Campaign Manager

Introduction

Campaign Manager allows you to send the same SMS or Voice call to hundreds of thousands of phone numbers within minutes. For more details, please review the general documentation.

This document covers the API(s) that are available to you to manage campaigns and get information on credits added to the account to track the usage of the service.

Credit

You can search all the credits added by CPaaS to your business.Credits help you to create campaigns and send SMS/Voice to your own customers or audience.This model is pre-paid to make sure that cost will never overrun the budget you have available.

  • Whenever Campaign is scheduled, equivalent Credit is deducted.

  • If there is not enough Credit available, scheduling of Campaign will fail.

  • If a Scheduled Campaign is cancelled, the equivalent Credit is added back.

  • Once a Campaign progresses to InProgress state, Credit cannot be reversed, no matter what.

*One credit equals 1 SMS or 1 Voice call.

*For example,if you have 100 credits, you can only send 100 SMS Segments or 100 Voice calls.

Get List of Credits

This endpoint will be used to get a current list of credits.

Base Resource URI

https://$DOMAIN

Get List of Credit Resource URI

/campaignmanager/credits/search

Supported Operations

HTTP Get: Get list of Credits for a Business Customer

Paging

The following paging parameters are supported.

Query Parameter Description

pageSize

Number of records returned per page

page

Which page of Participants records to return, starting from 0.

If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

The following filtering parameters are supported:

Query Parameter Description

endTime

Optional parameter. Only show Credits that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

type

Optional parameter. Only show Credits that are either credit which means added or debit which means reduced.

startTime

Optional parameter. Only show Credits that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note: that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Parameter Description

dateCreated

Sort by created date

Response Body

The response body will carry code, corresponding message and data of the Credit if it was successfully fetched. HTTP response will be 200 OK.

The response returned is the JSON body as shown in the example below. Parameters are as explained below:

Data Parameter Description

data

Actual data in form of a list that matches the filter criteria. Data as explained in "Data Parameter" below.

num_pages

Number of pages

pageSize

Size of the page

total

Total number of records matching the given criteria.

start

Start offset of the current page

end

End offset of the current page

firstPageUri

URI to access first page

previous_page_uri

URI to access previous page

nextPageUri

URI to access next page

uri

URI of current page
Data Parameters
Data Parameter Description

enterpriseSid

SID of the Business Customer.

sid

Unique sid of Credit

dateCreated

Timestamp when this Credit was created.

dateUpdated

Timestamp when this Credit was updated.

accountSid

Account Sid of Account that added/reduced this credit.

accountEmail

Email corresponding to accountSid

description

Description passed in request

credit

Credit that was added (+ve value) or reduced (-ve value)

Example

From the bash terminal you can run the command below:

curl -X GET \https://yourdomain.com/campaignmanager/credits/search?enterprriseSid=EN6c9dfebda23b403a959a99112437e785 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

Below is the response returned:

{
   "page":0,
   "num_pages":3,
   "page_size":2,
   "total":6,
   "start":0,
   "end":1,
   "uri":"/campaignmanager/credits/search",
    "first_page_uri":"/ campaignmanager/credits/search?pageSize=2&page=0",
   "previous_page_uri":null,
   "next_page_uri":"/ campaignmanager/credits/search?pageSize=2&page=1",
   "data":[
       {
                "sid": "ENCee320039e3e647eaa7df7cef5e3d6b55",
                "dateUpdated": "2020-08-31T07:36:21+0000",
                "dateCreated": "2020-08-31T07:36:21+0000",
                "accountSid": "ACb06dc1c0b555df46a02ccaea1cb11bc1",
                "accountEmail": "cpadmin@company.com",
                "description": "SMS credits",
                "credit": 1000
            },
            {
                "sid": "ENCec4ef69e91294de48862db3772ab2959",
                "dateUpdated": "2020-08-31T07:42:53+0000",
                "dateCreated": "2020-08-31T07:42:53+0000",
                "accountSid": "ACb06dc1c0b555df46a02ccaea1cb11bc1",
                "accountEmail": "cpadmin@company.com",
                "credit": 100
            },
            {
                "sid": "ENC79acd62882a245aab15045a962a216e4",
                "dateUpdated": "2020-08-31T07:44:20+0000",
                "dateCreated": "2020-08-31T07:44:20+0000",
                "accountSid": "ACb06dc1c0b555df46a02ccaea1cb11bc1",
                "accountEmail": "cpadmin@company.com",
                "description": "Reducing by 10 on 31 Aug 2020, 1:24PM",
                "credit": -10
            }
  ]
}

Get Single Credit

The Single Credit search API allows users to retrieve a specific Credit.

Base Resource URI

https://$DOMAIN

Get Single User Resource URI

/campaignmanager/credits/search/{creditSid}

Supported Operations

HTTP Get: Get Specific Credit

Request Parameters

Parameter Description

creditSid

SID to uniquely identify a Credit

Response Body

The Response Body will carry the Code, corresponding message, and data of the Credit if it was successfully searched. HTTP response will be 200 OK.

Error Code HTTP Status Error Message Description Category

472

409

Credit not found

Credit SID doesn’t exist in the system

Get Credit

The response returned is the JSON body as shown in the example below. Parameters are listed below.

Parameter Description

data

Credit data as explained in the Data Parameter of List Credit.

code

Sub-error code for response

message

Message describing error if error occurred or success message

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://yourdomain.com/campaignmanager/credits/search/ENCee320039e3e647eaa7df7cef5e3d6b55 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
         "code":”200”,
         "message":"OK",
         “data”:
            {
                "sid": "ENCee320039e3e647eaa7df7cef5e3d6b55",
                "dateUpdated": "2020-08-31T07:36:21+0000",
                "dateCreated": "2020-08-31T07:36:21+0000",
                "accountSid": "ACb06dc1c0b555df46a02ccaea1cb11bc1",
                "accountEmail": "cpadmin@company.com",
                "description": "SMS credits",
                "credit": 1000
            }
}

Campaign

Campaign Status

A campaign can be in one of the following states:

  • Initiating: The Campaign is getting created.For example setting up From numbers, To numbers and Body.Ideally the Campaign will remain in this state for a very short time.If there are any errors in processing From or To numbers, the Campaign will directly move to a Failed state.

  • Scheduled: The Campaign is Scheduled.This means the Campaign Manager has all the resources and data it needs to execute this Campaign when Scheduled time kicks in.The only option to move Campaign, via API call, from a Scheduled state is to Cancelled state.

  • Cancelled: When a scheduled Campaign is Cancelled.

  • InProgress: The Campaign is in Progress.This state automatically kicks in when scheduled time has arrived.The only possible transition from this state is either Completed or Failed

  • Completed: Once all SMS are successfully sent to the underlying platform, the Campaign is marked as completed.It doesn’t depend on the state of SMS, for example whether it is Delivered or not.

  • Failed: If the Campaign failed for some reason or cannot setup data correctly from the initiating state.

The life cycle of Campaign’s Status is as below:

campaign status

Create Campaign

The Create Campaign API is used to create SMS/ VOICE Campaigns.

Base Resource URI

https://$DOMAIN

Create Campaign Resource URI

/campaignmanager/campaigns

Supported Operations

HTTP POST: Create Campaign

Request Parameters

Parameter Description

dialTimeout

Optional. This parameter is used only if the channel is voice. It mentions how many seconds the call should be RINGING before disconnecting the call as explained here. Default is 30 seconds

