Create an Allocation

An allocation request maps a set of numbers (a-party) to another set of numbers (b-party) using a Variable Virtual Number or a GreenVN.  Both parties can optionally have pins (any integer number, preferably limited to 6 digits) associated with the allocation to enable new callers (whose numbers were not passed in the allocation request) to join either party at any time by entering the pin when calling for the first time on the VN since it was allocated.  If the ‘usage’ parameter is set to ‘oneway’ in the request, only the a-party may call the b-party.  For ‘twoway’ usage, both parties can call each other using the GreenVN.

POST

https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn

Replace <your_sid> with your tenant ID The following are the POST parameters:

Parameter Name Mandatory/Optional Value / Description
connection_id mandatory Unique identifier for the specific mapping. This can be any random string.
aparty_numbers mandatory List of numbers in E164 format for one side of the allocation. In the event that the allocation is oneway, only these numbers will be able to connect to the other party.
bparty_numbers mandatory List of numbers in E164 format for the other side of the allocation. In the event that the allocation is two-way, these numbers can connect to the a_party using the greenvn.
aparty_pins optional List of pins to be used for unregistered aparty_caller. This can be any positive integer. We recommend using 4 digit pins (or any number easy to remember by the calling party such as their mobile numbers etc.)
bparty_pins optional

List of pins to be used for unregistered aparty_caller.This can be any positive integer. We recommend using 4 digit pins (or any number easy to remember by the calling party such as their mobile numbers etc.)

usage mandatory

“oneway” allocations only permit a-party callers to talk to the b-party. “twoway” allocations permit both sides to call the other.

strictness optional

If strictness is true, the allocation only performed if all specified conditions are met.  This includes the preferred greenvn, region, and number type. If strictness is off, a number is returned which satisfies most maximum possible preferences.

The default value is false.

preferences optional

preferences are a set of preferred options that the returned greenvn should satisfy.

  • greenvn (optional): To request a specific number to be allocated.
  • region (optional): To request a greenvn that belongs to a specific region. Valid values are: DL, MU, MH, WB, AP, TN, GJ, KA, KL, RJ, MP
  • pin_code(optional): To request a greenvn that belongs to one of the above regions, a pin code can be passed. Please note: If a pin code belongs to a region not present in the above list, we will return a VN from a region in the list that is closest to the passed pin code. 
  • type (optional): To request either a “mobile” or “landline” number as greenvn.

These can be satisfied based on the available greenvn’s in the account

Deallocation_policy
(optional)
optional

This parameter is used to schedule an automatic deallocation. If not set, default deallocation period (as in configuration) is used

  •  duration: Duration can be specified in any unit (d, m, s)  Eg: “20s”. If not set, default deallocation period configured in your account is used
flow_id
optional*

A unique identifier of the call flow, which is required to be associated with the VN, at the time of allocation.

*It is required in the allocation request, if there are multiple call flows created at the account level and the expectation is to associate a particular call flow to the allocated VN. 

curl -X POST \
 https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn \
 -H 'Authorization: Basic <your Auth string which is Base64 encoded version of “username:Password” string>' \
 -H 'Content-Type: application/json' \
 -H 'cache-control: no-cache' \
 -d '{
"aparty_numbers" : [
          "+919176226528", "+911234567891"
],
"bparty_numbers" : [
         "+918136966620"
],
"usage":"twoway",
"connection_id":"X1",
"deallocation_policy":{"duration":"600s"}
}'
var request = require("request");
var userName = "XXXXXXXXX";
var password = "YYYYYYYYY";
var accountSID = “ZZZZZZZZZ”;
var encoding = Buffer.from(userName + ':' + password).toString('base64');
var options = { method: 'POST' ,
  url: 'https://leadassist.exotel.in/v1/tenants/'+ accountSid + '/greenvn’ ,
  headers: 
   { 
     Authorization: 'Basic ' + encoding ,
     'Content-Type': 'application/json' ,
     ‘cache-control’: ‘no-cache’ 
   },
   body: 
   { 
      aparty_numbers: [‘+919176226528’,‘+911234567891’ ],
      bparty_numbers: [‘+918136966620’ ],
      usage: ‘twoway’,
      connection_id: ‘X1’,
      deallocation_policy: [
              duration: ‘600s’
       ]
   },
  json: true
};
request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body.error_data);
  console.log(body);
});
<?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$userName = "YYYYYYYYYY";
$password = “ZZZZZZZZZZ”;
$encoding = base64_encode($userName.":". $password);
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://leadassist.exotel.in/v1/tenants/" . $accountSid . "/greenvn" ,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => '{
                "aparty_numbers" : [ "+919176226528", "+911234567891"], 
               "bparty_numbers" : [ "+918136966620"],
               "usage":"twoway",
               "connection_id":"X1",
               "deallocation_policy": {"duration":"600s"}
   }',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding ,
    "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 requests, base64, json
