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 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.
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.
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
. Theaccept
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.
Exampleapplication/vnd.newvoicemedia.v1+json
authorization
. Theauthorization
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 API.
ExampleBearer 24d80e703a037349cb4818cf7ec695cc
content-type
. Thecontent-type
header parameter must contain a string that represents type of the content you are sending in the body of the request.
Exampleapplication/json
Invocation
. TheInvocation
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 Therequests
property contains one or moreInteraction
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 thetype
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.