name

Mandatory. The name of the campaign.

startTime

Optional. Date when Campaign is to be started given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note: that the given date/time is inclusive and is assumed to be in UTC timezone.
If startTime is not passed, Campaign is scheduled immediately

fromPrefix

The prefix for country code for source/origin address, Campaign Manager application will automatically generate random source address with specific prefix. fromPrefix is mandatory if fromFile parameter is not passed.

fromFile

Mandatory. The source/origin phone address. Multipart File values can be passed as new line separated. In case of multiple values passed, each address will be used as round robin for the given number of to addresses. fromFile is mandatory if fromPrefix is not passed. In case both are passed fromPrefix is ignored.

toFile

Mandatory. The destination address. Multipart File values can be passed as new lines separated.

optOut

Optional. The Name of the Opt-Out database. The only possible value is "Opt-Out".

optInx

Optional. The Name of the Opt-In database.

channel

Optional. "channel" specifies if the Campaign is of SMS or Voice Call. Only possible values it can take is
* sms
* voice
If not passed, default is sms.

body

Mandatory if channel is omitted or sms is passed.
The SMS Body.

announcementSid

Optional. The Announcement that should be played for Voice Call.
This parameter is needed only if the channel is voice. For Voice either of rcmlUrl or announcementSid should be passed. If both announcementSid and rcmlUrl is passed, announcementSid takes preference.

rcmlUrl

Optional. This URL should return the RCML as explained https://$DOMAIN/docs/rcml/overview.html
This parameter is needed only if the channel is voice. For Voice either of rcmlUrl or announcementSid should be passed. If both announcementSid and rcmlUrl is passed, announcementSid takes preference.

Response Body

The response body will contain the code, corresponding message, and data of the Application if it was successfully created. HTTP response will be 201 Created(OK).

The response returned is the JSON body as shown in the example below. Parameters are as explained below:

Parameter Description

data

Campaign data as explained in the table below.

code

Sub-error code for response

message

Message describing error if error occured or success message
Data Parameters
Data Parameter Description

body

The SMS body applied on this Campaign

sid

Unique sid identity for Campaign

name

Name of the Campaign

dateCreated

Date when Campaign was created given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note: that the given date/time is inclusive and is assumed to be in UTC timezone.

dateUpdated

Date when Campaign was updated given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

startTime

Date when Campaign is to be started given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

enterpriseSid

The Business Customer sid to which the Campaign belongs.

total

The number of credits used for this Campaign.

Status

The status of the campaign as explained earlier.

fromPrefix

The prefix for country code for source/origin address, campaignmanager application will automatically generate random source address with specific prefix.

channel

"channel" specifies if the Campaign is for SMS or Voice Call

rcmlUrl

URL from which RCML payload is taken

announcementSid

Announcement Sid from which Voice is played

dialTimeout

How many seconds the call should be RINGING before disconnecting the call as explained here.

The Create Campaign API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, seen below are the Errors that it can return.

Error Code HTTP Status Error Message Description Category

498

Date format is incorrect. Supported format is ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32)

startDate format is incorrect. Supported date format is ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Create Campaign

489

409

Start Time is in past

Campaign is defined with a start date in the past.

Create Campaign

500

409

Announcement not found

Announcement Id does not exists

Update, Delete, Get Announcement, Create Campaign

488

409

Credit is not enough

Not enough credit to create new Campaign

Create Campaign

Example

SMS Campaign Example
{
    "name" : "Camp4-18Mar-1222",
    "startTime":"2021-03-18T12:20:46+0530",
    "fromPrefix":"91",
    "toFile":"<path to file having To numbers separated by new line>"
    "optOut": "Opt-Out",
    "optIn": "ACME-opt-in"
    "body":"Happy New Year"
}

From the bash terminal you can run the command below:

curl -X POST \
  https://company.com/campaignmanager/campaigns \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: multipart/form-data' \
  -F name="Test campaign TTS 18Mar1217" \
  -F body="Hello World 1" \
  -F toFile="@/Users/workspace/Solutions/SMSBlast/MXOrgTest2-Ent2-ToNumbers.csv" \
  -F optOut="Opt-Out" \
  -F optIn="ACME-opt-in" \
  -F fromPrefix="91"

If creation of campaign is successful, below is the response returned:

{
    "data": {
        "sid": "ECd96d3e5e57b7445e8db19b5e77146ca8",
        "dateUpdated": "2021-03-18T06:50:43+0000",
        "dateCreated": "2021-03-18T06:50:43+0000",
        "accountSid": "ACd29f41f95a13ff47279f8f71ccbbb4fe",
        "accountEmail": "jane.doe@company.com",
        "uri": "/campaignmanager/campaigns/search/ECd96d3e5e57b7445e8db19b5e77146ca8",
        "name": "Camp4-18Mar-1222",
        "startTime": "2021-03-18T06:52:46+0000",
        "enterpriseSid": "EN38347f3735b04741a0c9be689901e6b4",
        "total": 4,
        "status": "initiating",
        "fromPrefix": "91",
        "body": "Hello World 1",
        "optOut":"Opt-Out",
        "optIn":"ACME-opt-in"
    },
    "code": 200,
    "message": "OK"
}
Voice Campaign Example
    "name" : "Test campaign TTS 18Mar1217",
    "startTime":"2021-03-18T12:35:46+0530",
    "fromFile":"<path to file having From numbers separated by new line>",
    "toFile":"<path to file having To numbers separated by new line>"
    "announcementSid":"AN3f01da2b10d84f7f92f5b7aaced20a94”,
    "channel":"voice",
    "optOut": "Opt-Out",
    "optIn": "ACME-opt-in",
    "dialTimeout":"10"

From the bash terminal you can run the command below:

curl -X POST \
  https://company.com/campaignmanager/campaigns \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: multipart/form-data' \
 -F name="Test campaign TTS 18Mar1217" \
 -F startTime=”2021-03-18T12:35:46+0530” \T
 -F toFile="@/Users/workspace/Solutions/SMSBlast/MXOrgTest2-Ent2-ToNumbers.csv" \
 -F toFile="@/Users/workspace/Solutions/SMSBlast/MXOrgTest2-Ent2-FromNumbers.csv" \
 -F announcementSid=”AN3f01da2b10d84f7f92f5b7aaced20a94” \
 -F optOut="Opt-Out" \
 -F optIn="ACME-opt-in" \
 -F channel=”voice” \
 -F dialTimeout=”10”

If creation of campaign is successful, below is the response returned:

{
    "data": {
        "sid": "ECc28117d340f04f0581d60dc4ca2453ca",
        "dateUpdated": "2021-03-18T06:59:56+0000",
        "dateCreated": "2021-03-18T06:59:56+0000",
        "accountSid": "ACd29f41f95a13ff47279f8f71ccbbb4fe",
        "accountEmail": "jane.doe@company.com",
        "uri": "/campaignmanager/campaigns/search/ECc28117d340f04f0581d60dc4ca2453ca",
        "name": "Test campaign TTS 18Mar1217",
        "startTime": "2021-03-18T07:05:46+0000",
        "enterpriseSid": "EN38347f3735b04741a0c9be689901e6b4",
        "total": 1,
        "status": "initiating",
        "fromPrefix": "",
        "announcementSid": "AN3f01da2b10d84f7f92f5b7aaced20a94",
        "channel": "voice",
        "dialTimeout": "10",
        "optOut":"Opt-Out",
        "optIn":"ACME-opt-in"
    },
    "code": 200,
    "message": "OK"
}
Error example

