Create inbound interaction

The POST /invoke endpoint allows you to create a new interaction and process it through an Interaction Plan.

In this page

Headers

Header parameters in Requests (Interactions API) apply to this endpoint.

Authorization scopes supported:

Scope	Access granted

Scope	Access granted
`interactions:write`	Entire endpoint

Requests

Example Request

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>"

Example body (Full dispatch)

{
   "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.
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.
- clid. The identity of the caller which appears in ContactPad and is recorded against the interaction. Requires a corresponding value property. Maximum length of value is 50 characters.
- name. The display name for the interaction which appears in ContactPad to distinguish interactions. Requires a corresponding value property. Maximum length of value is 50 characters.
- mediatype. The media type for the interaction, used to indicate the specific type of object being routed. The media type appears in ContactPad. Requires a corresponding value property. Maximum length of value is 50 characters. Default value is ‘API Object’.
- url. A URL that relates to the interaction. The URL appears ContactPad when the interaction is routed to an agent. Requires label and value properties. If you do not provide a value property, the label still appears.
- interactionproperty. A key-value pair for an additional property. Requires 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:
  - live for interactions requiring the full undivided attention of an agent; for example, a phone call
  - chat for interactions requiring immediate, but, perhaps, divided attention
  - nonlive for interactions not requiring continuous attention; for example, an email
- 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).

Dispatching and interaction with interaction properties to send an SMS

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 interactionproperty to set the value. Wherever possible, instead of setting the value of that data source using an interactionproperty in the request, use a Data Connector applet in your interaction plan to set the value.

Dispatching a case with a registered provider

{
    "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"
            }
        }
    ]
}

Dispatching a case with preset skills

{
    "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"}
                ]
            }
        }
    ]
}

Dispatching a case tagged with personal queue

{
    "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
                }
            }
        }
    ]
}

Releasing interaction from the system

{
    "requests":
    [
        {
            "action": "release",
            "requestid": "8762187190",
            "externalid": "ObjectId_001"
        }
    ]
}

Responses

Successful response

Successful requests return a 200 Success code and an empty array:

[]

Failed response

Failed requests return a 200 Success code and and an array entry for every requestId that failed:

[
    "8762187190"
]