Invoke requests

Request body parameters

Currently the Invoke action contains one endpoint: POST /Invoke. The POST /Invoke endpoint requires one parameter:

Invocation

Required To call the POST /Invoke endpoint, you must provide a Invocation object. The Invocation is a JSON object that defines two properties:

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:

  • routed through the interaction plan, with or without external parameters
  • released from the system

You can provide multiple Interaction objects in a single Invocation.

Interaction

Required To route or release interactions, provide an Interaction object for each interaction.
The Interaction is a JSON object, defined by following properties:

  • action
  • requestId
  • externalId
  • route
  • linkeddata
  • routingdata

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.

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.

Example: linkeddata in routing an interaction representing a twitter conversation

"linkeddata":
      [
        {"type": "clid", "value": "@someone123"},
        {"type": "name", "value": "Someone"},
        {"type": "mediatype", "value": "Twitter"},
        {"type": "url", "label": "Click me", "value": "https://developer.newvoicemedia.com"}
      ]

Example: linkeddata for passing external data to an interaction plan

"linkeddata":
      [
        {"type": "interactionproperty", "key": "ToNum", "value": "+44987654321"},
        {"type": "interactionproperty", "key": "FromNum", "value": "+44123456789"},
        {"type": "interactionproperty", "key": "Message", "value": "Hello!"}
      ]

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).

Usage examples

Example 1: Routing SMS

{
  "requests":
  [
    {
      "route": "SendSMS",
      "linkeddata":
      [
        {"type": "interactionproperty", "key": "ToNum", "value": "07700936658"},
        {"type": "interactionproperty", "key": "FromNum", "value": "0654321"},
        {"type": "interactionproperty", "key": "Message", "value": "Hello!"}
      ]
    }
  ]
}

Example 2: Routing non-live interaction

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

Example 3: Routing non-live interaction tagged with 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"}
                ]
            }
        }
    ]
}

Example 4: Routing non-live interaction 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
                }
            }
        }
    ]
}

Example 5: Releasing interaction from the system

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