If creation fails, below response is returned with corresponding HTTP Error Code

{
  "code":489,
  "message”: “startTime is  in the past
   “data”:{
    "name" : "TestCampaign",
     “startTime”:”2019-01-01 09:53:51”,
    “fromPrefix”:”91”,
    “to”:”919960639903,919960639904,919960639905,919960639906”
    “body”:”Hello World”
  }
}

Update Campaign

This endpoint will be used to update existing campaigns.Only campaigns with a status of Scheduled can be updated.If the status of the campaign changes to any other, updating is no longer possible.

Base Resource URI

https://$DOMAIN

Update Context Resource URI

/campaignmanager/campaigns/{CampaignSid}

Supported Operations

HTTP PUT: Update Campaign

Request Parameters

Parameter Description

status

Status of campaign can be “canceled” only if existing status is “scheduled”. No other status change is supported as of today.

CampaignSid

Unique Campaign Sid that was generated when Campaign was created first time as explained in the "Create Campaign" section

No other parameters of Campaigns can be updated apart from status.

Response Body

The response body will carry code, corresponding message and data of Application if it was successfully Updated. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Parameters are as explained below.

Parameter Description

data

Campaign data as explained in the data parameter of create campaign.

code

Sub-error code for response

message

Message describing error if error occured or success message

Update Campaign API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, seen below are the Errors that it can return.

Error Code HTTP Status Error Message Description Category

487

409

Campaign status cannot be updated

User is trying to change the status of Campaign which is not acceptable as per Campaign State Machine.

Update Campaign

486

409

Enterprise campaign not found

User is trying to update or delete campaign passing invalid Campaign sid

Update or Delete Campaign

483

409

Campaign status is invalid

User is trying to change the status of the Campaign to invalid value.

Update Campaign

Example

{
"status" : "cancelled"
}

From the bash terminal you can run the command below:

curl -X PUT \
  https://yourdomain.com/campaignmanager/campaigns/CPb6eb071d21124dbab20b095c25f1274f \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
        "status" : "cancelled"
}'

If update of Campaign is successful, below is the response returned:

{
"code":200,
"message":"OK",
“data”:
   {
        “sid":"CPb6eb071d21124dbab20b095c25f1274f",
        “name”:”TestUpdatedCampaign”,
        "dateCreated":"2019-12-22 09:53:51",
        "dateUpdated":"2019-12-29 09:53:51",
        “startTime”:”2020-02-01 09:53:51”,
        “enterpriseSid” :”ENb6eb071d21124dbab20b095c25f1274f”,
        “total”:”4”,
        “status”:”canceled”,
        “fromPrefix”:”91”,
        “to”:”919960639903,919960639904,919960639905,919960639906”
        “body”:”Hello World. This is 2nd Jan 2020!”
        "uri":/campaignmanager/enterprise/campaign/search/CPb6eb071d21124dbab20b095c25f1274f"
     }
}

If update fails, below response is returned with corresponding HTTP Error Code

{
  "code":486,
  "message”: “Campaign not found
   “data”:{
        “sid":"CPb6eb071d21124dbab20b095c25f1274f",
        "status" : "canceled"
  }
}

Delete Campaign

This endpoint will be used to delete existing campaigns.Only campaigns with a status of Scheduled can be deleted.If the status of the campaign changes to any other, deleting is no longer possible.

Base Resource URI

https://$DOMAIN

Update Context Resource URI

/campaignmanager/campaigns/{CampaignSid}

Supported Operations

HTTP DELETE: Delete Campaign

Request Parameters

Parameter Description

CampaignSid

Unique Campaign Sid that was generated when Campaign was first created, as explained in Create Campaign section

Response Body

The response body will carry code, corresponding message and data of Application if it was successfully Updated. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Parameters are as explained below.

Parameter Description

data

Campaign data as explained in the data parameter of create campaign.

code

Sub-error code for response

message

Message describing error if error occured or success message

Delete Campaign API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, seen below are the Errors that it can return.

Error Code HTTP Status Error Message Description Category

464

409

Campaign status not "Scheduled"

Campaign is in different status than "Scheduled". This means campaign is already started and now it cannot be updated.

Update Campaign, Delete Campaign

463

409

Campaign not found

Campaign SID doesn’t exist in the system or probably assigned to some other Organization where existing user doesn’t have permission to access.

Update Campaign, Delete Campaign, List Single Campaign

Example

From the bash terminal you can run the command below:

curl -X DELETE \
  https://yourdomain.com/campaignmanager/campaigns/CPb6eb071d21124dbab20b095c25f1274f \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

If delete of Campaign is successful, below is the response returned:

{
"code":200,
"message":"OK",
“data”:
   {
        “sid":"CPb6eb071d21124dbab20b095c25f1274f",
        “name”:”TestUpdatedCampaign”,
        "dateCreated":"2019-12-22 09:53:51",
        "dateUpdated":"2019-12-30 09:53:51",
        “startTime”:”2020-02-01 09:53:51”,
        “enterpriseSid” :”ENb6eb071d21124dbab20b095c25f1274f”,
        “total”:”4”,
        “status”:”Scheduled”,
        “fromPrefix”:”91”,
        “to”:”919960639903,919960639904,919960639905,919960639906”
        “body”:”Hello World. This is 2nd Jan 2020!”
        "uri":/campaignmanager/enterprise/campaign/search/CPb6eb071d21124dbab20b095c25f1274f"
     }
}

If deletion fails, below response is returned with corresponding HTTP Error Code

{
  "code":463,
  "message”: “Campaign not found
   “data”:{
        “sid":"CPb6eb071d21124dbab20b095c25f1274f"
  }
}

Get List of Campaigns

This endpoint will be used to retrieve a list of campaigns.

Base Resource URI

https://$DOMAIN

Get List of Campaigns Resource URI

/campaignmanager/campaigns/search

Supported Operations

HTTP GET: List Campaigns

Paging

The following paging parameters are supported

Query Parameter Description

pageSize

Number of records returned per page

page

Which page of Campaigns records to return, starting from 0.
If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

Following filtering parameters are supported:

Query Parameter Description

endTime

Optional parameter. Only show Contexts that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

name

Optional parameter. Only show Campaigns that match name text, partially or fully.

status

Optional parameter. Only show campaigns having selected status. Possible value of status are as explained in campaign status section.

channel

Optional parameter. Only show campaigns that have channel matching.

startTime

Optional parameter. Only show Contexts that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. You can sort by the following attributes:

Sort Attributes
Parameter Description

startTime

Sort by startTime

name

Sort by name

status

Sort by status

Response Body

The response body will carry code, corresponding message, and data of Campaigns if it was successfully fetched. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Parameters are as explained below.

data Actual data in form of a list that match the filter criteria. Campaign data as explained in the data parameter of create campaign.

uri

URI of current page

num_pages

Number of pages

page_size

Size of the page

total

Total number of records matching the given criteria.

start

Start offset of the current page

end

End offset of the current page

first_page_uri

URI to access first page

previous_page_uri

URI to access previous page

next_page_uri

URI to access next page

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://yourdomain.com/campaignmanager/campaigns/search?name=test \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

Below is the response returned:

