×

Create Campaign

POST

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns

  • 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
from Mandatory Comma separated list of phone numbers that will be called. Preferably in E.164 format. If not set, our system will try to match it with a country and make a call. If landline number, prefix it with STD code; Ex: 0XXXXXX2400. Default is 1 and Max is 5000
lists Optional

Array of listSid. Up to 5 listSid can be part of one single campaign if optional parameter campaign type is selected as "static". If optional parameter campaign type is selected as "dynamic" then only one listSid is allowed. If no campaign type parameter is selected then the campaign by default runs as a "static" campaign. Either 'from' parameter or 'lists' parameter should be present in the API request

caller_id Mandatory This is your ExoPhone (pick one from here)
campaign_type Optional

This will be "static" by default. In case, a Dynamic Campaign has to be scheduled then this value will be "dynamic"

flow_type Optional

In case of Creating an IVR through the campaign module, defining "ivr" is mandatory. The parameter name is "ivr". If read_via_text is opted then this value will be "greeting". 

This is not applicable if you are selecting a flow.

repeat_menu_attempts Optional

If the flow_type is selected as "ivr" then this value can be specified to repeat the IVR menu.

The default value will be 0 if the flow_type is set as "ivr". 

This field is not applicable if flow_type is "greeting"

url Optional

Only applicable if you are selecting a call flow. 

http://my.exotel.com/{your_sid}/exoml/start_voice/{app_id} where app_id is the identifier of the flow (or applet) that you want to connect to once the from number picks up the call. You can get the app_id from your Exotel Dashboard

read_via_text Optional

If the flow_type is opted for "ivr" or "greeting", then this field has to be entered with the content that has to be played out to the caller. You can enter a static content(no variables) or Dynamic content. In case, dynamic content is entered then "@@" has to be entered with the header value. Ensure that the header is the exact match from the list uploaded. For ex: If the header name in the file is FirstName then in the content entered here the dynamic variable has to be "@@FirstName"

If flow/url is opted then this field would not be required. 

 

name Optional

It's an optional parameter in the request but mandatory in the response. It is used to define the name of the campaign. It should be greater than 3 characters and if not passed, its default value will be created using the 'AccountSID CurrentDate CurrentTime' and passed in the response.

Example: exotel 2021-06-04 11:11:10

type Optional

It's an optional parameter in the request but mandatory in the response. It's allowed (and default) value is 'trans'. If not passed in the request, we will create campaign as type 'trans' and pass this parameter in the API response. As per regulations, we support only transactional type of campaigns.

call_duplicate_numbers

Optional

Type: boolean

Allowed Values: 'true' & 'false'

Default Value: 'false'

If 'true', Campaign will try calling the duplicate numbers present in the list(s). If 'false', Campaign will call any number in the list(s) only once. It is independent of the 'retry' functionality.

retries Optional

Object;Retry logic in case the calls are not successful.

  • number_of_retries - The number of times a call to a phone number should be attempted. Default is 0 and max is 3.
  • interval_mins - The time interval between retries in mins. Mandatory when number_of_retries is specified
  • mechanism - either "Linear" or "Exponential". If the retry should be equally spaced or exponentially. Default is linear.
  • on_status - Array; Determines when should campaign treat a call as an unsuccessful attempt. Could be "busy", "no-answer", "failed"
schedule Optional

Array;Determines when to start and end a campaign in RFC 3339 date-time

  • send_at - Time when the campaign should start. Default is to start now.
  • end_at - Time when the campaign should end even if all calls are not attempted as part of the campaign. Default +30 days from now or send_at time. This time is always strictly adhered to even there are calls pending to be made
call_status_callback Optional

When the call completes, an HTTP POST will be made to the provided URL with the following four parameters:

  • campaign_sid - an alpha-numeric unique identifier of this campaign
  • call_sid - an alpha-numeric unique identifier of this call
  • date_created - time when the resource was created
  • date_updated - time when the was updated
  • number - number to which the call was made
  • status - one of: completed, no-answer, busy, failed
call_schedule_callback Optional

When all calls to a number were completed including retries, an HTTP POST will be made to the provided URL with the following four parameters:

  • campaign_sid - an alpha-numeric unique identifier of this campaign
  • to - the number to which the call was made
  • from - the Exophone used in the campaign
  • date_created - time when the resource was created
  • date_updated - time when the resource was updated
  • call_sids - Object; includes all the call_sids and status of the calls that were made as part of this schedule
  • status - one of completed, busy, no-answer, failed
status_callback Optional

When the call campaign starts or ends, an HTTP POST will be made to the provided URL with the following four parameters:

  • campaign_sid - an alpha-numeric unique identifier of this campaign
  • date_created - time when the campaign resource was created
  • date_updated - time when the campaign was updated
  • date_started - time when the campaign started
  • status - one of: in-progress, completed, failed, canceled
  • reports - link to the campaign reports
mode Optional

This can be "auto" or "custom". 

Auto- This will be a default in which the campaign service will distribute the throttle of the campaign automatically

Custom- The throttle value can be set based on the desired campaign priority. 

throttle Optional

Only if Mode is selected as "Custom" this parameter will be applicable. The allowed value will be between 1 to (Campaign account throttle minus 1). 

To know your Campaign Account throttle you can visit the Campaign settings page of your Exotel Account. 

custom_field Optional Any application-specific value that will be passed back as a parameter while doing a GET request to the URL mentioned in your Passthru Applet or Greetings Applet.It is also provided as part of the campaigns report
curl --location --request POST 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns' 
--header 'Content-Type: application/json' 
--data-raw '{
"campaigns": [
{
"name": "Exotel_2022-08-08 16:33:22",
"caller_id":"0xxxx83280",
"lists":["b7799a24becf436da672163858e8165d"],
"campaign_type":"dynamic",
"flow_type":"ivr",
"read_via_text":"Hi @@Name @@Last name , your order ID is @@Order ID . Press 1 to proceed, press 2 to abort",
"retries": {
"number_of_retries": 1,
"interval_mins": 1,
"mechanism": "Exponential",
"on_status": [
"failed",
"busy"
]
},
"status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"call_status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"call_schedule_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"custom_field": "{"name": "yo"}"
}
]
}'
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns',
'headers': {
'Content-Type': 'application/json'
},