accountSid = "XXXXXXXXX"
userName = "YYYYYYYYY"
Password = “ZZZZZZZZZ”
encoding = base64.b64encode(userName + ":" + password)
url = "https://leadassist.exotel.in/v1/tenants/"+accountSid+"/greenvn"
payload = json.dumps({ 
               "aparty_numbers" : ["+919176226528", "+911234567891"],
               "bparty_numbers" : ["+918136966620"],
               "usage":"twoway”,
               "connection_id":"X1",
               "deallocation_policy": {"duration":"600s"}
        })
headers = {
    'Content-Type': "application/json",
    'Authorization': "Basic " + encoding
          }
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
print(json.dumps(json.loads(response.text), indent = 4, sort_keys = True))
package main

import (
b64 "encoding/base64"
"fmt"
"io/ioutil"
"net/http"
"strings"
)

func main() {

accountSid := "XXXXXXXXX"
userName := "YYYYYYYY"
password := “ZZZZZZZZ”

// Encoding the userName and password to use in Authorization header
encoding := b64.StdEncoding.EncodeToString([]byte(userName + ":" + password))

url := "https://leadassist.exotel.in/v1/tenants/" + accountSid + "/greenvn"

payload := strings.NewReader(`{ 
                "aparty_numbers" : [ "+919176226528", "+911234567891"] , 
              "bparty_numbers" : [ "+918136966620"] ,
              "usage":"twoway” ,
              "connection_id":"X1" , 
              "deallocation_policy": {"duration":"600s"}
  }`)

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic "+encoding)

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)

fmt.Println(res)
fmt.Println(string(body))

}

HTTP Response:

  • On success, the HTTP response status code will be 200
  • The connection_id is the unique identifier of the allocation, and it will be referred in HTTP body will contain a JSON similar to the one below
{
  "success": true,
  "status": 200,
  "data": {
    "connection_id": "abcd12345",
    "aparty_numbers": [
      "+918660592ZZ2"
    ],
    "bparty_numbers": [
      "+91XXX543210X"
    ],
    "usage": "oneway|twoway",
    "state": "active",
    "green_vn": "+918012345678",
    "greenvn_id": "123456"
  }
}
[
    {
        "success": false,
        "status": 409,
        "code": 18,
        "message": "Allocation exists for this connection id.",
        "data": null
    }
]

Description of parameters mentioned in the above response:

Parameter Name Type & Value
success true or false. This shows whether the request succeeded or not.
status

 HTTP response code of your request

200: Successfully allocated

400: Bad Request (for example when deallocation request is sent after deallocation has already happened)

402: Unauthorized Request

429: Throttle limit exceeded

499: Response timeout exceeded

data

JSON array representing the response and contains the below parameters

  • connection _id: same string as passed in the allocation request
  • aparty_numbers: array containing the phone numbers mapped (in E164 format) as the A party of the connection
  • bparty_numbers: array containing the phone numbers mapped (in E164 format) as the B party of the connection
  • usage: “oneway” or “twoway” as defined in the allocation request
  • green_vn: The Exophone number (in E164 format) allocated to this request
  • greenvn_id: Unique identifier for the allocation. This is required for getting details of the allocation and deallocating
  • flow_id (optional): A unique identifier of the call flow associated to the allocated VN. It will be present in the response only if this parameter is passed in the request.
