QuickStartTutorialsDocumentationIntegrationsAPI ReferencePricingGet Started!
Documentation
LoginRegister

How to setup a basic IVR using Conversation API

Suggest Edits

With the conversation API, you are able to set up an IVR system.
Your audience is able to interact with your system through the use of DTMF tones. According to the received DTMF tones, you can change dynamically the dial plan of the call (eg connect your client with the requested department, play a prerecorded voice message, give instructions by using Text to Speech).
Take input, process it according to your needs and return a new custom dial plan to be executed.
Custom dial plans can be created comprising of different sets of actions (defined by action verbs) able to facilitate every need.

Example of a basic IVR:

In this example, your client will receive a call from your system. After hearing a welcome message, your client is able to choose between connecting with a sales representative, or technical support, or hearing prerecorded instructions.

https://connect.routee.net/voice/conversation

Your Header should contain authorization and content type:

KEYVALUE
AuthorizationBearer {access_token}
Content-Typeapplication/json

The example request is shown below:

curl -X POST \
  https://connect.routee.net/voice/conversation \
  -H 'authorization: Bearer 466e0eec-04c6-450e-8017-3aec2884b37a' \
  -H 'content-type: application/json' \
  -d '{
  "from": "AMDTelecom",
  "to": {
    "phone": "+306948xxxxxx"
  },
  "dialPlan": {
    "verbs": [
      {
        "type": "SAY",
        "message": {
          "language": "en-GB",
          "gender": "female",
          "text": "Hello. You received a call from AMD telecom. Thank you for your interest. Please choose from the following menu options:"
        }
      },
      {
        "type": "SAY",
        "message": {
          "language": "en-GB",
          "gender": "female",
          "text": "To speak with a sales representative, press 1."
        },
        "bargeIn": true
      },
      {
        "type": "PAUSE",
        "duration": 3
      },
      {
        "type": "SAY",
        "message": {
          "language": "en-GB",
          "gender": "female",
          "text": "For technical support, press 2."
        },
        "bargeIn": true
      },
      {
        "type": "PAUSE",
        "duration": 3
      },
      {
        "type": "COLLECT",
        "eventUrl": "http://xxxxxxxxxxxxxx.xxx"
      }
    ]
  }
}'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{  \n   \"from\":\"AMDTelecom\",\n   \"to\":{  \n      \"phone\":\"+306948xxxxxx\"\n   },\n   \"dialPlan\":{  \n      \"verbs\":[  \n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"Hello. You received a call from AMD telecom. Thank you for your interest. Please choose from the following menu options:\"\n            }\n         },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"To speak with a sales representative, press 1.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"For technical support, press 2.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"COLLECT\",\n            \"eventUrl\":\"http://xxxxxxxxxxxxxx.xxx\"\n         }\n      ]\n   }\n}");
Request request = new Request.Builder()
  .url("https://connect.routee.net/voice/conversation")
  .post(body)
  .addHeader("authorization", "Bearer 466e0eec-04c6-450e-8017-3aec2884b37a")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var client = new RestClient("https://connect.routee.net/voice/conversation");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("authorization", "Bearer 466e0eec-04c6-450e-8017-3aec2884b37a");