body: JSON.stringify({
"campaigns": [
{
"caller_id": "0XXXX83280",
"lists": [
"b7799a24becf436da672163858e8165d"
],
"campaign_type": "dynamic",
"flow_type": "ivr",
"read_via_text": "Hi @@Name @@Last name , your order ID is @@Order ID . Press 1 to proceed, press 2 to abort",
"retries": {
"number_of_retries": 1,
"interval_mins": 1,
"mechanism": "Exponential",
"on_status": [
"failed",
"busy"
]
},
"status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"call_status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"call_schedule_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"custom_field": "{"name": "yo"}"
}
]
})
};

request(options, function (error, response) {
if (error) thrownewError(error);

console.log(response.body);
});
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"campaigns": [
{
"caller_id":"0XXXX83280",
"lists":["b7799a24becf436da672163858e8165d"],
"campaign_type":"dynamic",
"flow_type":"ivr",
"read_via_text":"Hi @@Name @@Last name , your order ID is @@Order ID . Press 1 to proceed, press 2 to abort",
"retries": {
"number_of_retries": 1,
"interval_mins": 1,
"mechanism": "Exponential",
"on_status": [
"failed",
"busy"
]
},
"status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"call_status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"call_schedule_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"custom_field": "{"name": "yo"}"
}
]
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests

import json

url = "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns"

payload = json.dumps({
"campaigns": [
{
"caller_id": "0XXXX83280",
"lists": [
"b7799a24becf436da672163858e8165d"
],
"campaign_type": "dynamic",
"flow_type": "ivr",
"read_via_text": "Hi @@Name @@Last name , your order ID is @@Order ID . Press 1 to proceed, press 2 to abort",
"retries": {
"number_of_retries": 1,
"interval_mins": 1,
"mechanism": "Exponential",
"on_status": [
"failed",
"busy"
]
},
"status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"call_status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"call_schedule_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"custom_field": "{"name": "yo"}"
}
]
})