{
   "page":0,
   "num_pages":3,
   "page_size":2,
   "total":6,
   "start":0,
   "end":1,
   "uri":"/campaignmanager/campaigns/search",
    "first_page_uri":"/ campaignmanager/campaigns/search?pageSize=2&page=0",
   "previous_page_uri":null,
   "next_page_uri":"/ campaignmanager/campaigns/search?pageSize=2&page=1",
   "data":[
       {
        “sid":"CPb6eb071d21124dbab20b095c25f1274f",
        “name”:”TestUpdatedCampaign”,
        "dateCreated":"2019-12-22 09:53:51",
        "dateUpdated":"2019-12-30 09:53:51",
        “startTime”:”2020-02-01 09:53:51”,
        “enterpriseSid” :”ENb6eb071d21124dbab20b095c25f1274f”,
        “total”:”4”,
        “status”:”Scheduled”,
        “fromPrefix”:”91”,
        “to”:”919960639903,919960639904,919960639905,919960639906”
        “body”:”Hello World. This is 2nd Jan 2020!”
        "uri":/campaignmanager/campaigns/search/CPb6eb071d21124dbab20b095c25f1274f"
       } ,
       {
        “sid":"CPb6eb071d21124dbab20b095c25f1274g",
        “name”:”Marketing 1 Campaign”,
        "dateCreated":"2019-12-22 09:53:51",
        "dateUpdated":"2019-12-30 09:53:51",
        “startTime”:”2020-03-01 09:53:51”,
        “enterpriseSid” :”ENb6eb071d21124dbab20b095c25f1274f”,
        “total”:”4”,
        “status”:”Scheduled”,
        “fromPrefix”:”91”,
        “to”:”919960639903,919960639904,919960639905,919960639906”
        “body”:”Buy 1 get 1 free from Benetton World!”
        "uri":/campaignmanager/campaigns/search/CPb6eb071d21124dbab20b095c25f1274g"
       }
  ]
}

Get Single Campaign

The Single Campaign search API allows users to retrieve specific Campaigns.

Base Resource URI

https://$DOMAIN

Get Single Campaign Resource URI

/numbermasking/campaigns/search/{CampaignSid}

Supported Operations

HTTP GET: Specific Campaign

Request Parameters

Parameter Description

CampaignSid

SID to uniquely identify a Campaign

Response Body

The Response Body will carry Code, corresponding message, and data of User if it was successfully searched. HTTP response will be 200 OK.

Error Code HTTP Status Error Message Description Category

463

409

Campaign not found

Campaign SID doesn’t exist in the system or probably assigned to some other Organization where existing user doesn’t have permission to access.

Update Campaign, Delete Campaign, List Single Campaign

The response returned is JSON body as shown in the example below. Parameters are as explained below.

Parameter Description

data

Campaign data as explained in the data parameter of create campaign.

code

Sub-error code for response

message

Message describing error if error occured or success message

Example

From the bash terminal you can run the command below:

curl -X DELETE \
  https://yourdomain.com/campaignmanager/campaigns/search/CPb6eb071d21124dbab20b095c25f1274f \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
         "code":”200”,
         "message":"OK",
         “data”:
       {
        “sid":"CPb6eb071d21124dbab20b095c25f1274f",
        “name”:”TestUpdatedCampaign”,
        "dateCreated":"2019-12-22 09:53:51",
        "dateUpdated":"2019-12-30 09:53:51",
        “startTime”:”2020-02-01 09:53:51”,
        “enterpriseSid” :”ENb6eb071d21124dbab20b095c25f1274f”,
        “total”:”4”,
        “status”:”Scheduled”,
        “fromPrefix”:”91”,
        “to”:”919960639903,919960639904,919960639905,919960639906”
        “body”:”Hello World. This is 2nd Jan 2020!”
        "uri":/campaignmanager/enterprise/campaign/search/CPb6eb071d21124dbab20b095c25f1274f"
         }
}

Announcement

Announcements are used in Voice Campaigns.Users can create simple play announcements that play audio file uploaded or text-to-speech announcements.

Create Announcement

This API will create an Announcement for an Enterprise.

Base Resource URI

https://$DOMAIN

Add Announcement Resource URI

/campaignmanager/announcement

Supported Operations

HTTP POST: Add announcement

Request Parameters

Parameter Description

voice

Mandatory if type is “say”.
Voice of speech. Only possible values are “man” and “woman”

name

Mandatory. Name of the announcement

description

Optional. Description about the announcement.

enterpriseSid

Mandatory. Sid of the enterprise the announcement belongs to.

type

Mandatory. Type of announcement. Only options are as below
* say : Make an announcement from Text to speech in which case below parameters are mandatory
* play : Make an announcement by playing an audio file. In this case Upload announcement file should be called to upload Announcement File.

body

Mandatory if type is “say”.
Text to speech body.

language

Mandatory if type is “say”.
Language for Text to speech as explained in <say> verb of Core Engine

Response Body

The Response Body will carry the Code, corresponding message and data of the Announcement File if it was successfully created. HTTP response will be 200 Created (OK).

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

data

Announcement File data as explained in the table below.

code

Sub-error code for response

message

Message describing error if error occured or success message
Data Parameters
Data Parameter Description

voice

Voice of speech. Possible values are “man” or “woman”

sid

Unique announcement Id

name

Name of announcement

description

Description about the announcement.

accountEmail

Unique CPaaS Account that created this particular announcement

dateCreated

Timestamp when this announcement was created

dateUpdated

Timestamp when this announcement was updated

uri

Unique URI that you can call to get only this specific announcement

enterpriseSid

Sid of the enterprise the announcement belongs to.

file_uri

The File URI for this recording, relative to https://$DOMAIN. It can be used to access the WAV file

type

Type of announcement. Only options are as below
* say : Make an announcement from Text to speech in which case below parameters are mandatory
* play : Make an announcement by playing an audio file.

body

Text to speech body.

language

Language for Text to speech as explained in <say> verb of Core Engine
Response Parameters

Create announcement API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code

Error Code HTTP Status Error Message Description Category

522

409

Announcement voice type should be man or woman.

Passed invalid "voice" for say announcement

Create, Update Announcement

467

409

Enterprise not found

Enterprise for which the announcement is to be added is not found.

Create Announcement

500

409

Announcement not found

Announcement Id not exists

Update, Delete, Get Announcement, Create Announcement

4000

409

Mandatory parameter missing. Xxx needs to be passed.

Any Mandatory parameters not passed

Create Announcement

521

409

Announcement Language Not Found

Passed invalid language for say Announcement

Create Announcement

Example

Create Text To Speech Announcement
{
    "enterpriseSid": "EN38347f3735b04741a0c9be689901e6b4",
    "name": "TTS Play 19Mar21-852",
    "type": "say",
    "body": "Hello, we aree giving away 20% discounts on all our merchandise. Hurry offer valid only for next 3 days.",
    "language": "google.ar-XA-Standard-A",
    "voice": "woman"
}

From the bash terminal you can run the command below:

curl -X POST \
  https://company.com/autoattendant/announcement\
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "enterpriseSid": "EN38347f3735b04741a0c9be689901e6b4",
    "name": "TTS Play 19Mar21-852",
    "type": "say",
    "body": "Hello, we aree giving away 20% discounts on all our merchandise. Hurry offer valid only for next 3 days.",
    "language": "google.ar-XA-Standard-A",
    "voice": "woman"
}’

