How to release an existing interaction using the Interactions API

Overview

Releasing an interaction using the Interactions API, removes (and effectively deletes) a not-yet-assigned interaction from VCC or ends the agent’s current relationship with it.

You can only release an interaction you previously routed using the POST /Invoke endpoint of the Interactions API. You must have assigned the interaction an externalid and made a note of it. The interaction’s externalid is a unique reference to it. For information about routing an interaction using the Interactions API, see How to route an interaction using the Interactions API (without registering a provider) or How to register a provider and route interactions using the Interactions API.

Preparing your request

Right, so you know how to use VCC APIs, and you’ve got an interaction waiting to be released… 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, and can be used to route an interaction through the plan or release an existing interaction from VCC.

Request URL

The format for the POST /Invoke request URL is:

https://***.api.newvoicemedia.com/interactions/Invoke

Request parameters

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.

Invocation object

The Invocation is a JSON object that contains two properties:

• provider. In this example, you are not releasing an interaction that was dispatched with the name of a provider. You can therefore ignore this property.

  Release action

  If you were using this endpoint to release an interaction that was dispatched with the name of a provider, provider would be required.

• 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.
  • requestid. Unique identifier of a request.
  • externalid. Unique identifier of the existing interaction. The externalid must have been set on the interaction when first routed using the POST /Invoke endpoint.

Using the example above, provide the following information in your Interaction object:

Example Invocation object

{
  "requests":
  [
    {
      "action": "release",
      "requestid": "uniqueRequestId",
      "externalid": "existingInteractionId",
    }
  ]
}

Putting it all together

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: accept: application/vnd.newvoicemedia.v1+json"
  -H "authorization: Bearer <access_token>"
  -H "content-type: application/json"
  -d '{
    "requests":
    [
      {
        "action": "release",
        "requestid": "uniqueRequestId",
        "externalid": "existingInteractionId",
      }
    ]
  }'
  "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 releases the interaction with the specified externalid from VCC or the assigned agent.

If our request is successful, we will receive a 200 Success response.