headers = {
'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

func main() {

url := "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns"

method := "POST"

payload := strings.NewReader(`{

"campaigns": [

{

"caller_id":"0XXXX683280",

"lists":["b7799a24becf436da672163858e8165d"],

"campaign_type":"dynamic",

"flow_type":"ivr",

"read_via_text":"Hi @@Name @@Last name , your order ID is @@Order ID . Press 1 to proceed, press 2 to abort",

"retries": {

"number_of_retries": 1,

"interval_mins": 1,

"mechanism": "Exponential",

"on_status": [

"failed",

"busy"

]

},

"status_callback": "https://mycallback.sampledomain.in/1gvta9f1",

"call_status_callback": "https://mycallback.sampledomain.in/1gvta9f1",

"call_schedule_callback": "https://mycallback.sampledomain.in/1gvta9f1",

"custom_field": "{"name": "yo"}"

}

]

}`)

client := &http.Client {
}

req, err := http.NewRequest(method, url, payload)
if err != nil {

fmt.Println(err)
return
}

req.Header.Add("Content-Type", "application/json")

res, err := client.Do(req)
if err != nil {

fmt.Println(err)
return
}

defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {

fmt.Println(err)
return
}

fmt.Println(string(body))
}

HTTP Response:

  • On success, the HTTP response status code will be 200
  • The id is the unique identifier of the campaign, and it will be useful to log this for future debugging
  • HTTP body will contain an JSON similar to the one below
{
"request_id": "0a6d6fccb66e48699b77058554b507e9",
"method": "POST",
"http_code": 200,
"response": [
{
"code": 200,
"error_data": null,
"status": "success",
"data": {
"id": "59beaff7d1c887e877a3b5942bc389fd1688",
"account_sid": "Exotel",
"name": "Exotel_2022-08-08 16:33:22",
"type": "trans",
"caller_id": "0XXXX83280",
"campaign_type": "dynamic",
"read_via_text": "Hi @@Name @@Last name , your order ID is @@Order ID . Press 1 to proceed, press 2 to abort",
"repeat_menu_attempts": 0,
"flow_type": "ivr",
"lists": [
"b7799a24becf436da672163858e8165d"
],
"url": "http://my.exotel.com/Exotel/exoml/start_voice/528696",
"retries": {
"number_of_retries": 1,
"interval_mins": 1,
"mechanism": "Exponential",
"on_status": [
"failed",
"busy"
]
},
"schedule": {
"send_at": "2022-08-08T16:34:22+05:30",
"end_at": "2022-09-07T16:34:22+05:30"
},
"status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"call_status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"call_schedule_callback": "https://mycallback.sampledomain.in/1gvta9f1",
"custom_field": "{"name": "yo"}",
"date_created": "2022-08-08T16:33:22+05:30",
"date_updated": "2022-08-08T16:33:22+05:30",
"status": "Created",
"call_status_callback_params": null,
"call_duplicate_numbers": false,
"stats": {
"created": 0,
"in-progress": 0,
"retry": 0,
"retrying": 0,
"failed": 0,
"failed-dnd": 0,
"invalid": 0,
"paused": 0,
"failed-no-attempt": 0,
"completed": 0,
"pending": 0
},
"mode": "auto"
},
"summary": {
"campaign_sid": "59beaff7d1c887e877a3b5942bc389fd1688",
"call_scheduled": 0,
"call_initialized": 0,
"call_completed": 0,
"call_failed": 0,
"call_inprogress": 0,
"DateCreated": "2022-08-08T16:33:22.749572683+05:30"
}
}
]
}

Description of parameters mentioned in the above response:

Parameter Name Type & Value
request_id string; Random string to uniquely identify the request
method string; HTTP request method (GET, POST, PUT, DELETE)
http_code string; HTTP response code for your request
response

JSON array representing the response and contains below parameters:

  • code - response code of the block in the response array, can be different from the overall http code, like in case of partial success (207)
  • error_data - To be populated in case of errors like below
"error_data": {
    "code": 1000,
    "description": "Not Found",
    "message": "Not Found"
}

In case of no errors, it’ll be null.

  • status - success or failure, depicting the status of the block in the response array
  • data - This will contain the data part of the block of the response array depending on the API, below table describes what will be populated in case of POST on Campaigns API. Please note, this field can be null also in case of failures like 404.
id Campaigns identifier
account_sid Exotel account SID
from Array; phone numbers that we will be attempted as part of this campaign
caller_id The Exophone that is used to initiate calls for this campaign
url Identifier of the flow (or applet) that you want to connect to once the from number picks up the call
retries

JSON; The retries that were configured as part of this campaign:

  • number_of_retries - The number of times a call to a phone number should be attempted.
  • interval_mins - The time interval between retries in mins.
  • mechanism - Either "linear" or "exponential". If the retry should be equally spaced or exponentially.
  • on_status - Array; When should campaign treat a call as an unsuccesful attempt. Could be "busy", "no-answer", "failed"
schedule

JSON; The start and end time that were configured for this campaign:

  • send_at - Time when the campaign should start. Default is to start now.
  • end_at - Time when the campaign should end even if all calls are not attempted as part of the campaign. Default +30 days from now or send_at time. This time is always stricktly adhered to even there are calls pending to be made
status_callback URL to which an HTTP POST will be made upon completion of the campaign
call_status_callback URL to which an HTTP POST will be made upon completion of a call in the campaign
call_schedule_callback URL to which an HTTP POST will be made upon completion of one call schedule which includes retries
custom_field Application specific value that was be passed back as a parameter to the campaign creation
date_created Time in format: RFC 3339; Date and time at which the resource was created in the system
date_updated Time in format: RFC 3339; Date and time at which the resource was updated in the system
status

The current status of the campaign. Campaings have both intermediate and final status:

  • Created - A campaign resource was created in the system as a result of a succesful POST request to the campaigns end point
  • InProgress - The campaign is currently in progress
  • completed - The campaign has ended normally
  • Failed - None of the calls were made as part of the campaign (5xx/4xx/invalid numbers etc.). Immediate failures are marked as failed as well
  • Canceled - The campaign was paused but never resumed and end_at time reached or it expired
  • Deleted - The campaign which was deleted before the trigger (scheduled time)
  • Paused - The campaign that was scheduled or is in-progress was paused

Status Callbacks

There are multiple status callbacks that Campaign API serves when specified as part of POST request. Sample responses of each of them are given below

Call Status Callback:

  • On every attempt to call a number, a HTTP POST request is made to the end point specified
  • The campaign_sid is the unique identifier of the campaign, and it will be useful to log this for future debugging
  • the HTTP body will contain an JSON similar to the one below
{
    "request_id": "745d624f47004b71bf72e6cb7d58a25b",
    "method": "POST",
    "http_code": 200,
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "name": "diwali_campaign",
                "type": "trans",
                "id": "909d2a2ba53ce07f3784668b938eb44914bo",
                "account_sid": "exotel8u3",
                "caller_id": "0XXXX720616",
                "lists": [
                    "68f443cd3e764ad1ae7d82ad27f0af72"
                ],
                "url": "http://my.exotel.com/<your_sid>/exoml/start_voice/<app_id>",
                "retries": {
                    "number_of_retries": 1,
                    "interval_mins": 1,
                    "mechanism": "Exponential",
                    "on_status": [
                        "failed",
                        "busy"
                    ]
                },
                "schedule": {
                    "send_at": "2019-01-20T21:15:00+05:30",
                    "end_at": "2019-01-20T21:16:00+05:30"
                },
                "status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
                "call_status_callback": "https://mycallback.sampledomain.in/1gvta9f1",
                "call_schedule_callback": "https://mycallback.sampledomain.in/1gvta9f1",
                "date_created": "2019-01-20T21:10:00+05:30",
                "date_updated": "2019-01-20T21:10:00+05:30",
                "status": "Created",
                "call_status_callback_params": null,
                "call_duplicate_numbers": true,
                "stats": {
                    "created": 0,
                    "in-progress": 0,
                    "retry": 0,
                    "retrying": 0,
                    "failed": 0,
                    "failed-dnd": 0,
                    "invalid": 0,
                    "paused": 0,
                    "failed-no-attempt": 0,
                    "completed": 0
                }
            },
            "summary": {
                "campaign_sid": "75ccf890dd85a87c138396b8abfec9251579",
                "call_scheduled": 0,
                "call_initialized": 0,
                "call_completed": 0,
                "call_failed": 0,
                "call_inprogress": 0,
                "DateCreated": "2019-01-20T21:10:00+05:30"
            }
        }
    ]
}

Call Schedule Status Callback:

  • After all attempts to call a number (including all retries), a HTTP POST request is made to the end point specified
  • The campaign_sid is the unique identifier of the campaign, and it will be useful to log this for future debugging
  • the HTTP body will contain an JSON similar to the one below
{
   "campaign_sid":"44a89f18b291441786f6be2dacee0366",
   "to": "+91XXXX161323",
   "from": "XXXXXX74100",
   "date_created": "2019-01-10T17:08:00+05:30",
   "date_updcated": "2019-01-10T17:08:00+05:30",
   "call_sids": [
       {
     "call_sid": "73f57c6bccd64a29a0cb4806af05cdbe",
       "status": "completed"
       }
   ],
   "status": "completed"
}