code

number: This parameter only comes in case of an error where the status returned in non-200. The list of possible error codes are as below:

 

0: Internal Service Error
1: GreenVN not found
2: Unsupported search filters
3: One or more Mandatory parameters missing
4: No free green VN unable allocate
5: Bad or missing parameters in request
7: Authentication failed or not provided
8: Permission denied to do this operation

9: Unsupported denied
13: Duplicate Filter Failed
14: Duplicate in request
15: Region not supported
16: Invalid number
17: Too many requests
18: Duplicate connection ID
19: Duplicate in group

state

This is the current state of the allocation which can have the following values

  • “active” - This is the state when the allocation is active
  • “vault” - This is the state when the allocation was deallocated

Delete an Allocation

A de-allocation request removes the mapping from the VN

DELETE

https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>

Replace <your_sid> with your tenant ID and <greenvn_id> with the same received in the allocation request

curl -X DELETE https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>

 

var request = require('request');
var options = {
url: 'https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>'
};
function callback(error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body);
}
}
request(options, callback);
 include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array();
$response = Requests::get('https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>', $headers);
import requests
requests.delete('https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>')
require 'net/http'
require 'uri'
uri = URI.parse("https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>")
response = Net::HTTP.get_response(uri)
# response.code
# response.body

HTTP Response:

  • On success, the HTTP response status code will be 200.
  • The HTTP response body will contain a JSON similar to the one below:
{
           "success": true,
           "status": 200,
           "data":{
                             "connection_id":"abcd12345",
                            "aparty_numbers":[
                                            "+000000000000”
                             ],
                            "bparty_numbers":[
                                            "+919876543210",
                             ],
            "usage":"oneway|twoway",            “state”: “vault”,
            "green_vn":"+918012345678",
            "greenvn_id":"123456"
           }
}

The parameters in the above request are same as described in the response of the allocation request.


Get Details of an Allocation

The details of an allocation can be retrieved using this method.

 

GET

https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>

Replace with your tenant ID and with the same received in the allocation request

curl -X GET https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>
var request = require('request');
var options = {
    url: 'https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>'
};
function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}
request(options, callback);
    
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array();
$response = Requests::get('https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>', $headers);
    
import requests
requests.get('https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>')
    
require 'net/http'
require 'uri'
uri = URI.parse("https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>")
response = Net::HTTP.get_response(uri)
# response.code
# response.body
    

HTTP Response:

  • On success, the HTTP response status code will be 200.
  • The HTTP response body will contain a JSON similar to the one below:
{
"success": true,
"status": 200,
"data":{
"connection_id":"abcd12345",
"aparty_numbers":[
"+000000000000”
],
"bparty_numbers":[
"+919876543210",
],
"usage":"oneway|twoway",
“state”: “active|vault”,
"green_vn":"+918012345678",
"greenvn_id":"123456"
}
}

The parameters in the above request are the same as described in the response of the allocation request.


Update Party Numbers & Pins New

This API allows to update following parameters in an existing active allocation:

  • A-party numbers
  • B-party numbers
  • A-party pins
  • B-party pins
  • Usage (can be changed from 'oneway' to 'twoway' and vice versa)

Other parameters will be inherited from the original allocation.

In the Update API request body, make sure that at least one of the A-party number or B-party number, is present.

A-party pin, B-party pin and usage are optional parameters and should be passed if intended to update.

PUT

https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>/call-party

Replace <your_sid> with your tenant ID.

Please refer 'Create a VN Allocation' (POST) API for details on request parameters.

curl --location --request PUT 'https://<your_api_key>:<your_api_token>@leadassist.exotel.in/v1/tenants/<account_sid>/greenvn/<greenvn_id>/call-party' \
--header 'Content-Type: application/json' \
--data-raw '{
    "aparty_numbers": [
        "+91995xxxx640", "+9199xxxx5641"
    ],
    
    "bparty_numbers": [
        "+91798xxxx840", "+91798xxxx841"
    ],
    "aparty_pins": [
        12340
    ],
    "bparty_pins": [
        2340
    ],
    "usage": "oneway|twoway"
}'
var request = require("request");
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64')