request.AddParameter("undefined", "{  \n   \"from\":\"AMDTelecom\",\n   \"to\":{  \n      \"phone\":\"+306948xxxxxx\"\n   },\n   \"dialPlan\":{  \n      \"verbs\":[  \n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"Hello. You received a call from AMD telecom. Thank you for your interest. Please choose from the following menu options:\"\n            }\n         },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"To speak with a sales representative, press 1.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"For technical support, press 2.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"COLLECT\",\n            \"eventUrl\":\"http://xxxxxxxxxxxxxx.xxx\"\n         }\n      ]\n   }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://connect.routee.net/voice/conversation",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{  \n   \"from\":\"AMDTelecom\",\n   \"to\":{  \n      \"phone\":\"+306948xxxxxx\"\n   },\n   \"dialPlan\":{  \n      \"verbs\":[  \n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"Hello. You received a call from AMD telecom. Thank you for your interest. Please choose from the following menu options:\"\n            }\n         },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"To speak with a sales representative, press 1.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"For technical support, press 2.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"COLLECT\",\n            \"eventUrl\":\"http://xxxxxxxxxxxxxx.xxx\"\n         }\n      ]\n   }\n}",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer 466e0eec-04c6-450e-8017-3aec2884b37a",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import http.client

conn = http.client.HTTPSConnection("connect.routee.net")

payload = "{  \n   \"from\":\"AMDTelecom\",\n   \"to\":{  \n      \"phone\":\"+306948xxxxxx\"\n   },\n   \"dialPlan\":{  \n      \"verbs\":[  \n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"Hello. You received a call from AMD telecom. Thank you for your interest. Please choose from the following menu options:\"\n            }\n         },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"To speak with a sales representative, press 1.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"For technical support, press 2.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"COLLECT\",\n            \"eventUrl\":\"http://xxxxxxxxxxxxxx.xxx\"\n         }\n      ]\n   }\n}"

headers = {
    'authorization': "Bearer 466e0eec-04c6-450e-8017-3aec2884b37a",
    'content-type': "application/json"
    }

conn.request("POST", "/voice/conversation", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://connect.routee.net/voice/conversation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Bearer 466e0eec-04c6-450e-8017-3aec2884b37a'
request["content-type"] = 'application/json'
request.body = "{  \n   \"from\":\"AMDTelecom\",\n   \"to\":{  \n      \"phone\":\"+306948xxxxxx\"\n   },\n   \"dialPlan\":{  \n      \"verbs\":[  \n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"Hello. You received a call from AMD telecom. Thank you for your interest. Please choose from the following menu options:\"\n            }\n         },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"To speak with a sales representative, press 1.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"For technical support, press 2.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"COLLECT\",\n            \"eventUrl\":\"http://xxxxxxxxxxxxxx.xxx\"\n         }\n      ]\n   }\n}"

response = http.request(request)
puts response.read_body

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://connect.routee.net/voice/conversation",
  "method": "POST",
  "headers": {
    "authorization": "Bearer 466e0eec-04c6-450e-8017-3aec2884b37a",
    "content-type": "application/json"
  },
  "processData": false,
 "data": "{  \n   \"from\":\"AMDTelecom\",\n   \"to\":{  \n      \"phone\":\"+306948xxxxxx\"\n   },\n   \"dialPlan\":{  \n      \"verbs\":[  \n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"Hello. You received a call from AMD telecom. Thank you for your interest. Please choose from the following menu options:\"\n            }\n         },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"To speak with a sales representative, press 1.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"SAY\",\n            \"message\":{  \n               \"language\":\"en-GB\",\n               \"gender\":\"female\",\n               \"text\":\"For technical support, press 2.\"\n            },\n            \"bargeIn\":true\n         },\n         {\n  \t\t\t\t\t\"type\":\"PAUSE\",\n  \t\t\t\t\t\"duration\": 3\n\t\t\t\t },\n         {  \n            \"type\":\"COLLECT\",\n            \"eventUrl\":\"http://xxxxxxxxxxxxxx.xxx\"\n         }\n      ]\n   }\n}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer 466e0eec-04c6-450e-8017-3aec2884b37a",
                           @"content-type": @"application/json";
NSDictionary *parameters = @{ @"from": @"AMDTelecom",
                              @"to": @{ @"phone": @"+306948xxxxxx" },
                              @"dialPlan": @{ @"verbs": @[ @{ @"type": @"SAY", @"message": @{ @"language": @"en-GB", @"gender": @"female", @"text": @"Hello. You received a call from AMD telecom. Thank you for your interest. Please choose from the following menu options:" } }, @{ @"type": @"SAY", @"message": @{ @"language": @"en-GB", @"gender": @"female", @"text": @"To speak with a sales representative, press 1." }, @"repeat":@1, @"bargeIn":@true }, @{ @"type": @"SAY", @"message": @{ @"language": @"en-GB", @"gender": @"female", @"text": @"For technical support, press 2."}, @"repeat": @1, @"bargeIn": @true } }, @{ @"type": @"SAY", @"message": @{ @"language": @"en-GB", @"gender": @"female", @"text": @"To hear prerecorded instructions, press 3." },  @"repeat": @1, @"bargeIn": @true }, @{ @"type": @"COLLECT", @"eventUrl": @"http://xxxxxxxxxxxxxx.xxx" } ] } };

NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://connect.routee.net/voice/conversation"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"POST"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];

With the "bargeIn" option of verbs set to true, the first DTMF tone during the verb will interrupt the dial plan.
In this case, a "COLLECT" verb is necessary, in order to provide to Routee the "eventUrl".
The eventUrl that you define, will be used to send you the DTMF tone that interrupted the dial.
As a response of the request to the eventUrl, Routee will be waiting to accept the new dial plan.

You will receive a payload as below:

{
   "from": "+3023xxxxxxx",
   "to": "+120xxxxxx",
   "messageId": "bd62d22e-dc10-48de-b696-45f63c6d0aad",
   "conversationTrackingId": "12fe3777-f32a-4350-996b-364018d457b5",
   "collectedTones": "2"
}

The only thing you have to do to change the dial plan, is to set your application to send as response to Routee the appropriate new dial plan in JSON format, according to the received collectedTones.

In this example, when "collectedTones" is "1", you may send a dial plan like:

{
  "verbs":[  
     {  
        "type":"SAY",
        "message":{  
           "language":"en-GB",
           "gender":"male",
           "text":"We will connect you shortly to a sales representative. Please hang on to your phone"
        }
     },
     {  
        "type":"DIAL",
        "from":"+306948xxxxxx",
        "to":{  
           "phone":"+306988xxxxxx"
        }
     }
  ]
}

When "collectedTones" is "2", you may send a dial plan like:

{
  "verbs":[  
     {  
        "type":"SAY",
        "message":{  
           "language":"en-GB",
           "gender":"male",
           "text":"We will connect you shortly to technical support. Please hang on to your phone"
        }
     },
     {  
        "type":"DIAL",
        "from":"+306948xxxxxx",
        "to":{  
           "phone":"+306933xxxxxx"
        }
     }
  ]
}

In the example payload above, the "collectedTones" is "2". So, your client will hear your message and then connect to technical support.

That's it! You have interacted with your client according to his needs.

Updated almost 6 years ago

What’s Next