Campaigns Status Callback:

  • After the campaign is completed, a HTTP POST request is made to the end point specified
  • The campaign_sid is the unique identifier of the campaign, and it will be useful to log this for future debugging
  • the HTTP body will contain an JSON similar to the one below
{
   "campaign_sid": "44a89a18b291441786f6be2dfcee0366",
   "date_created": "2019-01-10T17:08:00+05:30",
   "date_updated": "2019-01-10T17:08:00+05:30",
   "date_started": "2019-01-10T17:08:00+05:30",
   "status": "completed",
   "reports": "https://campaigns-reports.s3.ap-southeast-1.amazonaws.com/000d3b00d7651e088e1b42be5d89xxx.csv"
}

Get Campaign Details

To get the details of a specific campaign in your account, make an HTTP GET request to:

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns/<id>

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. Replace <id> with the campaign id.

curl -X GET https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns/<id>
var request = require("request");
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64')
var options = { method: 'GET',
  url: 'https://api.exotel.com/v2/accounts/'+ accountSid +'/campaigns/491dd6c97d64475ba0ce346a18530ce5',
  headers: 
   { 
     Authorization: 'Basic ' + encoding 
    } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
  
});
<?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.exotel.com/v2/accounts/".$accountSid."/campaigns/491dd6c97d64475ba0ce346a18530ce5",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding
  ),
));

$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"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

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

url = "https://api.exotel.com/v2/accounts/"+ accountSid +"/campaigns/491dd6c97d64475ba0ce346a18530ce5"

payload = ""
headers = {
    'Authorization': "Basic " + encoding
    }

response = requests.request("GET", 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"
)

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://api.exotel.com/v2/accounts/" + accountSid + "/campaigns/491dd6c97d64475ba0ce346a18530ce5"

	req, _ := http.NewRequest("GET", url, nil)

	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
  • HTTP body will contain an JSON similar to the one below
  • Response parameters are described above
"request_id": "4ab25b37b89447cb8e1c7d527ae98d2e",
"method": "GET",
"http_code": 200,
"metadata": {
"count": 0,
"offset": 0,
"total": 0,
"limit": 20
},
"response": [
{
"code": 200,
"error_data": null,
"status": "success",
"data": {
"id": "59beaff7d1c887e877a3b5942bc389fd1688",
"account_sid": "Exotel",
"name": "Exotel_2022-08-08 16:33:22",
"type": "trans",
"caller_id": "0XXXX83280",
"campaign_type": "dynamic",
"read_via_text": "Hi @@Name @@Last name , your order ID is @@Order ID . Press 1 to proceed, press 2 to abort",
"repeat_menu_attempts": 0,
"flow_type": "ivr",
"lists": [
"b7799a24becf436da672163858e8165d"
],
"url": "http://my.exotel.com/Exotel/exoml/start_voice/528696",
"retries": {
"number_of_retries": 1,
"interval_mins": 1,
"mechanism": "Exponential",
"on_status": [
"failed",
"busy"
]
},
"schedule": {
"send_at": "2022-08-08T16:34:23+05:30",
"end_at": "2022-09-07T16:34:23+05:30"
},
"status_callback": "https://webhook.site/59590860-f765-499c-bf45-47e14676b1f1",
"call_status_callback": "https://webhook.site/59590860-f765-499c-bf45-47e14676b1f1",
"call_schedule_callback": "https://webhook.site/59590860-f765-499c-bf45-47e14676b1f1",
"custom_field": "{\"name\": \"yo\"}",
"date_created": "2022-08-08T16:33:23+05:30",
"date_updated": "2022-08-08T16:40:42+05:30",
"status": "Completed",
"report_url": "https://campaigns-reports.s3.ap-southeast-1.amazonaws.com/59beaff7d1c887e877a3b5942bc389fd1688.csv",
"call_status_callback_params": null,
"call_duplicate_numbers": false,
"stats": {
"created": 0,
"in-progress": 0,
"retry": 0,
"retrying": 0,
"failed": 0,
"failed-dnd": 0,
"invalid": 0,
"paused": 0,
"failed-no-attempt": 0,
"completed": 2,
"pending": 0
},
"mode": "auto"
},
"summary": {
"campaign_sid": "59beaff7d1c887e877a3b5942bc389fd1688",
"call_scheduled": 0,
"call_initialized": 2,
"call_completed": 2,
"call_failed": 0,
"call_inprogress": 0,
"DateCreated": "2022-08-08T16:33:23+05:30"
}
}
]
}

Update Campaign

While you can update all the parameters of a campaign that has not started. For a campaign that is in progress you can 'pause' or 'resume' or 'mark as completed' specified by the parameter below. Additionally, any completed campaign can be marked as 'archived'.

PUT

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns/<id>

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. Replace <id> with the campaign id.

Parameter Name

Type & Value

action

A parameter which can control the action of a created campaign. The below values (string) can be passed:

  • pause - Stop calling more numbers as part of the campaign that is in progress. We can pause only created and in-progress campaign
  • resume - Resume calling numbers that were not called. We can resume only paused campaign
  • complete - Mark the entire campaign as Completed. Remaining numbers are marked as Failed. We can mark only paused campaign as completed
  • archive - Mark a campaign as archived. Only completed campaign can be marked as archived
 curl -X PUT https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns/<id> \
 -d '{"campaigns":[{"action":"pause"}]}'
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://api.exotel.com/v2/accounts/'+ accountSid +'/campaigns/6d49fb6fe1ee4abc8b2c4ea5d2f4015a',
  headers: 
   {
     Authorization: 'Basic ' + encoding,
     'Content-Type': 'application/json' 
    },
  body: 
   { campaigns: 
      [ { caller_id: '0XXXXXXXXX1',
          action: 'pause',
          url: 'http://my.exotel.com/<your_sid>/exoml/start_voice/<app_id>' } ] },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
  console.log(JSON.stringify(body))
});
<?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.exotel.com/v2/accounts/".$accountSid."/campaigns/6d49fb6fe1ee4abc8b2c4ea5d2f4015a",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => '{
    "campaigns":[{
    "action": "pause",
    "url": "http://my.exotel.com/<your_sid>/exoml/start_voice/<app_id>"}]}',
  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"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

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


