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 whitelisting is valid only for the next 6 months, post which you will have to ask your customer again if they wish to be contacted.
This is how it works:
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:
To use this API, an agreement outlining the clauses pertaining to calling NCPR numbers, needs to be signed and sent across to Exotel. Please contact your account manager for further details.
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.
To add a list of DND numbers through our API, you will need to make a HTTP POST request to
https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/
If you’d prefer response in JSON format, just append .json at the end of the HTTP POST request.
<your_api_key>
and <your_api_token>
with the API key and token created by you.<your_sid>
with your “Account sid”<subdomain>
with the region of your account
<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.
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:
<?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 |
To delete a list of whitelisted numbers through our API, you will need to make a HTTP DELETE request to
https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX
If you’d prefer response in JSON format, just append .json at the end of the HTTP DELETE request.
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:
<?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 |