The POST /invoke
endpoint allows you to create a new interaction and process it through an Interaction Plan.
Header parameters in Requests (Interactions API) apply to this endpoint.
Authorization scopes supported:
Scope | Access granted |
---|---|
interactions:write | Entire endpoint |
curl -L -X POST "https://***.api.newvoicemedia.com/interactions/invoke" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Accept: application/vnd.newvoicemedia.v1+json" \ -H "Content-Type: application/json" \ --data-raw "<JSON BODY>" |
{ "provider":"ProviderName", "requests":[ { "action":"dispatch", "requestid":"13141f79-79bb-4e4f-a7bc-a96f3a08d1bb", "externalid":"40a4b50f", "route":"APIRouting", "linkeddata":[ { "type":"clid", "value":"Cases 40a4b50f" }, { "type":"url", "label":"40a4b50f", "value":"https://vonage.com" }, { "type":"name", "value":"Case Friendly Name" }, { "type":"mediatype", "value":"Case-External" } ], "routingdata":{ "interactiontype":"nonlive", "personalqueue":{ "agent":"AgentUsername", "loggedintimeout":20, "loggedouttimeout":30 }, "skills":[ { "name":"skillOptional", "expiryafter":0 }, { "name":"skillExpiring", "expiryafter":60 }, { "name":"skillMandatory" } ] } } ] } |
provider
. (optional) The name of the provider that is used for the request. The provider must already have been registered using the POST /Register
endpoint.
Registering a provider enables you to receive callbacks when the interaction progresses through the Vonage platform. |
If you are using this endpoint to release an interaction that was dispatched with the name of a provider, |
requests
. (required) An array of Interaction
objects that can be either; routed through the interaction plan, with or without external parameters, or released from the system. Each object contains:
action
. (optional) The action associated with the Interaction
. Possible values are dispatch and release. Set to dispatch to route the interaction through the interaction plan. Set to release to release the interaction from the system. If you do not specify a value, action
defaults to dispatch.requestId
. (optional) Unique identifier of an Interaction
object. If two objects are found with the same requestId
, only the first one will be processed. This allows an integrator to send the same request more than once. (Subsequent Invoke requests relating to the interaction will contain a different Interaction
object with a different requestId
.)externalId
. (required - if action
is release) Unique identifier for the interaction. externalId
is optional if action
is dispatch. If you do not provide a value with a dispatch action, you will not be able to perform any future actions, such as release, on this interaction. We recommend that you provide an externalId
where possible, as this allows correlation between Vonage Contact Center (VCC) and the external system.route
. (required - if action
is dispatch) The named route you wish to invoke. VCC uses this value to locate the named route.linkeddata
. (optional) Dynamic settings used during the execution of a named route. There are several types of linkeddata
items. Different types have different additional properties.value
property. Maximum length of value
is 50 characters.value
property. Maximum length of value
is 50 characters.value
property. Maximum length of value
is 50 characters. Default value is ‘API Object’.label
and value
properties. If you do not provide a value
property, the label still appears.key
and value
properties. You can then refer to this key within the interaction plan. The linkeddata
property can contain multiple interactionproperty
items.routingdata
. (optional) Defines data useful for routing an interaction to an agent. All properties are optional:interactiontype
. Can be one of three values:
skills
. A list of skill objects matching those configured in VCC. The skills defined are added to the interaction. Each skill consists of:
name
. Reflects the name of the skill that the interaction will be tagged with. name
must match the name of a skill in VCC. name
is case-insensitive.expiryafter
. Defines a period of time for which skill is required measured in seconds. Maximum value is 2678399 seconds (31 days). 0 means that particular skill is optional. If not specified, the skill is mandatory.personalqueue
. A personal queue object defining the preferred agent for handling the interaction. personalqueue
consists of three required parameters:
agent
. The agent username to which interaction must be routed. agent
is case-insensitive.loggedintimeout
. The time (in seconds) for which personal queue settings are valid when agent is logged in. Maximum value is 2678399 seconds (31 days).loggedouttimeout
. The time (in seconds) for which personal queue settings are valid when the agent is logged out. Maximum value is 2678399 seconds (31 days).The SendSMS Interaction plan must be configured to use these properties within a Send SMS applet. |
{ "requests": [ { "route": "SendSMS", "linkeddata": [ {"type": "interactionproperty", "key": "ToNum", "value": "07700936658"}, {"type": "interactionproperty", "key": "FromNum", "value": "0654321"}, {"type": "interactionproperty", "key": "Message", "value": "Hello!"} ] } ] } |
In some applets you will need to specify an additional property from a list of data sources. If the data source name contains spaces, we cannot guarantee success when you use an |
{ "provider": "CrmIntegration", "requests": [ { "action": "dispatch", "requestid": "8762187187", "externalid": "ObjectId_001", "route": "CrmCallRouting", "linkeddata": [ {"type": "clid", "value": "+44123456789"}, {"type": "url", "label": "Click me", "value": "https://developer.newvoicemedia.com"} ], "routingdata": { "interactiontype" : "nonlive" } } ] } |
{ "provider": "CrmIntegration", "requests": [ { "action": "dispatch", "requestid": "8762187187", "externalid": "ObjectId_001", "route": "CrmCallRouting", "linkeddata": [ {"type": "clid", "value": "+44123456789"}, {"type": "url", "label": "Click me", "value": "https://developer.newvoicemedia.com"} ], "routingdata": { "interactiontype" : "nonlive", "skills": [ {"name": "skillOptional", "expiryafter": 0}, {"name": "skillExpiring", "expiryafter": 60}, {"name": "skillMandatory"} ] } } ] } |
{ "provider": "CrmIntegration", "requests": [ { "action": "dispatch", "requestid": "8762187187", "externalid": "ObjectId_001", "route": "CrmCallRouting", "linkeddata": [ {"type": "clid", "value": "+44123456789"}, {"type": "url", "label": "Click me", "value": "https://developer.newvoicemedia.com"} ], "routingdata": { "interactiontype" : "nonlive", "personalqueue": { "agent": "AgentUsername", "loggedintimeout": 20, "loggedouttimeout": 30 } } } ] } |
{ "requests": [ { "action": "release", "requestid": "8762187190", "externalid": "ObjectId_001" } ] } |
Successful requests return a 200 Success
code and an empty array:
[] |
Failed requests return a 200 Success
code and and an array entry for every requestId that failed:
[ "8762187190" ] |