url = "https://api.exotel.com/v2/accounts/"+accountSid+"/campaigns/6d49fb6fe1ee4abc8b2c4ea5d2f4015a"

payload = json.dumps({ "campaigns": [{ 
          "action": "0XXXXXXXXX1", 
          "url": "http://my.exotel.com/<your_sid>/exoml/start_voice/<app_id>"]
        })
headers = {
    'Content-Type': "application/json",
    'Authorization': "Basic " + encoding
    }

response = requests.request("PUT", 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() {
	// 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://api.exotel.com/v2/accounts/" + accountSid + "/campaigns/6d49fb6fe1ee4abc8b2c4ea5d2f4015a"

	payload := strings.NewReader(`{ 
    "campaigns": [{ 
      "action": "pause", 
      "url": "http://my.exotel.com/<your_sid>/exoml/start_voice/<app_id>"
      }]
    }`)

	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, _ := http.DefaultClient.Do(req)

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

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

}
{
    "request_id": "745d624f47004b71bf72e6cb7d58a25b",
    "method": "POST",
    "http_code": 200,
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "name": "diwali_campaign",
                "type": "trans",
                "id": "909d2a2ba53ce07f3784668b938eb44914bo",
                "account_sid": "<your_sid>",
                "caller_id": "03349360005",
                "lists": [
                    "71ee118172044804ac5ed2271167c02b"
                ],
                "url": "https://my.exotel.com/<your_sid>/exoml/start_voice/4",
                "retries": {
                    "number_of_retries": 1,
                    "interval_mins": 1,
                    "mechanism": "Exponential",
                    "on_status": [
                        "failed",
                        "busy"
                    ]
                },
                "schedule": {
                    "send_at": "2020-11-24T23:53:19+05:30",
                    "end_at": "2020-12-24T23:53:19+05:30"
                },
                "status_callback": "https://webhook.site/21a6f658-10d4-4b95-9001-c7bf00239502",
                "call_status_callback": "https://webhook.site/21a6f658-10d4-4b95-9001-c7bf00239502",
                "call_schedule_callback": "https://webhook.site/21a6f658-10d4-4b95-9001-c7bf00239502",
                "custom_field": "{\"name\": \"yo\"}",
                "date_created": "2020-11-24T23:52:19+05:30",
                "date_updated": "2020-11-24T23:52:19+05:30",
                "status": "paused",
                "call_status_callback_params": null
            },
            "summary": {
                "campaign_sid": "909d2a2ba53ce07f3784668b938eb44914bo",
                "call_scheduled": 0,
                "call_initialized": 0,
                "call_completed": 0,
                "call_failed": 0,
                "call_inprogress": 0,
                "DateCreated": "2020-11-24T23:52:19.625541789+05:30"
            }
        }
    ]
}
  • On success, the HTTP response status code will be 200
  • HTTP body will contain an JSON with details of the updated resource
  • Response parameters are described above

Update Campaign Details

This API allows you to update all the parameters of a campaign that has not started. Campaign details can be updated before send_at time is passed. Once send_at time is passed only action, status_callback, call_status_callback and call_schedule_callback can be updated.

PUT

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns/<id>

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. Replace <id> with the campaign id.

curl --location --request PUT 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns/<id>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "campaigns": [
        {
            "name": "holi_campaign",
            "type": "trans",
            "caller_id": "03349360005",
            "url": "https://my.exotel.com/<your_sid>/exoml/start_voice/123",
            "from": [
                "+917987616844"
            ],
            "retries": {
                "number_of_retries": 2,
                "interval_mins": 1,
                "mechanism": "Exponential",
                "on_status": [
                    "busy"
                ]
            },
            "status_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d",
            "call_status_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d",
            "call_schedule_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d"
        }
    ]
}'
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://api.exotel.com/v2/accounts/'+ accountSid +'/campaigns/6d49fb6fe1ee4abc8b2c4ea5d2f4015a',
  headers: 
   {
     Authorization: 'Basic ' + encoding,
     'Content-Type': 'application/json' 
    },
  body: 
   { campaigns: 
      [ { 
      name: "holi_campaign",
      type: "trans",
      caller_id: "03349360005",
      url: "https://my.exotel.com/<your_sid>/exoml/start_voice/123",
      from: [
          "+917987616844"
      ],
      retries: {
          "number_of_retries": 2,
          "interval_mins": 1,
          "mechanism": "Exponential",
          "on_status": [
              "busy"
          ]
      },
      status_callback: "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d",
      call_status_callback: "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d",
      call_schedule_callback: "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d" } ] },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
  console.log(JSON.stringify(body))
});
<?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.exotel.com/v2/accounts/".$accountSid."/campaigns/6d49fb6fe1ee4abc8b2c4ea5d2f4015a",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => '{
    "campaigns": [
        {
            "name": "holi_campaign",
            "type": "trans",
            "caller_id": "03349360005",
            "url": "https://my.exotel.com/<your_sid>/exoml/start_voice/123",
            "from": [
                "+917987616844"
            ],
            "retries": {
                "number_of_retries": 2,
                "interval_mins": 1,
                "mechanism": "Exponential",
                "on_status": [
                    "busy"
                ]
            },
            "status_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d",
            "call_status_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d",
            "call_schedule_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d"
        }
    ]
}',
  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"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

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


url = "https://api.exotel.com/v2/accounts/"+accountSid+"/campaigns/6d49fb6fe1ee4abc8b2c4ea5d2f4015a"