var options = { 
  	method: 'PUT',
    'url': 'https://leadassist.exotel.in/v1/tenants/'+accountSid+'/greenvn/<greenvn_id>/call-party',
    'headers': {
        'Authorization': 'Basic'+ encoding,
        'Content-Type': 'application/json'
    },
  body: JSON.stringify({"aparty_numbers":["+91995XXXXX40","+9199XXXXXX41"],"bparty_numbers":["+91798XXXXX40","+9179XXXX6841"],"aparty_pins":[12340],"bparty_pins":[2340],"usage":"oneway|twoway"})

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
<?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://leadassist.exotel.in/v1/tenants/'+$accountSid+'/greenvn/<greenvn_id>/call-party',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
    "aparty_numbers": [
        "+91995XXXXX40", "+9199XXXXXX41"
    ],
    "bparty_numbers": [
        "+91798XXXXX40", "+9179XXXX6841"
    ],
    "aparty_pins": [
        12340
    ],
    "bparty_pins": [
        2340
    ],
    "usage": "oneway|twoway"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic '+ $encoding,
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests, base64, json

accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://leadassist.exotel.in/v1/tenants/"+ accountSid+"/greenvn/<greenvn_id>/call-party"

payload = json.dumps({
    "aparty_numbers": [
        "+91995XXXXX40", "+9199XXXXXX41"
    ],
    "bparty_numbers": [
        "+91798XXXXX40", "+9179XXXX6841"
    ],
    "aparty_pins": [
        12340
    ],
    "bparty_pins": [
        2340
    ],
    "usage": "oneway|twoway"
})

headers = {
  'Authorization': 'Basic '+ encoding,
  'Content-Type': 'application/json'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)
package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
	"strings"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))
	url := "https://leadassist.exotel.in/v1/tenants/" + accountSid + "/greenvn/<greenvn_id>/call-party"

	payload := strings.NewReader(`{
		"aparty_numbers": [
			"+91995xxxx640", "+9199xxxx5641"
		],
		
		"bparty_numbers": [
			"+91798xxxx840", "+91798xxxx841"
		],
		"aparty_pins": [
			12340
		],
		"bparty_pins": [
			2340
		],
		"usage": "oneway|twoday"
	}`)

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic "+encoding)
	req.Header.Add("cache-control", "no-cache")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

HTTP Response:

  • On success, the HTTP response status code will be 200
  • The connection_id is the unique identifier of the original allocation, and it will be referred in HTTP body will contain a JSON similar to the one below
{
           "success": true,
           "status": 200,
           "data":{
                          "connection_id":"abcd12345",
                          "aparty_numbers":[
                                           "+91995xxxx640", "+9199xxxx5641"
                          ],
                          "bparty_numbers":[
                                           "+91798xxxx840", "+91798xxxx841"
                          ],
                          "aparty_pins": [
                                          12340
                          ],
                          "bparty_pins": [
                                          2340
                          ],
                          "usage":"oneway|twoway",
                          "state": "active",
                          "green_vn":"+918012345678",
                          "greenvn_id":"123456"
           }
}

Update GreenVN New

This API allows to update GreenVN in an existing active allocation. 

While placing the request for the new VN, the number and the region can also be provided as a preference. If requested, without a request body, Lead Assist system will allocate an available number from the VN pool.

Other parameters will be inherited from the original allocation and passed in the API response.

PUT

https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenvn_id>/vn

Replace <your_sid> with your tenant ID.

Please refer 'Create a VN Allocation' (POST) API for details on request parameters.

curl --location --request PUT 'https://<your_api_key>:<your_api_token>@leadassist.exotel.in/v1/tenants/<account_sid>/greenvn/<greenvn_id>/vn' \
--header 'Content-Type: application/json' \
--data-raw '{
    "strictness": "false",
    "preferences": {
        "greenvn": "+917205827365",
        "region": "KA",
        "number_type": "landline"
    }
}'
var request = require("request");
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64')

