Whitelist API allows you to add your DND clients' phone numbers into the Exotel's system and hence allowing you to call them. Exotel maintains the list of phone numbers subscribed to TRAI regulated DND (Do Not Disturb) / NCPR (National Customer Preference Registry). In general, a phone number subscribed to DND should not be dialed for marketing/commercial calls. Exotel differentiates these as transactional calls and promotional calls.

This is how it works:

  • You use the Customer whitelist API and add your DND customers' numbers into the Whitelist
  • An SMS is automatically sent to these numbers asking them their permission for you to contact them. Sample SMS: You've registered with <Your-company-Name> and permitted us to call you. If this is not the case, please give a missed call to 09XXXXXXXX. Thank you!
  • You can choose the brand name that goes in the opt-in SMS (<Your-company-Name> in the above Sample SMS). You can edit this in the "Brand Name" field in the company info page
  • If the person does not want to receive calls from you, s/he can 'unsubscribe' by giving a missed call to a specified number (in a SMS). Following this you will not be able to call him/her.
  • Once you have 'whitelisted' a DND number, you can make outbound transactional calls to that number

Important: If more than 3 people 'unsubscribe', then the process for whitelisting will change. Now, instead of getting a number that is on DND to 'unsubscribe' by giving a missed call, for you to be able to call him/her, the number will have to 'subscribe' by giving a missed call. Steps 3,4 will change accordingly. The following steps will then take place:

  • Sample SMS: You've registered with <Your-company-name>. As you're on DND, please authorise us to call you by giving a missed call to 09XXXXXXXXX
  • If the person wants to receive calls from you, they would have to give a missed call on the given number. Until that, you would be unable to contact that number
  • This is done to ensure that this whitelist API is used genuinely and only for transactional calls
  • The above mentioned SMSes are sent from your registered sender ID and the cost of the SMS will be deducted from your account

To start with, a list of DND numbers, who you wish to contact, needs to be prepared. While posting these numbers to Exotel, a Virtual Number/ExoPhone need to be specified using which SMSes can be sent to the DND numbers. On posting to Exotel, a SMS is sent to the DND number informing them that a company has added them as a client and an option is given to accept or deny calls from the company.

Adding to the whitelist

To add a list of DND numbers through our API, you will need to make a HTTP POST request to

POST

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/

  • Replace <your_api_key> and <your_api_token> with the API key and token created by you.
  • Replace <your_sid> with your “Account sid”
  • Replace <subdomain> with the region of your account
    1. <subdomain> of Singapore cluster is @api.exotel.com
    2. <subdomain> of Mumbai cluster is @api.in.exotel.com

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

The following are the POST parameters:

Parameter Name Mandatory/Optional Value
VirtualNumber Mandatory This is your ExoPhone/Virtual Number (pick one from here)
Number Mandatory List of phone numbers to be added in the whitelist.
Language Optional

The Language parameter specifies the language in which the SMS should be sent to the user. The following languages are supported.

  • en - English
  • ta - Tamil

The default Language is English (en).

 curl -X POST https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/ \
 -d "VirtualNumber=XXXXX30240" \
 -d "Number=XXXXX40682" \
 -d "Language=en"
            
var request = require('request');

var dataString = 'VirtualNumber=XXXXX30240&Number=XXXXX40682&Language=en';

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/',
    method: 'POST',
    body: dataString
};

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();
$data = array(
    'VirtualNumber' => 'XXXXX30240',
    'Number' => 'XXXXX40682',
    'Language' => 'en'
);
$response = Requests::post('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/', $headers, $data);
import requests

data = {
  'VirtualNumber': 'XXXXX30240',
  'Number': 'XXXXX40682',
  'Language': 'en'
}

requests.post('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/', data=data)
require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist")
request = Net::HTTP::Post.new(uri)
request.set_form_data(
  "VirtualNumber" => "XXXXX30240",
  "Number" => "XXXXX40682",
  "Language" => "en",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

# response.code
# response.body

HTTP Response:

  • On success, the HTTP response status code will be 200
  • the HTTP body will contain an XML/JSON similar to the one below
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
<Result>
<Total>2</Total>
<Duplicate>0</Duplicate>
<Processed>2</Processed>
<Succeeded>2</Succeeded>
<Redundant>0</Redundant>
<Failed>0</Failed>
<Message>The numbers have been added to the whitelist. If DND number gives a missed call to unsubscribe, the corresponding number will be removed from whitelist.</Message>
</Result>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name Type & Value
Result/Total Total numbers provided
Result/Duplicate Count of duplicate numbers skipped
Result/Processed Count of processed numbers
Result/Succeeded Count of successfully processed numbers
Result/Redundant Count of number with no action taken
Result/Failed Count of failed numbers
Message Description of the action in plain text. The text 'The numbers have been added to the whitelist' would be present in the message only when Result/Succeeded > 0

Deleting from the whitelist

To delete a list of whitelisted numbers through our API, you will need to make a HTTP DELETE request to

DELETE

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX

Replace <your_api_key> and <your_api_token> with the API key and token created by you. Similarly, replace <your_sid> with your “Account sid” value. These values are available in the API settings page of your Exotel Dashboard.

 curl -X DELETE https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX
var request = require('request');

var dataString = 'VirtualNumber=XXXXX30240&Number=XXXXX40682&Language=en';

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX',
    method: 'DELETE',
    body: dataString
};

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();
$data = array(
    'VirtualNumber' => 'XXXXX30240',
    'Number' => 'XXXXX40682',
    'Language' => 'en'
);
$response = Requests::delete('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX', $headers, $data);
import requests

data = {
  'VirtualNumber': 'XXXXX30240',
  'Number': 'XXXXX40682',
  'Language': 'en'
}

requests.delete('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX', data=data)
require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX")
request = Net::HTTP::Delete.new(uri)
request.set_form_data(
  "VirtualNumber" => "XXXXX30240",
  "Number" => "XXXXX40682",
  "Language" => "en",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

# response.code
# response.body

HTTP Response:

  • On success, the HTTP response status code will be 200
  • the HTTP body will contain an XML/JSON similar to the one below
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
<Result>
<Total>2</Total>
<Duplicate>0</Duplicate>
<Processed>2</Processed>
<Succeeded>2</Succeeded>
<Redundant>0</Redundant>
<Failed>0</Failed>
<Message>The numbers have been deleted from the whitelist.</Message>
</Result>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name Type & Value
Result/Total Total numbers provided
Result/Duplicate Count of duplicate numbers skipped
Result/Processed Count of processed numbers
Result/Succeeded Count of successfully processed numbers
Result/Redundant Count of number with no action taken
Result/Failed Count of failed numbers