payload = json.dumps({ {
    "campaigns": [
        {
            "name": "holi_campaign",
            "type": "trans",
            "caller_id": "03349360005",
            "url": "https://my.exotel.com/<your_sid>/exoml/start_voice/123",
            "from": [
                "+917987616844"
            ],
            "retries": {
                "number_of_retries": 2,
                "interval_mins": 1,
                "mechanism": "Exponential",
                "on_status": [
                    "busy"
                ]
            },
            "status_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d",
            "call_status_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d",
            "call_schedule_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d"
        }
    ]
}
        })
headers = {
    'Content-Type': "application/json",
    'Authorization': "Basic " + encoding
    }

response = requests.request("PUT", 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() {
// 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://api.exotel.com/v2/accounts/" + accountSid + "/campaigns/6d49fb6fe1ee4abc8b2c4ea5d2f4015a"

	payload := strings.NewReader(`{ 
    "campaigns": [{ 
      "action": "pause", 
      "url": "http://my.exotel.com/<your_sid>/exoml/start_voice/<app_id>"
      payload := strings.NewReader(
           { 
                { "campaigns": [ 
                { "name": "holi_campaign", 
                  "type": "trans", 
                  "caller_id": "03349360005", 
                  "url": "https://my.exotel.com/<your_sid>/exoml/start_voice/123", 
                  "from": [ "+917987616844" ], 
                  "retries": 
                       { "number_of_retries": 2, 
                         "interval_mins": 1, 
                         "mechanism": "Exponential", 
                         "on_status": [ "busy" ] 
                       }, 
                 "status_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d", 
                 "call_status_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d", 
                 "call_schedule_callback": "https://webhook.site/a5b59df3-c1b6-4a93-aa1a-75f2c8a3721d" 
                 } ] } })
      }]
    }`)

	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, _ := http.DefaultClient.Do(req)

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

	fmt.Println(res)
	fmt.Println(string(body))
}
{
    "request_id": "745d624f47004b71bf72e6cb7d58a25b",
    "method": "POST",
    "http_code": 200,
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "name": "diwali_campaign",
                "type": "trans",
                "id": "909d2a2ba53ce07f3784668b938eb44914bo",
                "account_sid": "<your_sid>",
                "caller_id": "03349360005",
                "lists": [
                    "71ee118172044804ac5ed2271167c02b"
                ],
                "url": "https://my.exotel.com/<your_sid>/exoml/start_voice/4",
                "retries": {
                    "number_of_retries": 1,
                    "interval_mins": 1,
                    "mechanism": "Exponential",
                    "on_status": [
                        "failed",
                        "busy"
                    ]
                },
                "schedule": {
                    "send_at": "2020-11-24T23:53:19+05:30",
                    "end_at": "2020-12-24T23:53:19+05:30"
                },
                "status_callback": "https://webhook.site/21a6f658-10d4-4b95-9001-c7bf00239502",
                "call_status_callback": "https://webhook.site/21a6f658-10d4-4b95-9001-c7bf00239502",
                "call_schedule_callback": "https://webhook.site/21a6f658-10d4-4b95-9001-c7bf00239502",
                "custom_field": "{\"name\": \"yo\"}",
                "date_created": "2020-11-24T23:52:19+05:30",
                "date_updated": "2020-11-24T23:52:19+05:30",
                "status": "Created",
                "call_status_callback_params": null
            },
            "summary": {
                "campaign_sid": "909d2a2ba53ce07f3784668b938eb44914bo",
                "call_scheduled": 0,
                "call_initialized": 0,
                "call_completed": 0,
                "call_failed": 0,
                "call_inprogress": 0,
                "DateCreated": "2020-11-24T23:52:19.625541789+05:30"
            }
        }
    ]
}

Delete Campaign

To delete a specific campaign in your account, make an HTTP DELETE request to:

DELETE

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns/<id>

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. Replace <id> with the campaign id.

curl -X DELETE https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns/<id>
var request = require("request");
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

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

var options = { method: 'DELETE',
  url: 'https://api.exotel.com/v2/accounts/'+ accountSid +'/campaigns/491dd6c97d64475ba0ce346a18530ce5',
  headers: 
   { 
     Authorization: 'Basic ' + encoding 
    } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
  
});
<?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";
$encoding = base64_encode($authKey .":". $accountToken);
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.exotel.com/v2/accounts/".$accountSid."/campaigns/491dd6c97d64475ba0ce346a18530ce5",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding
  ),
));

$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"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

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

url = "https://api.exotel.com/v2/accounts/"+ accountSid +"/campaigns/491dd6c97d64475ba0ce346a18530ce5"

payload = ""
headers = {
    'Authorization': "Basic " + encoding
    }

response = requests.request("DELETE", 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"
)

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://api.exotel.com/v2/accounts/" + accountSid + "/campaigns/491dd6c97d64475ba0ce346a18530ce5"

	req, _ := http.NewRequest("DELETE", url, nil)

	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
  • HTTP body will contain an JSON similar to the one below
  • Response parameters are described above

Bulk Campaign Details

This API allows you to fetch bulk campaign details with sorting and searching capabilities. 

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns

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. Replace <id> with the campaign id.

The following are the Query parameters:

Parameter Name   Mandatory/Optional Value

offset

Optional

This is the position in the dataset of a particular record. By specifying offset, you retrieve a subset of records starting with the offset value. Offset is zero-based i.e. the 10th record is at offset 9

limit

Optional

number of records on single page default:20 maximum=500

name

Optional

Search on Campaign name 

status

Optional

This will respect given statuses. By default all records will be populated of all status. However, you can filter on set of status too. eg, status=in-progress, created

sort_by

Optional

This indicates in what order the campaign records are sorted in the API response. By default records are sorted by DateCreated in ascending order. However, you can override the same in following way for ascending order: Eg: date_created:asc or name:asc

type Optional

It's an optional parameter in the request but mandatory in the response. It's allowed (and default) value is 'trans'. If not passed in the request, we will create campaign as type 'trans' and pass this parameter in the API response. As per regulations, we support only transactional type of campaigns.