If creation of announcement is successful, below is the response returned:

{
    "data": {
        "sid": "AN77564ea97c8d4ad1a17a3da3775222dd",
        "dateUpdated": "2021-03-19T06:06:55+0000",
        "dateCreated": "2021-03-19T06:06:55+0000",
        "accountEmail": "jane.doe@company.com",
        "uri": "/campaignmanager/announcement/search/AN77564ea97c8d4ad1a17a3da3775222dd",
        "name": "TTS Play 19Mar21-852",
        "enterpriseSid": "EN38347f3735b04741a0c9be689901e6b4",
        "type": "say",
        "body": "Hello, we aree giving away 20% discounts on all our merchandise. Hurry offer valid only for next 3 days.",
        "language": "google.ar-XA-Standard-A",
        "voice": "woman"
    },
    "code": 200,
    "message": "OK"
}
Create Play Announcement
{
    "enterpriseSid": "EN38347f3735b04741a0c9be689901e6b4",
    "name": "Ann Play 19mar958",
    "type": "play"
}

From the bash terminal you can run the command below:

curl -X POST \
  https://company.com/autoattendant/announcement\
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "enterpriseSid": "EN38347f3735b04741a0c9be689901e6b4",
    "name": "Ann Play 19mar958",
    "type": "play"
}’

If creation of announcement is successful, below is the response returned:

{
    "data": {
        "sid": "AN14075c11fbb84c049702e0e4560498fb",
        "dateUpdated": "2021-03-19T06:08:28+0000",
        "dateCreated": "2021-03-19T06:08:28+0000",
        "accountEmail": "jane.doe@company.com",
        "uri": "/campaignmanager/announcement/search/AN14075c11fbb84c049702e0e4560498fb",
        "name": "Ann Play 19mar958",
        "fileUri": "/campaignmanager/internal/announcement/file/AN14075c11fbb84c049702e0e4560498fb_1616134108629.wav",
        "enterpriseSid": "EN38347f3735b04741a0c9be689901e6b4",
        "type": "play"
    },
    "code": 200,
    "message": "OK"
}
After this you need to call Upload Announcement API endpoint to upload the Audio File
Create Announcement Error

If the creation of the announcement fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "467",
    "message": "Enterprise not found",
    "data": {
        "sid": "EN838bcdf35f9d421fad3ab516195b873"
    }
}

Upload announcement file:

This API will upload an audio file for the announcement.

Base Resource URI

https://$DOMAIN

Upload Announcement Resource URI

/campaignmanager/internal/file/announcement/{announcementSid}

Supported Operations

HTTP POST: Upload audio file

Request Parameters

Parameter Description

file

Mandatory.
Audio file in wav format to be uploaded in the recommended bitrate.
Please visit Media Server Audio File Format to understand more about supported audio file formats.

announcementSid

Mandatory. Sid to uniquely identify an announcement.

Response Body

The Response Body will carry the Code, corresponding message and data of the Announcement File if it was successfully uploaded. HTTP response will be 200 Created (OK).

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

data

Announcement File data as explained in the table below.

code

Sub-error code for response

message

Message describing error if error occured or success message
Data Parameters
Data Parameter Description

fileUri

The File URI for this recording, relative to https://$DOMAIN. It can be used to access the WAV file
Rest of the response parameters are the same as explained in Response Parameter of Create Announcement.
Response Parameters

Create announcement API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code

Error Code HTTP Status Error Message Description Category

4000

409

Mandatory parameter missing. fileUri need to be passed

Mandatory parameter fileUri was not passed

500

409

Announcement not found

AA System for which the announcement is to be added is not found.

Upload File

504

409

Error in uploading audio file

format is not a wav file.
error occurred while uploading file to s3

Upload File

Example

curl --location --request POST 'https://company.com/autoattendant/internal/announcement/file/ANd28fddd7f6184a67aacb2dd6c3c00e28' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Basic ***********' \
--form 'file=@/Users/adityad/Documents/ANd28fddd7f6184a67aacb2dd6c3c00e28.wav'

If creation of announcement is successful, below is the response returned:

{
    "data": {
        "sid": "AN42b3d3e952ff47ecba9d487095a2bc4e",
        "dateUpdated": "2020-01-27T06:44:13+0000",
        "dateCreated": "2020-01-27T06:44:13+0000",
        "accountEmail": "jane.doe@company.com",
        "uri": "/autoattendant/announcement/search/AN42b3d3e952ff47ecba9d487095a2bc4e",
        "name": "Sale announcement",
        "description": "Announcement for sale of merchandise",
        "fileUri": "/autoattendant/announcement/file/AN42b3d3e952ff47ecba9d487095a2bc4e_1580107453296.wav",
        "enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b"
    },
    "code": 200,
    "message": "OK"
}

If the upload of the audio file fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "500",
    "message": "Announcement not found",
    "data": {
        "sid": "ANd28fddd7f6184a67aacb2dd6c3c00e28"
    }
}

Update Announcement

Update announcement will update an existing announcement

Base Resource URI

https://$DOMAIN

Update Announcement Resource URI

/campaignmanager/announcement/{announcementSid}

Supported Operations

HTTP PUT: Update announcement

Request Parameters

Parameter Description

voice

Mandatory if type is “say”.
Voice of speech. Only possible values are “man” and “woman”

announcementSid

Mandatory. Unique Id of the announcement

name

Optional. Name of the announcement

description

Optional. Description about the announcement.

type

Mandatory. Type of announcement. Only options are as below
* say : Make an announcement from Text to speech in which case below parameters are mandatory
* play : Make an announcement by playing an audio file. In this case Upload announcement file should be called to upload Announcement File.

body

Mandatory if type is “say”.
Text to speech body.

language

Mandatory if type is “say”.
Language for Text to speech as explained in <say> verb of Core Engine

Response Body

The response body will carry code, corresponding message and Announce data if update was successful.

Parameter Description

data

Announcement data as explained in the data parameter of create Announcement.

code

Sub-error code for response

message

Message describing error if error occured or success message
Response Parameters

Update announcement API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code

Error Code HTTP Status Error Message Description Category

4000

409

Mandatory parameter missing. xxx needs to be passed.

Any Mandatory parameters not passed

Create Announcement

500

409

Announcement not found

Announcement Id not exists

Update, Delete, Get Announcement, Create Announcement

521

409

Announcement Language is not supported

Passed invalid language for say Announcement

Create, Update Announcement

522

409

Announcement voice type should be man or woman.

Passed invalid "voice" for say announcemnet

Create, Update Announcement

Example

{
    "name": "TTS Play 19Mar21-852 Updated",
    "description": "TTS Play Ann description",
    "type": "say",
    "body": "Hello, we aree giving away 20% discounts on all our merchandise. Hurry offer valid only for next 5 days.",
    "language": "google.ar-XA-Standard-A",
    "voice": "man"
}

From the bash terminal you can run the command below:

curl -X PUT \
  https://company.com/campaignmanager/announcement/AN77564ea97c8d4ad1a17a3da3775222dd\
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d ‘{
    "name": "TTS Play 19Mar21-852 Updated",
    "description": "TTS Play Ann description",
    "type": "say",
    "body": "Hello, we aree giving away 20% discounts on all our merchandise. Hurry offer valid only for next 5 days.",
    "language": "google.ar-XA-Standard-A",
    "voice": "man"
}’

If updating the announcement is successful, below is the response returned:

