How to route an interaction using the Interactions API (without registering a provider)

Before you start—some background reading

Before you make a start with using the Interactions API to route an interaction to an agent, you should familiarise yourself with using Vonage Contact Center (VCC) APIs.

Take a look at this guide which covers using the Vonage Contact Center Developer Portal, authenticating with VCC APIs, and using the API Explorer: Getting started with Vonage Contact Center APIs


Using the Interactions API’s Invoke action you can invoke interaction flows through one or more named routes within VCC. You can invoke an interaction flow through any interaction plan that you have configured in VCC’s Interaction Architect. Depending on the configuration of your interaction plan, you can perform a wide variety of tasks, such as:

  • Deliver the interaction to an agent
  • Send an SMS message using parameters passed within the request body
  • Send an email using data within VCC
  • Update a record in a third-party system

You can route an interaction with or without registering a provider first. If you register a provider, you can permit or restrict agent actions on an associated interaction or interactions, and, optionally, VCC can send notifications back to an API when an agent performs permitted actions. For information about registering a provider and using that provider when routing interactions, see How to register a provider and route interactions using the Interactions API.

Setting up your named route and applet in the VCC Admin Portal

Without a named route, you’ve got nothing to invoke, so your first task is to set up a named route, interaction plan and one or more applets using Interaction Architect in the VCC Admin Portal. For information about using Interaction Architect to create named routes and interaction plans, see Interaction Architect.

What is a named route/interaction plan/applet?

You can think of a named route as the address of an interaction plan. Without an address, your request wouldn’t know where to go.

An interaction plan is a collection of one of more applets that contain the description of what to do with your request. When your request reaches the target named route, it goes to the plan’s initial applet.

The applet or applets in your interaction plan determine what happens when your request travels through the interaction plan. In this example, the applet in your interaction plan routes an interaction to an agent.

Example named route

In the following example, there is just one named route Route Interaction NR. The Route Interaction NR named route has one applet, Route Interaction applet, which is an Automatic Call Distributor (ACD) applet in skills based routing (or UCD) mode. The Route Interaction applet is set as the initial applet.

Route Interaction Named Route

Example applet

In the following example, the Route Interaction applet routes the interaction to the agent who has been waiting longest. In a more complex interaction plan, configured skills and service level agreements, and other settings in the ACD applet, would also affect the routing.

For more information about the ACD applet, see Automatic Call Distributor (ACD) or Universal Contact Distributor (UCD) applet.

Route Interaction Applet

Preparing your request

Right, so you know how to use VCC APIs, and you’ve got your interaction plan set up in the VCC Admin Portal… Finally you can get started with using the Interactions API.

Currently there are just two actions in the Interactions API: Invoke and Register. We can ignore the Register action at this point. The Invoke action’s endpoint—POST /Invoke—invokes an interaction plan, located using the named route you specify.

Request URL

The format for the POST /Invoke request URL is:


Request parameters

The POST /Invoke endpoint requires the following parameters:

  • accept. The accept header parameter must contain a string that represents the version of the API you want to call and the content-type of the response. The content-type of the Interactions API’s responses is always JSON.
    Example application/vnd.newvoicemedia.v1+json

  • authorization. The authorization header parameter must contain your bearer access token. Your bearer access token is a string that identifies you to the API and proves that you are allowed to submit the request. You can obtain a bearer access token from the Authentication API. For information about getting and using your bearer access token, see How to authenticate with a Vonage Contact Center API.
    Example Bearer 24d80e703a037349cb4818cf7ec695cc

  • content-type. The content-type header parameter must contain a string that represents type of the content you are sending in the body of the request.
    Example application/json

  • Invocation. The Invocation body parameter must contain the properties necessary to invoke a named route and provide everything the interaction plan needs to execute. These properties are contained within an Invocation object.

Invocation object

The Invocation is a JSON object that contains two properties:

  • provider. You can ignore this property at the moment.
  • requests. Required The requests property contains one or more Interaction objects which, in turn, contain further properties. The example uses the following properties to route the interaction:
    • action. The action you want to perform with the request. Allowed values are dispatch and release.
    • requestid. Unique identifier of a request.
    • externalid. Unique identifier of the interaction. The externalid might be the same as a record ID in the source system. Without an externalid you will not be able to identify and perform any future actions, such as release, on this interaction.
    • route. The named route you wish to invoke. Specify the target named route. VCC uses the value to locate the named route.
    • routingdata. Use routingdata to provide any data useful for routing an interaction to an agent.
      • interactiontype. interactiontype labels the interaction as a live (call, for example), nonlive (email, for example), or chat (web chat, for example) type interaction.

Using the example above, provide the following information in your Interaction object:

Property Value
action dispatch
route Route Interaction NR
requestid uniqueRequestId
externalid sourceObjectName
interactiontype (within routingdata) nonlive

Example Invocation object

  		"action": "dispatch",
  		"requestid": "uniqueRequestId",
  		"externalid": "sourceObjectName",
  		"route": "Route Interaction NR",
  			"interactiontype" : "nonlive"

Putting it all together

Using a tool for making API requests, send the required parameters in your request.

Example request

The bearer access token has been replaced with <access_token>.

  -H "accept: application/vnd.newvoicemedia.v1+json"
  -H "authorization: Bearer <access_token>"
  -H "content-type: application/json"
  -d '{
    		"action": "dispatch",
    		"requestid": "uniqueRequestId",
    		"externalid": "sourceObjectName",
    		"route": "Route Interaction NR",
    			"interactiontype" : "nonlive"

This example sends a request to the /Invoke end point, passing in the required headers and the Invocation object. The object contains a single Interaction object. The request invokes the interaction plan that contains just the Route Interaction applet applet. The Route Interaction applet assigns a nonlive interaction defined in the Interaction object to the longest waiting agent.

If our request is successful, we will receive a 200 Success response.

Because we provided a value in externalid, we can later send a second POST /Invoke request to release the interaction. See How to release an existing interaction using the Interactions API to find out how to release the interaction.