curl https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns?offset=0&status=Created,Completed&limit=3
var request = require("request");
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64')
var options = { method: 'GET',
  url: 'https://api.exotel.com/v2/accounts/'+ accountSid +'/campaigns?offset=0&status=Created,Completed&limit=3',
  headers: 
   { 
     Authorization: 'Basic ' + encoding 
    } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
  
});
<?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.exotel.com/v2/accounts/".$accountSid."/campaigns?offset=0&status=Created,Completed&limit=3",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding
  ),
));

$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"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

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

url = "https://api.exotel.com/v2/accounts/"+ accountSid +"/campaigns?offset=0&status=Created,Completed&limit=3"

payload = ""
headers = {
    'Authorization': "Basic " + encoding
    }

response = requests.request("DELETE", 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"
)

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://api.exotel.com/v2/accounts/" + accountSid + "/campaigns?offset=0&status=Created,Completed&limit=3"

req, _ := http.NewRequest("GET", url, nil)

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))
}
{
    "request_id": "c2cedb1eabb4472da3a6fe4802607410",
    "method": "GET",
    "http_code": 207,
    "metadata": {
        "count": 3,
        "offset": 0,
        "total": 138,
        "limit": 3
    },
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "id": "046141c8f6edde79938e69af34e560ef156l",
                "account_sid": "<your_sid>",
                "name": "<your_sid>_2021-06-21 22:28:47",
                "type": "trans",
                "from": [
                    "9900000017"
                ],
                "caller_id": "03349360005",
                "url": "https://my.exotel.com/<your_sid>/exoml/start_voice/4",
                "retries": {
                    "number_of_retries": 1,
                    "interval_mins": 1,
                    "mechanism": "Exponential",
                    "on_status": [
                        "failed",
                        "busy",
                        "no-answer"
                    ]
                },
                "schedule": {
                    "send_at": "2021-06-21T22:29:47+05:30",
                    "end_at": "2021-07-21T22:29:47+05:30"
                },
                "status_callback": "https://webhook.site/65022bd9-a447-4ab8-975a-6ce2bd504843",
                "call_status_callback": "https://webhook.site/65022bd9-a447-4ab8-975a-6ce2bd504843",
                "call_schedule_callback": "https://webhook.site/65022bd9-a447-4ab8-975a-6ce2bd504843",
                "custom_field": "{\"name\": \"time\"}",
                "date_created": "2021-06-21T22:28:47+05:30",
                "date_updated": "2021-06-21T22:35:54+05:30",
                "status": "Completed",
                "uri": "/v2/accounts/<your_sid>/campaigns/046141c8f6edde79938e69af34e560ef156l",
                "report_url": "https://campaigns-reports-qa-us3.s3.us-west-2.amazonaws.com/046141c8f6edde79938e69af34e560ef156l.csv",
                "call_status_callback_params": null,
                "call_duplicate_numbers": true,
                "stats": {
                    "created": 0,
                    "in-progress": 0,
                    "retry": 0,
                    "retrying": 0,
                    "failed": 0,
                    "failed-dnd": 0,
                    "invalid": 0,
                    "paused": 0,
                    "failed-no-attempt": 0,
                    "completed": 1
                }
            },
            "summary": {
                "campaign_sid": "046141c8f6edde79938e69af34e560ef156l",
                "call_scheduled": 1,
                "call_initialized": 1,
                "call_completed": 1,
                "call_failed": 0,
                "call_inprogress": 0,
                "DateCreated": "2021-06-21T22:28:47+05:30"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "id": "391db1c6f28ca06273ba200221767fe3156l",
                "account_sid": "<your_sid>",
                "name": "<your_sid>_2021-06-21 21:58:43",
                "type": "trans",
                "from": [
                    "9900000017"
                ],
                "caller_id": "03349360005",
                "url": "https://my.exotel.com/<your_sid>/exoml/start_voice/4",
                "retries": {
                    "number_of_retries": 1,
                    "interval_mins": 1,
                    "mechanism": "Exponential",
                    "on_status": [
                        "failed",
                        "busy",
                        "no-answer"
                    ]
                },
                "schedule": {
                    "send_at": "2021-06-21T21:59:43+05:30",
                    "end_at": "2021-07-21T21:59:43+05:30"
                },
                "status_callback": "https://webhook.site/65022bd9-a447-4ab8-975a-6ce2bd504843",
                "call_status_callback": "https://webhook.site/65022bd9-a447-4ab8-975a-6ce2bd504843",
                "call_schedule_callback": "https://webhook.site/65022bd9-a447-4ab8-975a-6ce2bd504843",
                "custom_field": "{\"name\": \"time\"}",
                "date_created": "2021-06-21T21:58:43+05:30",
                "date_updated": "2021-06-21T21:58:43+05:30",
                "status": "Created",
                "uri": "/v2/accounts/<your_sid>/campaigns/391db1c6f28ca06273ba200221767fe3156l",
                "call_status_callback_params": null,
                "call_duplicate_numbers": true,
                "stats": {
                    "created": 0,
                    "in-progress": 0,
                    "retry": 0,
                    "retrying": 0,
                    "failed": 0,
                    "failed-dnd": 0,
                    "invalid": 0,
                    "paused": 0,
                    "failed-no-attempt": 0,
                    "completed": 0
                }
            },
            "summary": {
                "campaign_sid": "391db1c6f28ca06273ba200221767fe3156l",
                "call_scheduled": 0,
                "call_initialized": 0,
                "call_completed": 0,
                "call_failed": 0,
                "call_inprogress": 0,
                "DateCreated": "2021-06-21T21:58:43+05:30"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "id": "cff6e2d08f563dc358a9c565e10cd9d3156l",
                "account_sid": "<your_sid>",
                "name": "<your_sid>_2021-06-21 21:47:41",
                "type": "trans",
                "from": [
                    "9900000017"
                ],
                "caller_id": "03349360005",
                "url": "https://my.exotel.com/<your_sid>/exoml/start_voice/4",
                "retries": {
                    "number_of_retries": 1,
                    "interval_mins": 1,
                    "mechanism": "Exponential",
                    "on_status": [
                        "failed",
                        "busy",
                        "no-answer"
                    ]
                },
                "schedule": {
                    "send_at": "2021-06-21T21:48:42+05:30",
                    "end_at": "2021-07-21T21:48:42+05:30"
                },
                "status_callback": "https://webhook.site/65022bd9-a447-4ab8-975a-6ce2bd504843",
                "call_status_callback": "https://webhook.site/65022bd9-a447-4ab8-975a-6ce2bd504843",
                "call_schedule_callback": "https://webhook.site/65022bd9-a447-4ab8-975a-6ce2bd504843",
                "custom_field": "{\"name\": \"time\"}",
                "date_created": "2021-06-21T21:47:42+05:30",
                "date_updated": "2021-06-21T21:47:42+05:30",
                "status": "Created",
                "uri": "/v2/accounts/<your_sid>/campaigns/cff6e2d08f563dc358a9c565e10cd9d3156l",
                "call_status_callback_params": null,
                "call_duplicate_numbers": true,
                "stats": {
                    "created": 0,
                    "in-progress": 0,
                    "retry": 0,
                    "retrying": 0,
                    "failed": 0,
                    "failed-dnd": 0,
                    "invalid": 0,
                    "paused": 0,
                    "failed-no-attempt": 0,
                    "completed": 0
                }
            },
            "summary": {
                "campaign_sid": "cff6e2d08f563dc358a9c565e10cd9d3156l",
                "call_scheduled": 0,
                "call_initialized": 0,
                "call_completed": 0,
                "call_failed": 0,
                "call_inprogress": 0,
                "DateCreated": "2021-06-21T21:47:42+05:30"
            }
        }
    ]
}