var options = { 
  	method: 'PUT',
    'url': 'https://leadassist.exotel.in/v1/tenants/'+accountSid+'/greenvn/<greenvn_id>/vn',
    'headers': {
        'Authorization': 'Basic'+ encoding,
        'Content-Type': 'application/json'
    },
  body: JSON.stringify({"strictness":"false","preferences":{"greenvn":"+9172xxxxxx65"}})

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
<?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://leadassist.exotel.in/v1/tenants/'+$accountSid+'/greenvn/<greenvn_id>/vn',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
    "strictness": "false",
    "preferences": {
        "greenvn": "+91720XXXXX65"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic '+ $encoding,
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests, base64, json

accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://leadassist.exotel.in/v1/tenants/"+ accountSid+"/greenvn/<greenvn_id>/vn"

payload = json.dumps({
    "strictness": "false",
    "preferences": {
        "greenvn": "+91720XXXXX65"
    }
})

headers = {
  'Authorization': 'Basic '+ encoding,
  'Content-Type': 'application/json'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)
package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
	"strings"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))
	url := "https://leadassist.exotel.in/v1/tenants/" + accountSid + "/greenvn/<greenvn_id>/vn"

	payload := strings.NewReader(`{
    "strictness": "false",
    "preferences": {
		"greenvn": "+9172xxxx7365",
		"region": "KA",
		"number_type": "landline"
    }
}`)

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic "+encoding)
	req.Header.Add("cache-control", "no-cache")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

HTTP Response:

  • On success, the HTTP response status code will be 200
  • The connection_id is the unique identifier of the original allocation, and it will be referred in HTTP body will contain a JSON similar to the one below
{
           "success": true,
           "status": 200,
           "data":{
                   "connection_id":"abcd12345",
                   "aparty_numbers":[
                                   "+919176226528", "+911234567891"
                                    ],
                   "bparty_numbers":[
                                   "+918136966620",
                                    ],
            "usage":"oneway|twoway",
            "state": "active",
            "green_vn":"+917205827365",
            "greenvn_id":"123456"
           }
}

Events Call Backs

There are multiple call backs that Lead Assist solution provides for the events happening on the allocation.

Call Event

On every call that happens in an allocation, Lead Assist will make a HTTP POST request to the specified endpoint with the call details. The HTTP body will consist of the following parameters as shown below:

Parameter Name

Type & Value

connection_id

connection_id that was part of the request.

call_sid

string; an alpha-numeric unique identifier of the call

greenvn

The VN on which the call landed.

greenvn_id

The unique identifier of the allocation.

from

The phone number that is calling into the allocation

to

The phone number that is being called out by the VN

call_type

This is the same as call type parameter passed in passthru applet. Read here.

start_time

Time in format YYYY-MM-DD HH:mm:ss; Start time of the call.

current_time

Time in format YYYY-MM-DD HH:mm:ss; Current time

dial_call_duration

Duration of the second leg of the call in seconds

recording_url

Link to the recording of the call conversation if enabled.

dial_call_status

Second leg status

{
 "start_time": "2021-01-19T19:17:03+50:30",
 "direction": "incoming",
 "source": "exotel",
 "dial_call_duration": "32",
 "connection_id": "YOUR_CONNECTION_ID",
 "dial_call_status": "completed",
 "greenvn": "+91804XXXX513",
 "recording_url": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/CALL_SID.mp3",
 "on_call_duration": "27",
 "greenvn_id": "d12638b6-28b8-488d-8cf3-c60619ac2280",
 "call_type": "completed",
 "call_sid": "53fa8e40bb1XXXXXXXXXX257c439151k",
 "to": "+91776XXXX969",
 "current_time": "2021-01-19T19:17:44+50:30",
 "from": "+91959XXXX342"
}

Call Event with Call Insights Enabled

In addition to the above parameters, Lead Assist will pass Call Insights data if a client chooses to subscribe to them. Please refer to this Support Article to get additional details. The below sample response shows the additional 'insights' nested JSON block that will be included when a client subscribes to Call Insights. Please reach out to your Account Manager to get it enabled.

