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:
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.
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 Plans Architect.
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.
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.
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.
The format for the POST /Invoke request URL is:
https://***.api.newvoicemedia.com/interactions/Invoke |
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 (VCC) 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.
The Invocation is a JSON object that contains two properties:
provider. This property is not required in this example as you have not registered a provider.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. In this example, action must be dispatch. 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
{
"requests":
[
{
"action": "dispatch",
"requestid": "uniqueRequestId",
"externalid": "sourceObjectName",
"route": "Route Interaction NR",
"routingdata":
{
"interactiontype" : "nonlive"
}
}
]
}
|
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>.
curl
-X POST
-H "accept: application/vnd.newvoicemedia.v1+json"
-H "authorization: Bearer <access_token>"
-H "content-type: application/json"
-d '{
"requests":
[
{
"action": "dispatch",
"requestid": "uniqueRequestId",
"externalid": "sourceObjectName",
"route": "Route Interaction NR",
"routingdata":
{
"interactiontype" : "nonlive"
}
}
]
}'
"https://***.api.newvoicemedia.com/interactions/Invoke"
|
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.