Call Details of a Single Campaign

This API allows you to get the details of all the calls of a Campaign. It's like a summary page or Inbox per campaign.

The call level data consists of Name (if saved in Contacts), Number, Duration, Date Created, Status, Digits, Recording URL, Start Time, End Time, Caller ID, Direction & CallSid

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaign/<campaign_id>/call-details

  • 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 Query parameters:

Parameter Name   Mandatory/Optional Value

offset

optional

This is the position in the dataset of a particular record. By specifying offset, you retrieve a subset of records starting with the offset value. Offset is zero-based i.e. the 10th record is at offset 9

limit

optional

number of records on single page default:20

status

optional

completed, failed, busy, no-answer

sort_by

optional

Date_created:asc, date_created:desc

curl https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/campaigns/call-details?status=no-answer,failed&sort_by=date_created:desc&limit=3&offset=0
var request = require("request");
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64')
var options = { method: 'GET',
  url: 'https://api.exotel.com/v2/accounts/'+ accountSid +'/campaigns/491dd6c97d64475ba0ce346a18530ce5/call-details?status=no-answer,failed&sort_by=date_created:desc&limit=3&offset=0',
  headers: 
   { 
     Authorization: 'Basic ' + encoding 
    } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
  
});
<?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.exotel.com/v2/accounts/".$accountSid."/campaigns/491dd6c97d64475ba0ce346a18530ce5/call-details?status=no-answer,failed&sort_by=date_created:desc&limit=3&offset=0",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding
  ),
));

$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"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

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

url = "https://api.exotel.com/v2/accounts/"+ accountSid +"/campaigns/491dd6c97d64475ba0ce346a18530ce5/call-details?status=no-answer,failed&sort_by=date_created:desc&limit=3&offset=0"

payload = ""
headers = {
    'Authorization': "Basic " + encoding
    }

response = requests.request("DELETE", 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"
)

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://api.exotel.com/v2/accounts/" + accountSid + "/campaigns/491dd6c97d64475ba0ce346a18530ce5/call-details?status=no-answer,failed&sort_by=date_created:desc&limit=3&offset=0"

req, _ := http.NewRequest("GET", url, nil)

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))
}
{
    "request_id": "a0e05cd2d3b8419caba589b5278269c3",
    "method": "GET",
    "http_code": 200,
    "metadata": {
        "count": 3,
        "offset": 0,
        "total": 19,
        "limit": 3
    },
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "number": "+919449141947",
                "name": "NA",
                "duration": 3,
                "date_created": "2021-07-11T12:08:01+05:30",
                "status": "failed",
                "digit": null,
                "recording_url": "",
                "start_time": "2021-07-11T12:08:00+05:30",
                "end_time": "2021-07-11T12:08:00+05:30",
                "caller_id": "08088919888",
                "direction": "Outgoing",
                "call_sid": "e03f3cf9b27cea6108d1195c5753157b"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "number": "+919946986806",
                "name": "NA",
                "duration": 51,
                "date_created": "2021-07-11T12:08:01+05:30",
                "status": "no-answer",
                "digit": null,
                "recording_url": "",
                "start_time": "2021-07-11T12:08:00+05:30",
                "end_time": "2021-07-11T12:08:00+05:30",
                "caller_id": "08088919888",
                "direction": "Outgoing",
                "call_sid": "f93248f8e1a8e8b28b649ad5150a157b"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "number": "+919310398307",
                "name": "NA",
                "duration": 18,
                "date_created": "2021-07-11T12:08:01+05:30",
                "status": "failed",
                "digit": null,
                "recording_url": "",
                "start_time": "2021-07-11T12:08:00+05:30",
                "end_time": "2021-07-11T12:08:00+05:30",
                "caller_id": "08088919888",
                "direction": "Outgoing",
                "call_sid": "71ff290dc61eb39518af202ce37f157b"
            }
        }
    ]
}