How to send an SMS message using the Interactions API

Owned by Helen Griffith
Last updated: Jun 13, 2023
4 min read
In this page

Setting up your named route and Send SMS applet in the VCC Admin Portal

Without a named route, you’ve got nothing to invoke, so your first task is to set up a named route, interaction plan and one or more applets using Interaction Architect in the VCC Admin Portal. For information about using Interaction Architect to create named routes and interaction plans, see Interaction Plans Architect.

What is a named route/interaction plan/applet?

You can think of a named route as the address of an interaction plan. Without an address, your request wouldn’t know where to go.

An interaction plan is a collection of one of more applets that contain the description of what to do with your request. When your request reaches the target named route, it goes to the plan’s initial applet.

The applet or applets in your interaction plan determine what happens when your request travels through the interaction plan. In this example, the applet in your interaction plan sends an SMS message.

Example named route

In the following example, there is just one named route Send SMS NR. The Send SMS NR named route has just one applet, Send SMS applet, which is of Send SMS type. The Send SMS applet is set as the initial applet.

Send Sms Named Route

Example Send SMS applet

In the following example, the Send SMS applet sends an SMS to the telephone number specified in the data source named CustomerMobile. The destination country is defined in a data source named CustomerCountry. The message contains the text “Message from” followed by the value in the data source ContactName.

For more information about the Send SMS applet, see Send SMS applet.

Send Sms Applet

Preparing your request

Right, so you know how to use VCC APIs, and you’ve got your interaction plan set up in the VCC Admin Portal… 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 the interaction plan you specify.

Request URL

The generic 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. Ignore this property.
  • requests. Required The requests property contains one or more Interaction objects which, in turn, contain further properties. You only need the following properties to send an SMS:
    • route. The named route you wish to invoke. Specify the target named route. VCC uses the value to locate the named route.
    • linkeddata. Dynamic settings used during the execution of your named route. Specify additional values as required in key-value pairs where the key matches the name of an expected value in the interaction plan. Set the type of these key-value pairs to property.
      Provide each additional property in the following format: "type": "interactionproperty", "key": "propertyName", "value": "propertyValue"

Using the example above, the route property in your Interaction object must contain the name of the named route—Send SMS NR—and the linkeddata requires key-value pairs representing the following data sources:

  • CustomerMobile. The value of CustomerMobile must be a valid telephone number in national or international format.
  • CustomerCountry. The value of CustomerCountry must be the three character ISO country code for the destination country.
  • ContactName.

Example Invocation object

{
  "requests":
  [
    {
      "route": "Send SMS",
      "linkeddata":
      [
        {"type": "interactionproperty", "key": "CustomerMobile", "value": "01234567890"},
        {"type": "interactionproperty", "key": "CustomerCountry", "value": "GBR"},
        {"type": "interactionproperty", "key": "ContactName", "value": "Joe Bloggs"}
      ]
    }
  ]
}

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":
  [
    {
      "route": "Send SMS",
      "linkeddata":
      [
        {"type": "interactionproperty", "key": "CustomerMobile", "value": "01234567890"},
        {"type": "interactionproperty", "key": "CustomerCountry", "value": "GBR"},
        {"type": "interactionproperty", "key": "ContactName", "value": "Joe Bloggs"}
      ]
    }
  ]
}'
  "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 request invokes the interaction plan that contains just the Send SMS applet applet. Send SMS applet uses the key-value pairs in linkeddata to determine where to send the SMS and the message to include.

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