{
    "data": {
        "sid": "AN77564ea97c8d4ad1a17a3da3775222dd",
        "dateUpdated": "2021-03-25T06:22:27+0000",
        "dateCreated": "2021-03-19T06:06:55+0000",
        "accountEmail": "jane.doe@company.com",
        "uri": "/campaignmanager/announcement/search/AN77564ea97c8d4ad1a17a3da3775222dd",
        "name": "TTS Play 19Mar21-852 Updated",
        "description": "TTS Play Ann description",
        "enterpriseSid": "EN38347f3735b04741a0c9be689901e6b4",
        "type": "say",
        "body": "Hello, we aree giving away 20% discounts on all our merchandise. Hurry offer valid only for next 5 days.",
        "language": "google.ar-XA-Standard-A",
        "voice": "man"
    },
    "code": 200,
    "message": "OK"
}

If the update of the announcement fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "500",
    "message": "Announcement not found",
    "data": {
        "sid": "ANf1ef82a9fecd4ee2b367e96c98aaf82"
    }
}

Delete Announcement

Delete announcement will delete an existing announcement

Base Resource URI

https://$DOMAIN

Delete Announcement Resource URI

/campaignmanager/announcement/{announcementSid}

Supported Operations

HTTP DELETE: Delete announcement

Request Parameters

Parameter Description

announcementSid

SID to uniquely identify an announcement

Response Body

The response body will carry code, corresponding message and Announcement data if delete was successful.

Parameter Description

data

Announcement data as explained in the data parameter of create Announcement.

code

Sub-error code for response

message

Message describing error if error occured or success message
Response Parameters

Delete announcement API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code

Error Code HTTP Status Error Message Description Category

507

409

This Announcement cannot be deleted as it is being used in a campaign.

Announcement is used in Campaign

Delete Announcement

500

409

Announcement not found

Announcement SID doesn’t exist in the system

Update Announcement, Delete Announcement, Get Announcement

Example

From the bash terminal you can run the command below:

curl -X DELETE \
  https://company.com/campaignmanager/announcement/AN9701e246abfe4b839bcfad37c228ab67 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If deleting the announcement is successful, below is the response returned:

{
    "data": {
        "sid": "AN9701e246abfe4b839bcfad37c228ab67",
        "dateUpdated": "2021-03-14T02:08:11+0000",
        "dateCreated": "2021-03-09T07:10:51+0000",
        "accountEmail": "jane.doe@company.com",
        "uri": "/campaignmanager/announcement/search/AN9701e246abfe4b839bcfad37c228ab67",
        "name": "Ann TTS",
        "enterpriseSid": "EN38347f3735b04741a0c9be689901e6b4",
        "type": "say",
        "body": "Hello World. This is announcement text to speech test for campaign manager",
        "language": "google.ar-XA-Standard-A",
        "voice": "female"
    },
    "code": 200,
    "message": "OK"
}

If deleting of the announcement fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "507",
    "message": "This Announcement cannot be deleted as it is being used in a campaign.",
    "data": {
        "sid": "AN77564ea97c8d4ad1a17a3da3775222dd"
    }
}

Get list of Announcement

This endpoint will be used to get list of announcements

Base Resource URI

https://$DOMAIN

Get Announcement List Resource URI

/campaignmanager/announcement/search

Supported Operations

HTTP GET: Get Announcement list

Paging

The following paging parameters are supported

Query Parameter Description

pageSize

Number of records returned per page

page

Which page of Announcements records to return, starting from 0.
If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

Following filtering parameters are supported:

Query Parameter Description

endTime

Optional parameter. Only show users that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

name

Optional parameter. Only show Announcements that match name text, partially or fully.

enterpriseSid

Optional parameter. Only show announcements for specific enterprises.

startTime

Optional parameter. Only show users that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Sort Attributes
Parameter Description

dateCreated

Sort by created date

name

Sort by name

Response Body

The response body will carry code, corresponding message and data of Announcement if it was successfully fetched. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

data

data of search as explained in table below

code

Sub-error code for response

message

Message describing error if error occured or success message
Data parameters
Data Parameter Description

uri

Unique URI that you can call to get records

result

Announcement data as explained in the data parameter of create Announcement.

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

Unique URI that you can call to get records in First page

nextPageUri

Unique URI that you can call to get records in next page

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://company.com/campaignmanager/announcement/search?sortBy=name:asc&page=0&pageSize=2\
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

Below is the response returned:

{
    "data": {
        "result": [
            {
                "sid": "AN3f01da2b10d84f7f92f5b7aaced20a94",
                "dateUpdated": "2021-03-17T03:38:45+0000",
                "dateCreated": "2021-03-17T03:38:45+0000",
                "accountEmail": "cm_bc1_testent3@mxorgtest2.com",
                "uri": "/campaignmanager/announcement/search/AN3f01da2b10d84f7f92f5b7aaced20a94",
                "name": "Ann Play",
                "fileUri": "/campaignmanager/internal/announcement/file/AN3f01da2b10d84f7f92f5b7aaced20a94_1615952325000.wav",
                "enterpriseSid": "ENd3766c7cb2234439b1dfb9f14ca1d80a",
                "type": "play"
            },
            {
                "sid": "AN16ac1003209c432381d5bd171c4b2e51",
                "dateUpdated": "2021-03-09T07:23:19+0000",
                "dateCreated": "2021-03-09T07:23:19+0000",
                "accountEmail": "jane.doe@company.com",
                "uri": "/campaignmanager/announcement/search/AN16ac1003209c432381d5bd171c4b2e51",
                "name": "AnnTTS4",
                "enterpriseSid": "ENd3766c7cb2234439b1dfb9f14ca1d80a",
                "type": "say",
                "body": "Hello World",
                "language": "google.ar-XA-Standard-A",
                "voice": "female"
            }
        ],
        "pageSize": 2,
        "total": 6,
        "page": 0,
        "numPages": 3,
        "start": 0,
        "end": 1,
        "firstPageUri": "/campaignmanager/announcement/search/?pageSize=2&sortBy=name:asc&page=0",
        "nextPageUri": "/campaignmanager/announcement/search/?pageSize=2&sortBy=name:asc&page=1",
        "uri": "/campaignmanager/announcement/search/?pageSize=2&sortBy=name:asc&page=0"
    },
    "code": 200,
    "message": "OK"
}

Get Single Announcement

Single Announcement search API allows users to retrieve specific announcements.

Base Resource URI

https://$DOMAIN

Get Single Announcement Resource URI

/campaignmanager/announcement/search/{announementSid}

Supported Operations

HTTP GET: Specific announcement

Response Parameters

Search Announcement API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

Error Code HTTP Status Error Message Description Category

500

409

Announcement not found

Announcement is not found.

Delete Announcement, Update Announcement, Get Announcement

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://company.com/campaignmanager/announcement/search/AAEb6eb071d21124dbab20b095c25f1274f \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "sid": "AN42b3d3e952ff47ecba9d487095a2bc4e",
        "dateUpdated": "2020-01-27T06:44:13+0000",
        "dateCreated": "2020-01-27T06:44:13+0000",
        "accountEmail": "jane.doe@company.com",
        "uri": "/campaignmanager/announcement/search/AN42b3d3e952ff47ecba9d487095a2bc4e",
        "name": "Welcome announcement",
        "description": "Announcement made during working hours",
        "fileUri": "/campaignmanager/announcement/file/AN42b3d3e952ff47ecba9d487095a2bc4e_1580107453000.wav",
        "enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
        "type": "play"
    },
    "code": 200,
    "message": "OK"
}

