How to sent a pin number efficiently using Voice Conversation

The voice conversation resource can be used to send PIN numbers to your customers. Below is an example of how to sent PINs to phone number efficiently.

First, your application makes an HTTP request to the /conversation resource as follows:

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

Your Header should contain authorization and content type:

KEY	VALUE
Authorization	Bearer {access_token}
Content-Type	application/json

An example request is shown below:

curl -X POST \
  https://devconnect.routee.net/voice/conversation \
  -H 'authorization: Bearer {accessToken}' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "from": "+123456",
  "to": {
    "phone": "+306990000000"
  },
  "dialPlan": {
    "verbs": [{
      "type": "PAUSE",
      "duration": 3
    }, {
      "type": "SAY",
      "message": {
        "language": "en-US",
        "gender": "female",
        "text": "Your pin code is: 1. 2. 3. 4."
      },
      "bargeIn": true
    }, {
      "type": "PAUSE",
      "duration": 2
    }, {
      "type": "SAY",
      "message": {
        "language": "en-US",
        "gender": "female",
        "text": "Your pin code is: 1. 2. 3. 4. If you wish to hear the message again, Please press 1."
      },
      "bargeIn": true
    }, {
      "type": "PAUSE",
      "duration": 3
    }, {
      "type": "COLLECT",
      "eventUrl": "https://example.com"
    }]
  }
}'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"from\": \"+123456\",\n  \"to\": {\n    \"phone\": \"+306990000000\"\n  },\n  \"dialPlan\": {\n    \"verbs\": [{\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 2\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4. If you wish to hear the message again, Please press 1.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"COLLECT\",\n      \"eventUrl\": \"https://example.com\"\n    }]\n  }\n}");
Request request = new Request.Builder()
  .url("https://devconnect.routee.net/voice/conversation")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer {accessToken}")
  .addHeader("cache-control", "no-cache")
  .build();

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

var client = new RestClient("https://devconnect.routee.net/voice/conversation");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("authorization", "Bearer {accessToken}");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\n  \"from\": \"+123456\",\n  \"to\": {\n    \"phone\": \"+306990000000\"\n  },\n  \"dialPlan\": {\n    \"verbs\": [{\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 2\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4. If you wish to hear the message again, Please press 1.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"COLLECT\",\n      \"eventUrl\": \"https://example.com\"\n    }]\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

<?php

$request = new HttpRequest();
$request->setUrl('https://devconnect.routee.net/voice/conversation');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'cache-control' => 'no-cache',
  'authorization' => 'Bearer {accessToken}',
  'content-type' => 'application/json'
));

$request->setBody('{
  "from": "+123456",
  "to": {
    "phone": "+306990000000"
  },
  "dialPlan": {
    "verbs": [{
      "type": "PAUSE",
      "duration": 3
    }, {
      "type": "SAY",
      "message": {
        "language": "en-US",
        "gender": "female",
        "text": "Your pin code is: 1. 2. 3. 4."
      },
      "bargeIn": true
    }, {
      "type": "PAUSE",
      "duration": 2
    }, {
      "type": "SAY",
      "message": {
        "language": "en-US",
        "gender": "female",
        "text": "Your pin code is: 1. 2. 3. 4. If you wish to hear the message again, Please press 1."
      },
      "bargeIn": true
    }, {
      "type": "PAUSE",
      "duration": 3
    }, {
      "type": "COLLECT",
      "eventUrl": "https://example.com"
    }]
  }
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

import http.client

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

payload = "{\n  \"from\": \"+123456\",\n  \"to\": {\n    \"phone\": \"+306990000000\"\n  },\n  \"dialPlan\": {\n    \"verbs\": [{\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 2\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4. If you wish to hear the message again, Please press 1.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"COLLECT\",\n      \"eventUrl\": \"https://example.com\"\n    }]\n  }\n}"

headers = {
    'content-type': "application/json",
    'authorization': "Bearer {accessToken}",
    'cache-control': "no-cache",
    }

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://devconnect.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["content-type"] = 'application/json'
request["authorization"] = 'Bearer {accessToken}'
request["cache-control"] = 'no-cache'
request.body = "{\n  \"from\": \"+123456\",\n  \"to\": {\n    \"phone\": \"+306990000000\"\n  },\n  \"dialPlan\": {\n    \"verbs\": [{\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 2\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4. If you wish to hear the message again, Please press 1.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"COLLECT\",\n      \"eventUrl\": \"https://example.com\"\n    }]\n  }\n}"

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

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://devconnect.routee.net/voice/conversation",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "authorization": "Bearer {accessToken}",
    "cache-control": "no-cache",
  },
  "processData": false,
  "data": "{\n  \"from\": \"+123456\",\n  \"to\": {\n    \"phone\": \"+306990000000\"\n  },\n  \"dialPlan\": {\n    \"verbs\": [{\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 2\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4. If you wish to hear the message again, Please press 1.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"COLLECT\",\n      \"eventUrl\": \"https://example.com\"\n    }]\n  }\n}"
}

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

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://devconnect.routee.net/voice/conversation",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "authorization": "Bearer {accessToken}",
    "cache-control": "no-cache",
  },
  "processData": false,
  "data": "{\n  \"from\": \"+123456\",\n  \"to\": {\n    \"phone\": \"+306990000000\"\n  },\n  \"dialPlan\": {\n    \"verbs\": [{\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 2\n    }, {\n      \"type\": \"SAY\",\n      \"message\": {\n        \"language\": \"en-US\",\n        \"gender\": \"female\",\n        \"text\": \"Your pin code is: 1. 2. 3. 4. If you wish to hear the message again, Please press 1.\"\n      },\n      \"bargeIn\": true\n    }, {\n      \"type\": \"PAUSE\",\n      \"duration\": 3\n    }, {\n      \"type\": \"COLLECT\",\n      \"eventUrl\": \"https://example.com\"\n    }]\n  }\n}"
}

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

When any key is pressed, Routee will immediately submit to the eventUrl the collected tones, the conversation id, and the message id.

You will receive a payload as below:

{
  "messageId": "bd62d22e-dc10-48de-b696-45f63c6d0aad",
  "conversationTrackingId": "12fe3777-f32a-4350-996b-364018d457b5",
  "collectedTones": "1"
}

Routee waits as a response of the above request, a valid dial plan in JSON format.
So, your client can hear the PIN code again.
For example:

{
    "verbs": [
        {
            "type": "SAY",
            "message": {
                "language": "en-US",
                "gender": "female",
                "text": "Your pin code is: 1 2 3 4"
            }
        },
        {
            "type": "PAUSE",
            "duration": 3
        }
    ]
}

More information on dial plan verbs here
More information on Voice Conversation resource here
More information on Voice Conversation Webhooks here
More information on Languages supported here