The POST /invoke
endpoint allows you to create a new interaction and process it through an Interaction Plan.
...
provider
. (optional) The name of the provider that is used for the request. The provider must already have been registered using thePOST /Register
endpoint.Tip Registering a provider enables you to receive callbacks when the interaction progresses through the Vonage platform.
Note title Release action If you are using this endpoint to release an interaction that was dispatched with the name of a provider,
provider
is mandatory.requests
. (required) An array ofInteraction
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 theInteraction
. 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 anInteraction
object. If two objects are found with the samerequestId
, 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 differentInteraction
object with a differentrequestId
.)externalId
. (required - ifaction
is release) Unique identifier for the interaction.externalId
is optional ifaction
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 anexternalId
where possible, as this allows correlation between Vonage Contact Center (VCC) and the external system.route
. (required - ifaction
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 oflinkeddata
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 ofvalue
is 50 characters. - name. The display name for the interaction which appears in ContactPad to distinguish interactions. Requires a corresponding
value
property. Maximum length ofvalue
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 ofvalue
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
andvalue
properties. If you do not provide avalue
property, the label still appears. - interactionproperty. A key-value pair for an additional property. Requires
key
andvalue
properties. You can then refer to this key within the interaction plan. Thelinkeddata
property can contain multipleinteractionproperty
items.
- clid. The identity of the caller which appears in ContactPad and is recorded against the interaction. Requires a corresponding
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).
...
Code Block | ||||
---|---|---|---|---|
| ||||
{ "requests": [ { "action": "release", "requestid": "8762187190", "externalid": "ObjectId_001" } ] } |
Responses
Successful response
Successful requests return a 200 Success
code and an empty array:
Code Block | ||||
---|---|---|---|---|
| ||||
[] |
Failed response
Failed requests return a 200 Success
code and and an array entry for every requestId that failed:
Code Block | ||||
---|---|---|---|---|
| ||||
[ "8762187190" ] |
...