How to accept a pin number using the IVR system

The Interactive Voice Response System can be used to accept or decline a pin number.
According to the received accepted or declined pin number, you can change dynamically the dial plan of the call.

Example of a simple IVR system which accepts a pin number:

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://connect.routee.net/voice/conversation \
  -H 'authorization: Bearer a783eea8-18ce-442f-a10d-ab1b59f75794' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "from": "Company Name",
  "to": {
    "phone": "+30691111111"
  },
  "dialPlan": {
    "verbs": [
      {
        "type": "SAY",
        "message": {
          "language": "en-GB",
          "gender": "female",
          "text": "Please enter your four digits service number and then press the pound key."
        }
      },
      {
        "type": "PAUSE",
        "duration": 10
      },
      {
        "type": "COLLECT",
        "eventUrl": "http://www.example.com",
        "maxDigits": 4,
        "submitOnHash": true
      }
    ]
  }
}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"from\":\"Company Name\",\n  \"to\":{\"phone\":\"+30691111111\"},\n  \"dialPlan\": {\n      \"verbs\":[\n        {\n        \t\"type\": \"SAY\",\n          \"message\": {\n          \t\"language\": \"en-GB\",\n            \"gender\": \"female\",\n            \"text\": \"Please enter your four digits service number and then press the pound key.\"\n          }\n        },\n        {\n        \t\"type\":\"PAUSE\",\n          \"duration\": 10\n        },\n        {\n           \"type\": \"COLLECT\",\n\t\t\t     \"eventUrl\": \"http://www.example.com\",\n           \"maxDigits\": 4,\n           \"submitOnHash\": true\n        }\n      ]\n  }\n}");
Request request = new Request.Builder()
  .url("https://connect.routee.net/voice/conversation")
  .post(body)
  .addHeader("authorization", "Bearer a783eea8-18ce-442f-a10d-ab1b59f75794")
  .addHeader("content-type", "application/json")
  .addHeader("cache-control", "no-cache")
  .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("cache-control", "no-cache");
request.AddHeader("content-type", "application/json");
request.AddHeader("authorization", "Bearer a783eea8-18ce-442f-a10d-ab1b59f75794");
request.AddParameter("undefined", "{\n  \"from\":\"Company Name\",\n  \"to\":{\"phone\":\"+30691111111\"},\n  \"dialPlan\": {\n      \"verbs\":[\n        {\n        \t\"type\": \"SAY\",\n          \"message\": {\n          \t\"language\": \"en-GB\",\n            \"gender\": \"female\",\n            \"text\": \"Please enter your four digits service number and then press the pound key.\"\n          }\n        },\n        {\n        \t\"type\":\"PAUSE\",\n          \"duration\": 10\n        },\n        {\n           \"type\": \"COLLECT\",\n\t\t\t     \"eventUrl\": \"http://www.example.com\",\n           \"maxDigits\": 4,\n           \"submitOnHash\": true\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\":\"Company Name\",\n  \"to\":{\"phone\":\"+30691111111\"},\n  \"dialPlan\": {\n      \"verbs\":[\n        {\n        \t\"type\": \"SAY\",\n          \"message\": {\n          \t\"language\": \"en-GB\",\n            \"gender\": \"female\",\n            \"text\": \"Please enter your four digits service number and then press the pound key.\"\n          }\n        },\n        {\n        \t\"type\":\"PAUSE\",\n          \"duration\": 10\n        },\n        {\n           \"type\": \"COLLECT\",\n\t\t\t     \"eventUrl\": \"http://www.example.com\",\n           \"maxDigits\": 4,\n           \"submitOnHash\": true\n        }\n      ]\n  }\n}",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer a783eea8-18ce-442f-a10d-ab1b59f75794",
    "cache-control: no-cache",
    "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\":\"Company Name\",\n  \"to\":{\"phone\":\"+30691111111\"},\n  \"dialPlan\": {\n      \"verbs\":[\n        {\n        \t\"type\": \"SAY\",\n          \"message\": {\n          \t\"language\": \"en-GB\",\n            \"gender\": \"female\",\n            \"text\": \"Please enter your four digits service number and then press the pound key.\"\n          }\n        },\n        {\n        \t\"type\":\"PAUSE\",\n          \"duration\": 10\n        },\n        {\n           \"type\": \"COLLECT\",\n\t\t\t     \"eventUrl\": \"http://www.example.com\",\n           \"maxDigits\": 4,\n           \"submitOnHash\": true\n        }\n      ]\n  }\n}"


headers = {
    'authorization': "Bearer a783eea8-18ce-442f-a10d-ab1b59f75794",
    'content-type': "application/json",
    '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://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 a783eea8-18ce-442f-a10d-ab1b59f75794'
request["content-type"] = 'application/json'
request["cache-control"] = 'no-cache'
request.body = "{\n  \"from\":\"Company Name\",\n  \"to\":{\"phone\":\"+30691111111\"},\n  \"dialPlan\": {\n      \"verbs\":[\n        {\n        \t\"type\": \"SAY\",\n          \"message\": {\n          \t\"language\": \"en-GB\",\n            \"gender\": \"female\",\n            \"text\": \"Please enter your four digits service number and then press the pound key.\"\n          }\n        },\n        {\n        \t\"type\":\"PAUSE\",\n          \"duration\": 10\n        },\n        {\n           \"type\": \"COLLECT\",\n\t\t\t     \"eventUrl\": \"http://www.example.com\",\n           \"maxDigits\": 4,\n           \"submitOnHash\": true\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 a783eea8-18ce-442f-a10d-ab1b59f75794",
    "content-type": "application/json",
    "cache-control": "no-cache"
  },
  "processData": false,
  "data": "{\n  \"from\":\"Company Name\",\n  \"to\":{\"phone\":\"+30691111111\"},\n  \"dialPlan\": {\n      \"verbs\":[\n        {\n        \t\"type\": \"SAY\",\n          \"message\": {\n          \t\"language\": \"en-GB\",\n            \"gender\": \"female\",\n            \"text\": \"Please enter your four digits service number and then press the pound key.\"\n          }\n        },\n        {\n        \t\"type\":\"PAUSE\",\n          \"duration\": 10\n        },\n        {\n           \"type\": \"COLLECT\",\n\t\t\t     \"eventUrl\": \"http://www.example.com\",\n           \"maxDigits\": 4,\n           \"submitOnHash\": true\n        }\n      ]\n  }\n}"
}

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

When the pound 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,2,3,4"
}

Routee waits as response of the above request, a valid dial plan in JSON format.

For example:
So, your client will hear your message and then connect to technical support.

{
    "verbs":[  
     {  
        "type":"SAY",
        "message":{  
           "language":"en-GB",
           "gender":"female",
           "text":"You will shortly be connected to the first available representative"
        }
     },
     {  
        "type":"DIAL",
        "from":"+306948xxxxxx",
        "to":{  
           "phone":"+306988xxxxxx"
        }
     }
  ]
}

If the pin number is declined, you may send a dial plan as following:

{
  "verbs":[  
     {  
        "type":"SAY",
        "message":{  
           "language":"en-GB",
           "gender":"female",
           "text":"Your four digits service number is not valid. Please try again."
        }
     },
     {
        "type": "COLLECT",
        "eventUrl": "http://www.example.com",
        "maxDigits": 4,
        "submitOnHash": true
     }
  ]
}

Congratulations! You have just interacted with your client according to his pin number.