{
"start_time": "2021-09-24 07:05:28",
"insights": {
"DisconnectedBy": "Caller",
"Status": "completed",
"DetailedStatus": "CALL_COMPLETED",
"RingingDuration": "4.58"
},
"direction": "incoming",
"source": "monotel",
"dial_call_duration": "11",
"connection_id": "Sample_ID",
"dial_call_status": "completed",
"greenvn": "+9120XXXXX531",
"on_call_duration": 4,
"recording_url": "null",
"greenvn_id": "6360bbb7-XXXX-410c-XXXX-0c6ec70cc442",
"call_type": "completed",
"call_sid": "8a4d92198hy678hgt0fd9c1f2063159o",
"to": "+9198XXXXX940",
"current_time": "2021-09-24 07:05:44",
"from": "+91XXXXX99814"
}

Deallocation Callback Event

When deallocation of GreenVN is triggered via the deallocation policy as defined in the Allocation API, this callback will be triggered to let the user know that the deallocation has happened. The callback won’t be triggered if the user calls the deallocation API.

Parameter 

Description

connection_id

connection_id that was part of the request

greenvn

The VN that is allocated

greenvn_id

The unique identifier of the allocation.

usage

. usage as provided in allocation API (default twoway)

aparty_numbers

List of aparty numbers as provided in allocation api

bparty_numbers

List of bparty numbers as provided in allocation api

aparty_pins

List of aparty pins  as provided in allocation api

bparty_pins

List of bparty pins as provided  in allocation api

state

This is the current state of the allocation which can have the following values

  • “active” - The state when the allocation is active
  • “vault” - The state when the allocation was deallocated

 

{
   "connection_id": "YOUR_CONNECTION_ID",
   "aparty_numbers": [
       "+917317678172"
   ],
   "bparty_numbers": [
       "+918400047000"
   ],
   "aparty_pins": [null],
   "bparty_pins": [null],
   "usage": "twoway",
   "state": "vault",
   "greenvn": "+91983XXXX195",
   "greenvn_id": "fffe1797-b738-483f-a5a6-757ddfb15e78"
}

Successful Verification Event

If an unregistered caller calls a VN, he will be prompted to enter the pin number.  If the user identifies himself with the correct pin, we connect him to the other party.  This will trigger an HTTP POST request to a specified endpoint with the HTTP body containing the following parameters.

Parameter Name Type & Value
connection_id connection id to which the new user has been added.
greenvn the VN to which the new user has been added.
greenvn_id the unique identifier of the allocation to which the user has been added
caller the phone number of the new user.
pin Pin entered by the user.

Failed Verification Event

If an unregistered caller fails to verify himself (incorrect pin entry etc.), a failed verification event is triggered.

Parameter Name Type & Value
call_sid Unique identifier of the call made by the caller to the VN
greenvn The GreenVN to which the caller called
start_time Time in format YYYY-MM-DD HH:mm:ss; Start time of the call.
caller The phone number of the new user.
pin Pin entered by the user.

Appendix 1

List of status codes and their definition:

Status Code Description Http code
0 Internal Service Error 500
1 Could not find the given GreenVN 404
2 One or more unsupported search filters provided 400
3 One or more mandatory parameters not present in request 400
4 No free GreenVNs are available for allocation 452
5 Bad or missing parameters in Request 400
7 Authentication not provided or failed 401
8 Not permitted to do this operation. 403
9 Version header not specified or supported for this API 400
13 All numbers in the group are duplicates 409
14 a-party numbers and b-party numbers cannot contain the same number for an allocation. 409
15 The region code specified is not supported 403
16 Invalid Number Received. 400
17 Too many allocation requests in bulk. 413
18 Allocation exists for this connection id 409
19 One or more of the numbers is already registered with another pin 409
20 Group and number mapping doesn't exist 404
22 This greenvn is already deleted 410
23 An invalid date range was provided in the query 400
50 An invalid call flow is configured 422