In case of failure, the following response is returned.

{
    "errorCode": "500",
    "message": "Announcement not found",
    "data": {
        "sid": "AN42b3d3e952ff47ecba9d487095a2bc4"
    }
}

Do Not Disturb (DND)

The DND feature allows the Business Customers to:

  • Define Opt-Out Database

  • Define many explicit Opt-In Databases

  • Allow applying Opt-Out and/or Opt-In database while setting up campaigns

Create Opt-Out List

This API is used to update the Opt-Out List for Campaign Manager.

Base Resource URI

https://$DOMAIN

Add Opt-Out Resource URI

/campaignmanager/dnd/optout

Supported Operations

HTTP POST: Add Opt-Out List

Request Parameters

Parameter Description

file

Mandatory. Multipart File values can be passed separately as new lines.

Response Body

The Response Body will carry the Code, corresponding message and data of the Opt-Out if it was successfully created. The HTTP response will be 200 Created (OK).

The response returned is the JSON body as shown in the example below.

Parameter Description

data

Opt-Out data as explained in the table below.

code

Sub-error code for response

message

Message describing the error if such has occurred, or a success message, if successful.
Data Parameters
Data Parameter Description

enterpriseSid

Sid of the enterprise the Opt-Out belongs to.

name

Opt-Out name. The default value assigned to the name will be "Opt-Out".
Response Parameters

Create Opt-Out API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Codes.

Error Code HTTP Status Error Message Description Category

490

409

Dnd File numbers is not valid

Passed Invalid Opt-Out file

Create Opt-Out

Example

Create Opt-Out Database
{
    "file":"<path to file having the phone numbers separated by new line>"
}

From the bash terminal you can run the command below:

curl -X POST \
  https://company.com/campaignmanager/dnd/optout\
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -F file="@/Users/workspace/Solutions/OptOut/MXOrgTest2-Ent2-Numbers.csv" \

If the creation of the Opt-Out is successful, below is the response returned:

{
    "data":{
        "name":"Opt-Out",
        "enterpriseSid":"EN909628cbd8e9429899c0b474f2e96423"
    },
    "code":200,
    "message":"OK"
}

Delete Single Opt-Out Value

Delete Single Opt-Out Value will delete an existing Number from the Opt-Out database.

Base Resource URI

https://$DOMAIN

Delete Opt-Out Value Resource URI

/campaignmanager/dnd/optout/{numberSid}

Supported Operations

HTTP DELETE: Delete Opt-Out Value

Request Parameters

Parameter Description

numberSid

The unique identifier of a Number.

Response Body

The response body will carry code, corresponding message and Number data if delete was successful.

Parameter Description

data

Number data as explained in the data parameter explained below.

code

Sub-error code for response

message

Message describing the error if such has occurred, or success message if successful.
Data Parameters
Data Parameter Description

enterpriseSid

The Sid of the enterprise the Opt-Out belongs to.

sid

SID to uniquely identify a single Opt-Out value.

name

Name of the Opt-Out database.

number

Value containing the PhoneNumber.

dateCreated

The date on which this particular Opt-Out was created.
Response Parameters

Delete Opt-Out API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code section.

Error Code HTTP Status Error Message Description Category

491

409

OptOut Sid not found

The OptOut SID does not exist in the system

Delete Opt-Out

Example

From the bash terminal you can run the command below:

curl -X DELETE \
  https://company.com/campaignmanager/dnd/optout/OT38cbd6deddda44cebcaaf1e06e78ca3e \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If deleting the Opt-Out Number is successful, below is the response returned:

{
    "data":{
        "sid":"OT38cbd6deddda44cebcaaf1e06e78ce3e",
        "name":"Opt-Out","number":"918278362878",
        "dateCreated":"2021-12-13T12:21:27+0000",
        "enterpriseSid":"EN909628cbd8e9429899c0b474f2e96423"
    },
    "code":200,
    "message":"OK"
}

If deleting of the Opt-Out fails, below is the response returned. Exact error code and message will depend on the error occurred.

{
    "errorCode": "491",
    "message": "OptOut Sid not found",
    "data": "OT38cbd6deddda44cebcaaf1e06e78ce3e"
}

Get list of Opt-Out Numbers

This endpoint is used to get a list of Opt-Out Numbers.

Base Resource URI

https://$DOMAIN

Get Opt-Out List Resource URI

/campaignmanager/dnd/optout/search

Supported Operations

HTTP GET: Get Opt-Out Numbers list

Paging

The following paging parameters are supported.

Query Parameter Description

pageSize

Number of records returned per page.

page

Which page of the Opt-Out records to return, starting from 0.
If the search API is called without page and pageSize parameters set, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

The following filtering parameters are supported:

Query Parameter Description

endTime

Optional parameter. Only show users that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

phoneNumber

Optional parameter. Only show the Opt-Out value containing this phone Number.

startTime

Optional parameter. Only show users that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in what order. Either 'asc' for ascending or 'desc' for descending sort ordering. Here is the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Sort Attributes
Parameter Description

dateCreated

Sort by created date

Response Body

The response body will carry code, corresponding message and data of Opt-Out values if it was successfully fetched. The HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below.

Parameter Description

data

data of search as explained in table below

code

Sub-error code for response

message

Message describing error if error occurred or success message
Data parameters
Data Parameter Description

uri

Unique URI that you can call to get records

result

Opt-Out data as explained in the data parameter of Delete Opt-Out.

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

Unique URI that you can call to get records in First page

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://company.com/campaignmanager/dnd/optout/search?page=0&pageSize=10&sortBy=datecreated:desc
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

Below is the response returned:

{
    "data":{
        "result":[
            {
                "sid":"OT5fd7e2a4efa14c2f90bd986f197d86fc",
                "name":"Opt-Out",
                "number":"6372837839",
                "dateCreated":"2021-12-13T12:21:27+0000",
                "enterpriseSid":"EN909628cbd8e9429899c0b474f2e96423"
            }
        ],
        "pageSize":10,
        "total":1,
        "page":0,
        "numPages":1,
        "start":0,
        "end":0,
        "firstPageUri":"/campaignmanager/dnd/optout/search/?pageSize=10&sortBy=datecreated:desc&page=0",
        "uri":"/campaignmanager/dnd/optout/search/?pageSize=10&sortBy=datecreated:desc&page=0"
        },
        "code":200,
        "message":"OK"
}

Get Single Opt-Out Number

Single Opt-Out search API allows users to retrieve specific number.

Base Resource URI

https://$DOMAIN

Get Single Opt-Out Resource URI

/campaignmanager/dnd/optout/search/{numberSid}

Supported Operations

HTTP GET: Specific Opt-Out Number

Response Parameters

Search Opt-Out API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

Error Code HTTP Status Error Message Description Category

491

409

OptOut Sid not found

Opt-Out sid is not found.

Get Announcement

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://company.com/campaignmanager/dnd/optout/search/OT5fd7e2a4efa14c2f90bd986f197d86fd \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "sid": "OT5fd7e2a4efa14c2f90bd986f197d86fd",
        "name": "Opt-Out",
        "number": "6372837839",
        "dateCreated": "2021-12-13T12:21:27+0000",
        "enterpriseSid": "EN909628cbd8e9429899c0b474f2e96424"
    },
    "code": 200,
    "message": "OK"
}

In case of failure, the following response is returned.

{
    "errorCode": "491",
    "message": "OptOut Sid not found",
    "data": "OT5fd7e2a4efa14c2f90bd986f197d86fd"
}

Opt-In

Create Opt-In List

This API is used to Create the Opt-In List for Campaign Manager.

Base Resource URI

https://$DOMAIN

Add Opt-In Resource URI

/campaignmanager/dnd/optin

Supported Operations

HTTP POST: Add Opt-In List

Request Parameters

Parameter Description

file

Mandatory. Multipart File values can be passed as new lines separated.

name

Optional. Name for the Opt-In Database. If not passed, default is "opt-in".

Response Body

The Response Body will carry the Code, corresponding message and data of the Opt-In if it was successfully created. HTTP response will be 200 Created (OK).

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

data

Opt-In data as explained in the table below.

code

Sub-error code for response

message

Message describing error if error occured or success message
Data Parameters
Data Parameter Description

enterpriseSid

Sid of the enterprise the Opt-In belongs to.

name

Opt-In name.
Response Parameters

Create Opt-In API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code

Error Code HTTP Status Error Message Description Category

490

409

Dnd File numbers is not valid

Passed Invalid Opt-In file

Create Opt-In

Example

Create Opt-Out Database
{
    "file":"<path to file having the phone numbers separated by new line>"
}

From the bash terminal you can run the command below:

curl -X POST \
  https://company.com/campaignmanager/dnd/optin\
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -F name="test-Opt-In"\
  -F file="@/Users/workspace/Solutions/OptIn/MXOrgTest2-Ent2-Numbers.csv" \

If creation of Opt-In is successful, below is the response returned:

{
    "data":{
        "name":"test-Opt-In",
        "enterpriseSid":"EN909628cbd8e9429899c0b474f2e96423"
    },
    "code":200,
    "message":"OK"
}

Delete Opt-In Value

Delete Single Opt-In Value will delete an existing Number from the Opt-In database.

Base Resource URI

https://$DOMAIN

Delete Opt-In Value Resource URI

/campaignmanager/dnd/optin/{numberSid}

Supported Operations

HTTP DELETE: Delete Opt-In Value

Request Parameters

Parameter Description

numberSid

SID to uniquely identify a Number

Response Body

The response body will carry code, corresponding message and Number data if delete was successful.

Parameter Description

data

Number data as explained in the data parameter explained below.

code

Sub-error code for response

message

Message describing error if an error occurred or success message
Data Parameters
Data Parameter Description

enterpriseSid

Sid of the enterprise the Opt-In belongs to.

sid

SID to uniquely identify a single Opt-In value

name

Name of the Opt-In database

number

Value containing the PhoneNumber

dateCreated

Date on which this particular Opt-In was created
Response Parameters

Delete Opt-In API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code

Error Code HTTP Status Error Message Description Category

491

409

OptIn Sid not found

OptIn SID doesn’t exist in the system

Delete Opt-In

Example

From the bash terminal you can run the command below:

curl -X DELETE \
  https://company.com/campaignmanager/dnd/optin/OT38cbd6deddda44cebcaaf1e06e78ca3e \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If deleting the Opt-In Number is successful, below is the response returned:

{
    "data":{
        "sid":"OT38cbd6deddda44cebcaaf1e06e78ce3e",
        "name":"test-Opt-In","number":"918278362878",
        "dateCreated":"2021-12-13T12:21:27+0000",
        "enterpriseSid":"EN909628cbd8e9429899c0b474f2e96423"
    },
    "code":200,
    "message":"OK"
}

If deleting of the Opt-In value fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "491",
    "message": "OptIn Sid not found",
    "data": "OT38cbd6deddda44cebcaaf1e06e78ce3e"
}

Get list of Opt-In Numbers

This endpoint is used to get a list of Opt-In Numbers.

Base Resource URI

https://$DOMAIN

Get Opt-In List Resource URI

/campaignmanager/dnd/optin/search

Supported Operations

HTTP GET: Get Opt-In Number’s list

Paging

The following paging parameters are supported

Query Parameter Description

pageSize

Number of records returned per page

page

Which page of Opt-In records to return, starting from 0.
If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

Following filtering parameters are supported:

Query Parameter Description

endTime

Optional parameter. Only show numbers that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

phoneNumber

Optional parameter. Only show the Opt-In value containing this phone Number.

name

Optional Parameter. Only show numbers which were created under this opt-in name.

startTime

Optional parameter. Only show numbers that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Sort Attributes
Parameter Description

dateCreated

Sort by created date

Response Body

The response body will carry code, corresponding message and data of Opt-In values if it was successfully fetched. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

data

data of search as explained in table below

code

Sub-error code for response

message

Message describing error if error occured or success message
Data parameters
Data Parameter Description

uri

Unique URI that you can call to get records

result

Set of Opt-In data as explained in the data parameter of Delete Opt-In.

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

Unique URI that you can call to get records in First page

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://company.com/campaignmanager/dnd/optin/search?page=0&pageSize=10&sortBy=datecreated:desc
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

Below is the response returned:

{
    "data":{
        "result":[
            {
                "sid":"OT5fd7e2a4efa14c2f90bd986f197d86fc",
                "name":"test-Opt-in-1",
                "number":"6372837839",
                "dateCreated":"2021-12-13T12:21:27+0000",
                "enterpriseSid":"EN909628cbd8e9429899c0b474f2e96423"
            },
            {
                "sid":"OT4414858b74454884af8a607a67cb807a",
                "name":"test-opt-in-2",
                "number":"6372837839",
                "dateCreated":"2021-12-20T03:44:33+0000",
                "enterpriseSid":"EN909628cbd8e9429899c0b474f2e96423"
            }
        ],
        "pageSize":10,
        "total":2,
        "page":0,
        "numPages":1,
        "start":0,
        "end":0,
        "firstPageUri":"/campaignmanager/dnd/optin/search/?pageSize=10&sortBy=datecreated:desc&page=0",
        "uri":"/campaignmanager/dnd/optin/search/?pageSize=10&sortBy=datecreated:desc&page=0"
        },
        "code":200,
        "message":"OK"
}

Get Single Opt-In Number

Single Opt-In search API allows users to retrieve a specific number.

Base Resource URI

https://$DOMAIN

Get Single Opt-In Resource URI

/campaignmanager/dnd/optin/search/{numberSid}

Supported Operations

HTTP GET: Specific Opt-in Number

Response Parameters

Search Opt-in API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

Error Code HTTP Status Error Message Description Category

491

409

OptIn Sid not found

Opt-In sid is not found.

Get Opt-In

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://company.com/campaignmanager/dnd/optin/search/OT5fd7e2a4efa14c2f90bd986f197d86fd \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "sid": "OT54523f57449d4be285cd93e84e3a66e4",
        "name": "test-opt-in",
        "number": "6372837839",
        "dateCreated": "2021-12-20T03:34:23+0000",
        "enterpriseSid": "EN909628cbd8e9429899c0b474f2e96422"
    },
    "code": 200,
    "message": "OK"
}

In case of failure, the following response is returned.

{
    "errorCode": "491",
    "message": "OptIn Sid not found",
    "data": "OT54523f57449d4be285cd93e84e3a66e9"
}