Auto Attendant API
Overview
Auto Attendant API allows Enterprise Accounts to Edit Autoattendant, manage users, assign phone numbers and assign extensions.
CPaaS Auto Attendant API’s can be broadly classified into below categories :
| When the API returns a timestamp or expects date/timestamp as request parameter, format is given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS±[hh][mm]. For example 2019-10-10T13:13:48+0000. Note that the given date/time is inclusive and is assumed to be in UTC timezone. Hence the offset ±[hh][mm] will always be +0000. |
User
Create User
This endpoint is used to create user depending on role as explained below.
-
SUPPORT can add another user with role SUPPORT(This role is not yet defined to be done in future)
-
CSP_ADMIN can create users with role ENTERPRISE_ADMIN (a.k.a BG Admin) and AA_ADMIN
-
ENTERPRISE_ADMIN can create users with role ENTERPRISE_ADMIN and AA_ADMIN within same Enterprise
Request Parameters
| Parameter | Description |
|---|---|
name |
Optional. Full name of the user being added |
emailId |
Required. Email Id of the user |
password |
Password associated with this user. |
role |
Required. Possible values are: SUPPORT (This is specifically for Support Not yet implemented), CSP_ADMIN, ENTERPRISE_ADMIN, AA_ADMIN, USER_ADMIN(Not yet Implemented) |
status |
Optional. Will be set to active if not passed. Possible values are: ACTIVE, SUSPENDED, DELETED |
enterpriseSid |
Sid of the enterprise the user belongs to. |
Response Body
Response Body will carry Code, corresponding message and data of User if it was successfully created. HTTP response will be 200 Created (OK).
The response returned is JSON body as shown in the example below. Each parameters are as explained below.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
User data as explained in the table below. |
Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique User Id |
accountEmail |
Unique CPaaS Account that created this particular user |
dateCreated |
Timestamp when this User was created |
dateUpdated |
Timestamp when this User was updated |
name |
Name of this user |
emailId |
Email Id of the user created |
role |
Role of the user |
status |
Status of the user(ACTIVE/INACTIVE) |
uri |
Unique URI that you can call to get only this specific user |
Response Parameters
The create user API can also return error code and corresponding HTTP error as mentioned in the Common Response Error Codes section. Below are the errors that can be returned.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
499 |
409 |
Error in creating an account on CPaaS |
Error while creating an account in CPaaS(password fail) |
Create User, Update User |
467 |
409 |
Enterprise not found |
Enterprise for which user is to be added is not found. |
Create User, Update User |
484 |
409 |
supportUser not unique |
A user already exists in the DB with provided emailId |
Create User, Update User |
505 |
409 |
CPaaS account belongs to a different Admin account |
user id is already am account to a different account |
Create User, Update User |
Example
{
"status":"ACTIVE",
"name":"Test BG 2",
"enterpriseSid":"EN838bcdf35f9d421fad3ab516195b873b",
"emailId":"testbgadmin2@yourcompany.com",
"password":"W31Comet0@@!",
"role":"BG_ADMIN"
}
From the bash terminal you can run the command below:
curl -X POST \
https://your_custom_domain.com/autoattendant/user \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"status":"ACTIVE",
"name":"Test BG 2",
"enterpriseSid":"EN838bcdf35f9d421fad3ab516195b873b",
"emailId":"testbgadmin2@yourcompany.com",
"password":"W31Comet0@@!",
"role":"BG_ADMIN"
}’
If creation of User is successful, below is the response returned
{
"data": {
"sid": "RCS31e4303c3d06409a9e7a847fc7221bd0",
"dateUpdated": "2020-01-27T05:50:02+0000",
"dateCreated": "2020-01-27T05:50:02+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/user/search/RCS31e4303c3d06409a9e7a847fc7221bd0",
"emailId": "testbgadmin2@yourcompany.com",
"status": "ACTIVE",
"role": "BG_ADMIN",
"name": "Test BG 2"
},
"code": 200,
"message": "OK"
}
If creation fails, below response is returned with corresponding HTTP Error Code
{
"errorCode": "484",
"message": "supportUser not unique",
"data": {
"emailId": "testbgadmin2@yourcompany.com",
"password": "W31Comet0@@!",
"status": "ACTIVE",
"role": "BG_ADMIN",
"name": "Test BG 2",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b"
}
}
Get list of Users
This endpoint is used to get a list of users.
Paging
The following paging parameters are supported.
| Query Parameter | Description |
|---|---|
page |
Which page of users records to return, starting from zero. |
pageSize |
Number of records returned per page. |
If the search API is called without those two query parameters, by default pageSize will be set to 10, and the page will be set to 0 to avoid retrieving all data in a single API call.
|
Filtering
The following filtering parameters are supported.
| Query Parameter | Description |
|---|---|
name |
Optional parameter. Only show users that match name text partially or fully. |
emailId |
Optional parameter. Only show users that match email text partially or fully. |
role |
Optional parameter. Only show users that have this particular role. |
enterpriseSid |
Optional parameter. Only show users for this particular enterprise. |
status |
Optional parameter. Only show users that have this particular status. |
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. If you want to omit the time you shall use YYYY-MM-DD format. For example 2018-10-05. If only the 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 the UTC timezone. |
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. If you want to omit the time you shall use YYYY-MM-DD format. For example 2018-10-06. If only the 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 the 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. The order can either be asc for ascending and desc for descending sort ordering. Here is an example of 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 use to sort by.
Sort Attributes
| Parameter | Description |
|---|---|
name |
Sort by name |
Sort by email |
|
dateCreated |
Sort by created date |
Response Body
The response body will carry a response code, corresponding message and data of the user, if successfully fetched. The HTTP response will be 200 OK.
The response returned is in a JSON format as shown in the example below. The possible parameters are listed below.
| Code | Description |
|---|---|
code |
Sub-error response code. |
message |
Message describing the error if same occurred, or a success message if successful. |
data |
Data response as explained in table below. |
Data parameters
| Data Parameter | Description |
|---|---|
result |
A liist of |
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. |
uri |
Unique URI that you can call to get records. |
firstPageUri |
Unique URI that you can call to get records in the first page. |
nextPageUri |
Unique URI that you can call to get records in the next page. |
Example
From the bash terminal you can run the following command:
curl -X GET \
https://your_custom_domain.com/autoattendant/user/search?enterpriseSid=EN54e3389b5bf34896876b86e139cca614 \
--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": "RCS6de60a360c75453893b5b6d1503b7276",
"dateUpdated": "2020-01-27T11:14:14+0000",
"dateCreated": "2020-01-27T11:14:14+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/user/search/RCS6de60a360c75453893b5b6d1503b7276",
"emailId": "Testenterprise@yourcompany.com",
"status": "ACTIVE",
"role": "BG_ADMIN",
"name": "testbg"
}
],
"pageSize": 10,
"total": 1,
"page": 0,
"numPages": 1,
"start": 0,
"end": 0,
"firstPageUri": "/autoattendant/user/search/?enterpriseSid=EN54e3389b5bf34896876b86e139cca614&pageSize=10&page=0",
"uri": "/autoattendant/user/search/?enterpriseSid=EN54e3389b5bf34896876b86e139cca614&pageSize=10&page=0"
},
"code": 200,
"message": "OK"
}
Get Single User
The single enterprise search API makes it possible to search for a specific user.
Response Parameters
The search enterprise 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 |
|---|---|---|---|---|
487 |
409 |
Auto Attendant user Id not found |
User is not found. |
Delete User, Update User, Get User |
Example
From the bash terminal you can run the following command:
curl -X GET \
https://your_custom_domain.com/autoattendant/user/search/AAEb6eb071d21124dbab20b095c25f1274f \
--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":"AAEb6eb071d21124dbab20b095c25f1274f",
“accountEmail”:”jane.doe@yourcompany.com”,
"dateCreated":"2019-07-22 09:53:51",
"dateUpdated":"2019-07-22 09:53:51",
"name" : "test",
“emailId”:”john.doe@yourcompany.com”,
“role”: “AA-Admin”,
“enterpriseSid”: “ EN801e792d86504368a9385314e8c5c4d6”,
"uri":/autoattendant/user/search/ AAEb6eb071d21124dbab20b095c25f1274f "
} }
Update User
This endpoint is used to update existing users.
-
SUPPORT user can make changes to all users irrespective of their role.
-
CSP_ADMIN user can make changes to all users with ENTERPRISE_ADMIN and AA_ADMIN role within their organisation.
-
ENTERPRISE_ADMIN user can make changes to other users with ENTERPRISE_ADMIN and AA_ADMIN role within the same enterprise.
Request Parameters
| Parameter | Description |
|---|---|
UserSid |
Unique id of the user. |
status |
Status of the user. Could be one of the following: - ACTIVE |
enterpriseSid |
Optional enterprise id. Move a user from one enterprise to another by passing the enterpriseId of the destination enterprise. |
Response Body
The response body will carry code, corresponding message and data of the user, it updated successfully. The HTTP response will be 200 OK.
The response returned is in a JSON format as shown in the example below. All possible parameters are listed below.
| Parameter | Description |
|---|---|
code |
Sub-error response code. |
message |
Message describing the error if same occurred, or a success message if successful. |
data |
User data as explained in the Data Parameters section. |
Response Parameters
The create user API can also return error code and corresponding HTTP error as mentioned in the Common Response Error Codes section. The possible error codes are listed below.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
499 |
409 |
Error creating an account under the CPaaS organization. |
A user with the same emailId already exists in the database. |
Create User, Update User |
467 |
409 |
Enterprise not found. |
The enterprise for which user is to be added is not found. |
Create User, Update User |
484 |
409 |
supportUser not unique. |
A user with the same emailId already exists in the database. |
Create User, Update User |
505 |
409 |
CPaaS account belongs to a different Admin account. |
The user id is already an account of a different primary account. |
Create User, Update User |
487 |
409 |
Auto Attendant user Id not found. |
User Id not found. |
Update User |
Example
{
"status":"SUSPENDED"
}
From the bash terminal you can run the command below:
curl -X PUT \
https://your_custom_domain.com/autoattendant/user/RCSb4ba60022d87407db2134146e3bd4ceb \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"status":"SUSPENDED"
}’
If the user update is successful, the below response shall be returned:
{
"data": {
"sid": "RCSb4ba60022d87407db2134146e3bd4ceb",
"dateUpdated": "2020-01-29T05:21:28+0000",
"dateCreated": "2020-01-21T13:35:19+0000",
"accountEmail": "jane.doe@nyourcomapny.com",
"uri": "/autoattendant/user/search/RCSb4ba60022d87407db2134146e3bd4ceb",
"emailId": "john.doe@nyourcomapny.com",
"status": "SUSPENDED",
"role": "BG_ADMIN",
"name": "Doe's Enterprise Admin"
},
"code": 200,
"message": "OK"
}
If updating fails, below response is returned with corresponding HTTP Error Code
{
"errorCode": "487",
"message": "Auto Attendant user Id not found",
"data": {
"sid": "RCSb4ba60022d87407db2134146e3bd4c"
}
}
Announcement
Create Announcement
Creating an announcement will upload an audio file to the Auto Attendant System and will populate the uri in the database.
Request Parameters
| Parameter | Description |
|---|---|
name |
Name of the announcement. |
description |
Optional. Description of the announcement. |
enterpriseSid |
Sid of the enterprise the announcement belongs to. |
type |
Type of the announcement. Possible options are: - say: Make an announcement from text-to-speech. In that case the below parameters are mandatory. |
body |
Text-to-speech body. Please visit Say-RCML for more information. |
language |
Text-to-speech language as explained in the <Say> verb documentation. |
voice |
Voice of speech. The voice options depend on the TTS provider as follows: - Google: Man and Woman |
Response Body
The response body will carry the code, corresponding message and data of the announcement File, if successfully created. The HTTP response will be 200 Created (OK).
The response returned is in JSON format as shown in the example below. The possible parameters are as follows.
| Parameter | Description |
|---|---|
code |
Sub-error response code |
message |
Message describing error if same occurred, or a success message if successful. |
data |
Announcement file data as explained in the table below. |
Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique announcement Id. |
name |
Name of the announcement. |
description |
Description of the announcement. |
accountEmail |
Unique CPaaS account that created the announcement. |
dateCreated |
Timestamp when the announcement was created. |
dateUpdated |
Timestamp when the 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. |
fileUri |
The File URI for this recording, relative to https://$DOMAIN. It can be used to access the WAV file. |
type |
Type of the announcement. Possible options are: - say: Make an announcement from text-to-speech. In that case below parameters are mandatory. |
body |
Text-to-speech body. |
language |
Text-to-speech language as explained in the <Say> verb documentation. |
voice |
Voice of the speech. Options depend upon the TTS provider and are as follows: - Google: Man and Woman |
Response Parameters
The create announcement API will return error code and corresponding HTTP error as mentioned in Common Response Error Codes section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
467 |
409 |
Enterprise Not Found |
Enterprise for which the announcement is to be added is not found. |
Create Announcement |
490 |
409 |
Auto Attendant System Not Found |
Auto Attendant system for which the announcement is to be added is not found. |
Create Announcement |
520 |
409 |
Announcement Type Not Found |
Announcement type not found |
Create Announcement |
519 |
409 |
Say Required Parameters Missing |
Error in creating announcement. Required parameter(s) for type SAY missing |
Create Announcement |
521 |
409 |
Announcement Language Not Found |
Announcement language is not supported |
Create Announcement |
522 |
409 |
Announcement Voice Not Found |
Announcement Voice types can be Man/Woman. Leave Blank to use default. |
Create Announcement |
Example
{
"name" : "Welcome announcement",
"description" : “Announcement made during working hours”,
“file” : “……..” ,
“enterpriseSid”: “ EN838bcdf35f9d421fad3ab516195b873b”
}
From the bash terminal you can run the command below:
curl -X POST \
https://your_custom_domain.com/autoattendant/announcement\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"name" : "Welcome announcement",
"description" : "Announcement made during working hours",
"enterpriseSid" : "EN838bcdf35f9d421fad3ab516195b873b"
}’
If the 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@yourcompany.com",
"uri": "/autoattendant/announcement/search/AN42b3d3e952ff47ecba9d487095a2bc4e",
"name": "Welcome announcement",
"description": "Announcement made during working hours",
"type": "play",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b"
},
"code": 200,
"message": "OK"
}
If the creation of the announcement fails, below is the response returned. Exact error code and message depend on the error occurred.
{
"errorCode": "467",
"message": "Enterprise not found",
"data": {
"sid": "EN838bcdf35f9d421fad3ab516195b873"
}
}
Upload Announcement file
This API will upload an audio file to S3 for the announcement.
Request Parameters
| Parameter | Description |
|---|---|
announcementSid |
Sid to uniquely identify an announcement. |
file |
Audio file in wav format to be uploaded in the recommended bitrate. Please visit Media Server Audio File Format to find out more about the supported audio file formats. |
Response Body
The response body will carry the code, corresponding message and data of the announcement, if the file was successfully uploaded and linked to the announcement. HTTP response 200 (OK) will be returned.
The response is returned in JSON format as shown in the example below.
Available Parameters
| Parameter | Description |
|---|---|
code |
Sub-error code of the response |
message |
Message describing the error (if an error occurred), or success message (if successful). |
data |
Announcement file data as explained in the table below. |
Data Parameter
| Data Parameter | Description |
|---|---|
fileUri |
The file URI for this recording, relative to https://$DOMAIN . It can be used to access the WAV file. |
| The rest of the response parameters are the same as explained in Response Data Parameters documentation. |
Response Parameters
Create announcement API will return an error code and corresponding HTTP error as mentioned in the Common Response Error Code section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
500 |
409 |
Announcement not found |
Announcement Id doesn’t exists |
Upload File |
504 |
409 |
Error in uploading audio file |
Either format is not a wav file or an error occurred while uploading the file |
Upload File |
Example
From the bash terminal you can run the following command:
curl -X POST \
https://your_custom_domain.com/autoattendant/file/announcement/AN5450dbc715fb4b9fac550cfdc9d2e51d\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: multipart/form-data' \
-d '{
"file" : "file:/user/home/teru_-_110_Downtempo_Electronic_4.wav
"
}’
If the upload of the file is successful, the response below will be returned:
{
"data": {
"sid": "AN5450dbc715fb4b9fac550cfdc9d2e51d",
"dateUpdated": "2020-08-12T07:26:46+0000",
"dateCreated": "2020-08-12T07:26:46+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/announcement/search/AN5450dbc715fb4b9fac550cfdc9d2e51d",
"name": "test api upload",
"fileUri": "/autoattendant/internal/announcement/file/AN5450dbc715fb4b9fac550cfdc9d2e51d_1597217206000.wav",
"enterpriseSid": "ENe528dc1c9e984830b119e75aaa7574f7",
"type": "play"
},
"code": 200,
"message": "OK"
}
If the upload of the audio file fails, the following response will be returned. The exact error code and message depend on the error occurred.
{
"errorCode": "500",
"message": "Announcement not found",
"data": {
"sid": "ANd28fddd7f6184a67aacb2dd6c3c00e28"
}
}
Get list of Announcement
This endpoint can be used to delete an existing user.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Announcements records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If search API is called without page and pageSize parameters, 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 |
|---|---|
name |
Optional parameter. Only show announcements that match name text partially or fully. |
enterpriseSid |
Optional parameter. Only show announcements for specific enterprise. |
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. If you want to omit the time you shall use YYYY-MM-DD format. For example 2018-10-05. If only the 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 the UTC timezone. |
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. If you want to omit the time you shall use YYYY-MM-DD format. For example 2018-10-06. If only the 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 the 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:
Response Body
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
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
data of search as explained in table below |
Data parameters
Data Parameter |
Description |
result |
List of announcement data as explained in the Data Parameters section. |
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 |
uri |
Unique URI that you can call to get records |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/announcement/search?enterpriseSid=EN838bcdf35f9d421fad3ab516195b873b&name=Welcome announcement\
--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": "AN42b3d3e952ff47ecba9d487095a2bc4e",
"dateUpdated": "2020-01-27T06:44:13+0000",
"dateCreated": "2020-01-27T06:44:13+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/announcement/search/AN42b3d3e952ff47ecba9d487095a2bc4e",
"name": "Welcome announcement",
"description": "Announcement made during working hours",
"fileUri": "/autoattendant/announcement/file/AN42b3d3e952ff47ecba9d487095a2bc4e_1580107453000.wav",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b"
}
],
"pageSize": 10,
"total": 1,
"page": 0,
"numPages": 1,
"start": 0,
"end": 0,
"firstPageUri": "/autoattendant/announcement/search/?enterpriseSid=EN838bcdf35f9d421fad3ab516195b873b&name=Welcome%20announcement&pageSize=10&page=0",
"uri": "/autoattendant/announcement/search/?enterpriseSid=EN838bcdf35f9d421fad3ab516195b873b&name=Welcome%20announcement&pageSize=10&page=0"
},
"code": 200,
"message": "OK"
}
Get Single Announcement
The single announcement search API allows users to retrieve specific announcement.
Response Parameters
The search enterprise API will return error code and corresponding HTTP error as mentioned in Common Response Error Codes section.
| 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://your_custom_domain.com/autoattendant/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@yourcompany.com",
"uri": "/autoattendant/announcement/search/AN42b3d3e952ff47ecba9d487095a2bc4e",
"name": "Welcome announcement",
"description": "Announcement made during working hours",
"fileUri": "/autoattendant/announcement/file/AN42b3d3e952ff47ecba9d487095a2bc4e_1580107453000.wav",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b"
},
"code": 200,
"message": "OK"
}
If it failes, the following response is returned.
{
"errorCode": "500",
"message": "Announcement not found",
"data": {
"sid": "AN42b3d3e952ff47ecba9d487095a2bc4"
}
}
Update Announcement
Update announcement will update an existing announcement.
Request Parameters
| Parameter | Description |
|---|---|
announcementSid |
Unique Id of the announcement |
| The rest of the request parameters are the same as Request Parameters of create announcement. |
| If you are updating the announcement file, Upload Announcement file should be called. |
Response Body
Response Body will carry Code, corresponding message and Announcement data if update was successful.
| Parameter | Description |
|---|---|
code |
Sub-error response code |
message |
Message describing the error if an error occurred, or success message if successful. |
data |
Announcement data as explained in the Data Parameters section of Create Announcement section. |
Response Parameters
Update announcement 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 |
|---|---|---|---|---|
467 |
409 |
Enterprise not found |
Enterprise for which the announcement is to be added is not found. |
Create Announcement |
490 |
409 |
Auto Attendant system not found |
AA System for which the announcement is to be added is not found. |
Create Announcement |
500 |
409 |
Announcement not found |
Announcement Sid doesn’t exists |
Create Announcement |
519 |
409 |
Say Required Parameters missing |
Error in creating announcement. Required Parameter(s) for type SAY missing |
Update Announcement |
521 |
409 |
Announcement Language Not Found |
Announcement Language is not supported |
Update Announcement |
522 |
409 |
Announcement Voice Not Found |
Announcement Voice types can be Man/Woman. Leave Blank to use default. |
Update Announcement |
Example
{
"name" : "Welcome announcement",
"description" : “Announcement made during working hours”,
“enterpriseSid”: “ EN838bcdf35f9d421fad3ab516195b873b”
}
From the bash terminal you can run the command below:
curl -X PUT \
https://your_custom_domain.com/autoattendant/announcement/AN0bd592a2192e45f3932af05ecddbb864\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"name" : "Working Hours",
"description" : "Working Hours Announcement",
"enterpriseSid": "EN70b163ea4290498287c06b8e286abbc2"
}’
If updating the announcement is successful, below is the response returned:
{
"data":{
"sid":"AN0bd592a2192e45f3932af05ecddbb864",
"dateUpdated":"2020-09-04T05:45:27+0000",
"dateCreated":"2020-08-28T12:38:02+0000",
"accountEmail":"jane.does@yourcompany.com",
"uri":"/autoattendant/announcement/search/AN0bd592a2192e45f3932af05ecddbb864",
"name":"Working Hours",
"description":"Working Hours Announcement",
"fileUri":"/autoattendant/internal/announcement/file/AN0bd592a2192e45f3932af05ecddbb864_1599198327000.wav",
"enterpriseSid":"EN70b163ea4290498287c06b8e286abbc2",
"type":"say",
"body":"Welcome to Bob's Car Services. To reach to desired extension, please press 1. Press 2 to know the direction to store. ",
"language":"google.en-GB-Wavenet-A",
"voice":"woman"
},
"code":200,
"message":"OK"
}
If the update of the announcement fails, below is the response returned. Exact error code and message will depend on the error that occurred.
{
"errorCode": "500",
"message": "Announcement not found",
"data": {
"sid": "ANf1ef82a9fecd4ee2b367e96c98aaf82"
}
}
Delete Announcement
Delete announcement will delete an existing announcement.
Response Body
The response body will carry code, corresponding message and announcement data, if deletion was successful.
| Parameter | Description |
|---|---|
code |
Sub-error response code |
message |
Message describing error if error occurred. |
data |
Announcement data as explained in the Data Parameters section. |
Response Parameters
The delete announcement 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 |
|---|---|---|---|---|
500 |
409 |
Announcement not found |
Announcement SID doesn’t exist in the system |
Update Announcement, Delete Announcement, Get Announcement |
507 |
409 |
This Announcement cannot be deleted as it is being used in a menu. |
announcement is used in a menu |
Delete Announcement |
523 |
409 |
Announcement cannot be deleted as it is assigned to an action in a menu. |
Announcement is assigned to an action in a menu |
Delete Announcement |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
https://your_custom_domain.com/autoattendant/announcement/ANd72b8662c3ce4bab849edae2906d6bf0 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
If the deletion of the announcement is successful, below is the response returned:
{
"data": {
"sid": "ANd72b8662c3ce4bab849edae2906d6bf0",
"dateUpdated": "2020-01-27T14:25:09+0000",
"dateCreated": "2020-01-27T14:25:09+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/announcement/search/ANd72b8662c3ce4bab849edae2906d6bf0",
"name": "test",
"description": "testannouncement",
"fileUri": "/autoattendant/announcement/file/ANd72b8662c3ce4bab849edae2906d6bf0_1580135109000.wav",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b"
},
"code": 200,
"message": "OK"
}
If the deletion 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 menu.",
"data": {
"sid": "AN42b3d3e952ff47ecba9d487095a2bc4e"
}
}
Schedule
Create Schedule
This API creates a schedule for an Auto Attendant system.
Request Parameters
| Parameter | Description |
|---|---|
autoAttendantSid |
Sid to uniquely identify an Auto Attendant system. |
schedule |
Schedule of the Auto Attendant system as explained below in schedule parameters section. |
scheduleType |
Type of the schedule. Possible values are: - WEEKLY (weekly schedule), |
Schedule parameters:
| Data Parameter | Description |
|---|---|
entries |
List schedule time frames as explained below in the Entries parameters section (in case of weekly schedule) |
menuSid |
Menu sid to which entries/special days belong to. |
scheduleType |
Type of the schedule entries. Possible Values are: WEEKLY (weekly schedule), DATE_RANGE (special days schedule) |
startDate |
Start date of the special days schedule |
endDate |
end date of the special days schedule |
Response Body
Thw response body will carry code, corresponding message and unique id if creation of schedule was successful.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing the error if an error occurred, or success message if successful. |
data |
Schedule data as explained in the Request Parameters section below. |
Response Parameters
Create Schedule API will return error code and corresponding HTTP error as mentioned in the Common Response Error Codes section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
490 |
409 |
Auto Attendant System not found |
Auto Attendant Sid passed does not exist |
Create schedule, Update schedule |
502 |
409 |
Menu not found |
Menu Sid passed does not exist |
Create schedule, Update schedule |
Weekly Schedule Example
{
"autoAttendantSid":"AAa95f0d7ea0ce4863b2935523074bf466",
"scheduleType":"WEEKLY",
"schedule":[
{"menuSid":"MN8922ed9aba854ce3afe17b0f1725e2b5",
"scheduleType":"WEEKLY",
"entries":[
{"day":1,
"startTime":"01:00",
"endTime":"04:00"
}
]
}
]
}
From the bash terminal you can run the command below:
curl -X POST \
https://your_custom_domain.com/autoattendant/schedule\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"autoAttendantSid":"AAa95f0d7ea0ce4863b2935523074bf466",
"scheduleType":"WEEKLY",
"schedule":[
{"menuSid":"MN8922ed9aba854ce3afe17b0f1725e2b5",
"scheduleType":"WEEKLY",
"entries":[
{"day":1,
"startTime":"01:00",
"endTime":"04:00"
}
]
}
]
}’
If creation of the schedule is successful, below is the response returned:
{
"data": {
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
"scheduleType": "WEEKLY",
"schedule": [
{
"menuSid": "MN8922ed9aba854ce3afe17b0f1725e2b5",
"scheduleType": "WEEKLY",
"entries": [
{
"day": 1,
"startTime": "01:00",
"endTime": "04:00"
}
]
}
]
},
"code": 200,
"message": "OK"
}
If the creation of schedule fails, below is the response returned. Exact error code and message will depend on the error occurred.
{
"errorCode": "490",
"message": "AutoAttendant System not found",
"data": {
"sid": "AAa95f0d7ea0ce483b2935523074bf466"
}
}
Special Days Schedule Example
{
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
"schedule": [
{
"startDate": "2020-01-22",
"endDate": "2020-01-22",
"menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"scheduleType": "DATE_RANGE"
},
{
"startDate": "2020-01-30",
"endDate": "2020-01-30",
"menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"scheduleType": "DATE_RANGE"
},
{
"startDate": "2020-01-23",
"endDate": "2020-01-23",
"menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"scheduleType": "DATE_RANGE"
}
],
"scheduleType": "DATE_RANGE"
}
From the bash terminal you can run the command below:
curl -X POST \
https://your_custom_domain.com/autoattendant/schedule\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
"schedule": [
{
"startDate": "2020-01-22",
"endDate": "2020-01-22",
"menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"scheduleType": "DATE_RANGE"
},
{
"startDate": "2020-01-30",
"endDate": "2020-01-30",
"menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"scheduleType": "DATE_RANGE"
},
{
"startDate": "2020-01-23",
"endDate": "2020-01-23",
"menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"scheduleType": "DATE_RANGE"
}
],
"scheduleType": "DATE_RANGE"
}\’
If creation of special days schedule is successful, below is the response returned:
{
"data": {
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
"scheduleType": "DATE_RANGE",
"schedule": [
{
"menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"scheduleType": "DATE_RANGE",
"entries": [],
"startDate": "2020-01-22",
"endDate": "2020-01-22"
},
{
"menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"scheduleType": "DATE_RANGE",
"entries": [],
"startDate": "2020-01-30",
"endDate": "2020-01-30"
},
{
"menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"scheduleType": "DATE_RANGE",
"entries": [],
"startDate": "2020-01-23",
"endDate": "2020-01-23"
}
]
},
"code": 200,
"message": "OK"
}
If the creation of schedule fails, below is the response returned. Exact error code and message will depend on the error occurred.
{
"errorCode": "490",
"message": "AutoAttendant System not found",
"data": {
"sid": "AAa95f0d7ea0ce483b2935523074bf466"
}
}
Get Schedule
Get schedule for an AA-System
Filtering
The following filtering parameters are supported.
| Query Parameter | Description |
|---|---|
autoAttendantSid |
Required parameter. |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/schedule/search?autoAttendandSid= AAEb6eb071d21124dbab20b031dak13f1274f \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"autoAttendantSid": "AA1dff3a6c89a34e12b4c31eb177e82e3f",
"schedule": [
{
"menuSid": "MNb4d808cd188a44aaae33c7aec05aac63",
"scheduleType": "WEEKLY",
"entries": [
{
"day": 1,
"startTime": "00:00",
"endTime": "04:00"
},
{
"day": 3,
"startTime": "00:00",
"endTime": "04:00"
}
]
}
]
},
"code": 200,
"message": "OK"
}
Menu
Create Menu
This endpoint is used to create a menu.
Request Parameters
| Parameter | Description |
|---|---|
name |
Name of the menu |
keys |
List of action type and action data for each of the keys, explained in below key data parameters section. |
enterpriseSid |
Sid of the enterprise the menu belongs to. |
autoAttendantSid |
Auto Attendant sid the menu belongs to. |
colorCode |
Color code of the menu. |
announcementSid |
Optional announcement sid for the menu. |
timeoutSeconds |
Timeout duration of the menu. |
timeoutAction |
Action type and action data to perform after timeout. Possible actionType are: Transfer to phone, Dial by extension, Dial by name, Go to menu, Return to previous menu, Replay menu, Announcement return, Announcement hangup, Hangup. |
Key data parameters
| key Parameter | Description | ||
|---|---|---|---|
menuKey |
menu key ex: 0-9 and * |
||
menuAction |
Contains action type and action data for each key. Possible actionType are: Transfer to Phone. Dial by extension. Dial by name. Go To Menu. Return to previous menu. Replay Menu. Announcement Return. Announcement Hangup. Hangup. |
||
actionData |
Action Types can have action data. Possible action data for action types are:
|
Response Body
The response body will carry code, corresponding message and unique id if creation of menu is successful.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Menu data explained in the table below. |
Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique Menu Id |
accountEmail |
Unique CPaaS Account that created this particular record. |
dateCreated |
Timestamp when this Menu was created. |
dateUpdated |
Timestamp when this Menu was updated. |
name |
Name of this Menu. |
autoAttendantSid |
Auto Attendant sid of this menu. |
announcementSid |
Announcement sid assigned to this menu. |
keys |
Keys data explained in key data parameters section. |
enterpriseSid |
Sid of the enterprise the menu belongs to. |
colorCode |
Color code of the menu. |
timeoutSeconds |
Timeout duration of the menu. |
timeoutAction |
Time out action type and action data of the menu. |
uri |
Unique URI that you can call to get only this specific menu. |
Response Parameters
Create Menu API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
467 |
409 |
Enterprise not found |
Enterprise for which menu is to be added is not found. |
Create Menu, Update Menu |
500 |
409 |
Announcement not found |
Announcement sid is not found |
Create menu, Update Menu |
490 |
40 |
AutoAttendant System not found |
Auto Attendant system Id is not foun |
Create menu, Update Menu |
Example
{
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
"announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"timeoutSeconds": "1",
"timeoutAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
},
"name": "weekendmenu",
"keys": [
{
"menuKey": "1",
"menuAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN5067f6f1c8f546dd909df1f50ee9f935"
}
}
]
}
From the bash terminal you can run the command below:
curl -X POST \
https://your_custom_domain.com/autoattendant/menu\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
"announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"timeoutSeconds": "1",
"timeoutAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
},
"name": "weekendmenu",
"keys": [
{
"menuKey": "1",
"menuAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN5067f6f1c8f546dd909df1f50ee9f935"
}
}
]
}’
If the creation of menu is successful, below is the response returned:
{
"data": {
"sid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"dateUpdated": "2020-01-27T09:16:13+0000",
"dateCreated": "2020-01-27T09:16:13+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/menu/search/MN064163a7f3c74f4594d5a8dc55bc4c33",
"name": "weekendmenu",
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"keys": [
{
"menuKey": "1",
"menuAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN5067f6f1c8f546dd909df1f50ee9f935"
}
}
],
"timeoutSeconds": 1,
"timeoutAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
},
"announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e"
},
"code": 200,
"message": "OK"
}
If the creation of menu fails, below is the response returned. Exact error code and message will depend on error occurred.
{
"errorCode": "490",
"message": "AutoAttendant System not found",
"data": {
"sid": "AAa95f0d7ea0ce4863b235523074bf466"
}
}
Get list of Menus
This endpoint is used to get list of Menus
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Menu records to return, starting from 0. |
pageSize |
Number of records returned per page |
If search API is called without page and pageSize parameters, by default pageSize will be set to 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 |
|---|---|
name |
Optional parameter. Only show Menus that match name text, partially or fully. |
enterpriseSid |
Optional Parameter. Only show Menus for this particular enterprise. |
startTime |
Optional parameter. Only show Menus 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. |
endTime |
Optional parameter. Only show Menus 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. |
Sorting Information
You can use the SortBy GET query parameter to determine which attribute you want to sort by and in what order. The order can either be asc for ascending and desc for descending. Here is the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
Response Body
The response body contains code, corresponding message and data of the menu if successfully fetched. The HTTP response will be 200 OK.
The response returned is in JSON format as shown in the example below.
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
data of search as explained in table below |
Data parameters
| Data Parameter | Description |
|---|---|
result |
list of Menu data as explained in the Data Parameter section. |
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 |
uri |
Unique URI that you can call to get records |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/menu/search?autoAttendantSid=AA1dff3a6c89a34e12b4c31eb177e82e3f \
--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": "MNb4d808cd188a44aaae33c7aec05aac63",
"dateUpdated": "2020-01-28T07:00:47+0000",
"dateCreated": "2020-01-28T07:00:41+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/menu/search/MNb4d808cd188a44aaae33c7aec05aac63",
"name": "weekdays",
"autoAttendantSid": "AA1dff3a6c89a34e12b4c31eb177e82e3f",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"colorCode": "#e56052",
"keys": [
{
"menuKey": "1",
"menuAction": {
"actionType": "HANGUP"
}
}
],
"announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e"
}
],
"pageSize": 10,
"total": 1,
"page": 0,
"numPages": 1,
"start": 0,
"end": 0,
"firstPageUri": "/autoattendant/menu/search/?autoAttendantSid=AA1dff3a6c89a34e12b4c31eb177e82e3f%20&pageSize=10&page=0&%20name=sunday",
"uri": "/autoattendant/menu/search/?autoAttendantSid=AA1dff3a6c89a34e12b4c31eb177e82e3f%20&pageSize=10&page=0&%20name=sunday"
},
"code": 200,
"message": "OK"
}
Get Single Menu
The single menu search API allows users to retrieve specific menu.
Response Parameters
The search enterprise API will return error code and corresponding HTTP error as mentioned in the Common Response Error Codes section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
502 |
409 |
Menu not found |
Menu is not found. |
Delete Menu, Update Menu, Get Menu |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/menu/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": "MNb4d808cd188a44aaae33c7aec05aac63",
"dateUpdated": "2020-01-28T07:00:47+0000",
"dateCreated": "2020-01-28T07:00:41+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/menu/search/MNb4d808cd188a44aaae33c7aec05aac63",
"name": "weekdays",
"autoAttendantSid": "AA1dff3a6c89a34e12b4c31eb177e82e3f",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"colorCode": "#e56052",
"keys": [
{
"menuKey": "1",
"menuAction": {
"actionType": "HANGUP"
}
}
],
"announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e"
},
"code": 200,
"message": "OK"
}
{
"errorCode": "502",
"message": "Menu not found",
"data": {
"sid": "MNb4d808cd18a44aaae33c7aec05aac63",
"keys": []
}
}
Update Menu
This endpoint will be used to update an existing menu.
Request Parameters
| Parameter | Description |
|---|---|
name |
Name of the menu |
keys |
List of action type and action data for each of the keys as explained in the key data parameters section. |
enterpriseSid |
Sid of the enterprise the menu belongs to. |
autoAttendantSid |
Auto attendant sid the menu belongs to. |
colorCode |
Color code of the menu. |
announcementSid |
Optional announcement sid for the menu. |
timeoutSeconds |
Timeout duration of the menu |
timeoutAction |
Action type and action data to perform after timeout. Possible actionType are: Transfer to Phone, Dial by extension, Dial by name, Go To Menu, Return to previous menu, Replay Menu, Announcement Return, Announcement Hangup, Hangup. |
Response Body
The response body will contain code, corresponding message and menu data, if updating the menu was successful.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing the error, if error occurred, Or success message, if successful. |
data |
menu data as explained in the Data Parameter section |
Response Parameters
Update menu API will return error code and corresponding HTTP error as mentioned in the Common Response Error Codes section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
467 |
409 |
Enterprise not found |
Enterprise for which menu is to be added is not found. |
Create Menu, Update Menu |
500 |
409 |
Announcement not found |
Announcement sid is not found |
Create menu, Update Menu |
490 |
409 |
AutoAttendant System not found |
AA system Id is not found |
Create menu, Update Menu |
502 |
409 |
Menu not found |
Menu sid is not found |
Create menu, Update Menu |
Example
{
"name": "weekendmenu",
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"keys": [
{
"menuKey": "1",
"menuAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN5067f6f1c8f546dd909df1f50ee9f935"
}
}
],
"timeoutSeconds": 1,
"timeoutAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
},
"announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e",
"colorCode": "#e56052"
}
From the bash terminal you can run the command below:
curl -X PUT \
https://your_custom_domain.com/autoattendant/menu/ AA9fc6143123d048579f7d5b5d76572e1d \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"name": "weekendmenu",
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"keys": [
{
"menuKey": "1",
"menuAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN5067f6f1c8f546dd909df1f50ee9f935"
}
}
],
"timeoutSeconds": 1,
"timeoutAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
},
"announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e",
"colorCode": "#e56052"
}
If updating the menu is successful, below is the response returned:
{
"data": {
"sid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
"dateUpdated": "2020-01-29T05:28:11+0000",
"dateCreated": "2020-01-27T09:16:13+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/menu/search/MN064163a7f3c74f4594d5a8dc55bc4c33",
"name": "weekendmenu",
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"colorCode": "#e56052",
"keys": [
{
"menuKey": "1",
"menuAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN5067f6f1c8f546dd909df1f50ee9f935"
}
}
],
"timeoutSeconds": 1,
"timeoutAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
},
"announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e"
},
"code": 200,
"message": "OK"
}
If updating the Menu fails, below is the response returned. Exact error code and message will depend on error occurred
{
"errorCode": "502",
"message": "Menu not found",
"data": {
"sid": "MN064163a7f3c74f4594d5dc55bc4c33",
"keys": []
}
}
Delete Menu
This endpoint will be used to delete an existing menu.
Response Body
The response body will contain code, corresponding message and menu data, if deletion of the menu was successful.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing the error, if an error occurred. Or success message if successful. |
data |
Menu data describe in table Data Parameters section. |
Response Parameters
Delete menu API will return error code and corresponding HTTP error as mentioned in the Common Response Error Code section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
502 |
409 |
Menu not found |
Menu SID doesn’t exist in the system. |
Update Menu, Delete Menu, Get Menu |
506 |
409 |
This menu cannot be deleted as it is being used in a schedule. |
menu is being used in a schedule |
Delete Menu |
509 |
409 |
This menu cannot be deleted as it has announcements assigned to it. |
announcement is assigned to the menu |
Delete Menu |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
https://your_custom_domain.com/autoattendant/menu/ MN73b19aeef8d54073809d21edc8eb760b\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
If deletion of the menu is successful, below is the response is returned:
{
"data": {
"sid": "MN73b19aeef8d54073809d21edc8eb760b",
"dateUpdated": "2020-01-27T14:28:13+0000",
"dateCreated": "2020-01-27T14:28:13+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/menu/search/MN73b19aeef8d54073809d21edc8eb760b",
"name": "weekdaysmenu",
"autoAttendantSid": "AA1dff3a6c89a34e12b4c31eb177e82e3f",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"keys": [
{
"menuKey": "1",
"menuAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
}
}
],
"timeoutSeconds": 6,
"timeoutAction": {
"actionType": "HANGUP"
}
},
"code": 200,
"message": "OK"
}
If deletion of the Menu fails, below is the response returned. Exact error code and message depend on the error occurred.
{
"code":465,
"message":"Menu Not Found”,
“data”:{
“sid”:”AA9fc6143123d048579f7d5b5d76572e1d”
}
}
Auto Attendant System
Get list of AA-Systems
This endpoint will be used to get list of AA-Systems.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of AA-System records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If the search API is called without page and pageSize parameters, 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 |
|---|---|
name |
Optional parameter. Only show AA-System that match name text, partially or fully. |
enterpriseSid |
Optional Parameter. Only show AA-System for this particular enterprise. |
startTime |
Optional parameter. Only show AA-System 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. |
endTime |
Optional parameter. Only show AA-System 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. |
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:
Response Body
Response Body will carry Code, corresponding message and data of AA-System 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
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
data of search as explained in table below |
Data parameters
| Data Parameter | Description |
|---|---|
result |
list of AA system data as explained in the Data Parameters section. |
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 |
uri |
Unique URI that you can call to get records |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/system/search?name=welcome \
--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":"/autoattendant/system/search",
"first_page_uri":"/ autoattendant/ system /search?pageSize=2&page=0",
"previous_page_uri":null,
"next_page_uri":"/ autoattendant/ system /search?pageSize=2&page=1",
"data":[
{
“sid":"AA9fc6143123d048579f7d5b5d76572e1d",
“accountEmail”:”jane.doe@yourcompany.com”,
"dateCreated":"2019-07-22 09:53:51",
"dateUpdated":"2019-07-22 09:54:20",
"name": "Marketing",
"description": "this is marketing",
"numbers": [
"123-123123",
"12312-412"
],
"extensions": [
"123-123124",
"123-123125"
]
}
]
"uri":/autoattendant/system/search/AA9fc6143123d048579f7d5b5d76572e1d" }
]
}
Get Single AA-System
Single Menu search API allows users to retrieve specific Menu.
Response Parameters
Search Enterprise 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 |
AutoAttendant System not found |
AA-System is not found. |
Delete AA-System, Update AA-System, Get AA-System |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/system/search?enterpriseSid=ENc4a6ddacbea548f7b7b2dca120d5ff20 \
--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": "AAecf2e1b073184b3abf60bd9a0a86a63e",
"dateUpdated": "2020-01-22T09:55:26+0000",
"dateCreated": "2020-01-15T05:36:27+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/system/search/AAecf2e1b073184b3abf60bd9a0a86a63e",
"name": "Ent1 AA1",
"description": "Test AA for Ent1 for Nuso",
"status": "ACTIVE",
"aaNumbers": [
"15719916943",
"15719916944"
],
"extensions": [
"15717716943",
"917381101400"
],
"enterpriseSid": "ENc4a6ddacbea548f7b7b2dca120d5ff20",
"timeoutSeconds": 3,
"timeoutMaxOccurance": 2,
"timeoutAction": {
"actionType": "TRANSFER_TO_PHONE",
"actionData": "919960639901"
},
"invalidExtensionMaxOccurance": 2,
"invalidExtensionAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "ANdfefb0cb0eac43e1a0dbd508291e3c77"
},
"invalidInputMaxOccurance": 2,
"invalidInputAction": {
"actionType": "ANNOUNCEMENT_HANGUP"
},
"timezoneId": "US/Hawaii"
},
{
"sid": "AAc1824e46315f475989ccba1e5f3ba0b4",
"dateUpdated": "2020-01-22T06:40:33+0000",
"dateCreated": "2020-01-16T06:10:32+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/system/search/AAc1824e46315f475989ccba1e5f3ba0b4",
"name": "AA-1",
"status": "ACTIVE",
"aaNumbers": [
"12012108266",
"3144335465",
"3146265306",
"3146265307",
"3146265308",
"3146265309",
"3146265310"
],
"extensions": [
"917381101400"
],
"enterpriseSid": "ENc4a6ddacbea548f7b7b2dca120d5ff20",
"timeoutSeconds": 5,
"timeoutMaxOccurance": 3,
"timeoutAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "ANdfefb0cb0eac43e1a0dbd508291e3c77"
},
"invalidExtensionMaxOccurance": 2,
"invalidExtensionAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "ANdfefb0cb0eac43e1a0dbd508291e3c77"
},
"invalidInputMaxOccurance": 2,
"invalidInputAction": {
"actionType": "ANNOUNCEMENT_HANGUP",
"actionData": "ANab64856368fe4966b858aeba327a5188"
},
"timezoneId": "America/Phoenix"
},
{
"sid": "AA1853e05247094eb692f4fde127feb90c",
"dateUpdated": "2020-01-21T07:27:51+0000",
"dateCreated": "2020-01-17T10:50:06+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/system/search/AA1853e05247094eb692f4fde127feb90c",
"name": "AA 3",
"description": "AA test 3",
"status": "ACTIVE",
"aaNumbers": [],
"extensions": [
"15717716944"
],
"enterpriseSid": "ENc4a6ddacbea548f7b7b2dca120d5ff20",
"timeoutAction": {},
"invalidExtensionAction": {},
"invalidInputAction": {},
"timezoneId": "Arctic/Longyearbyen"
}
],
"pageSize": 10,
"total": 3,
"page": 0,
"numPages": 1,
"start": 0,
"end": 2,
"firstPageUri": "/autoattendant/system/search/?enterpriseSid=ENc4a6ddacbea548f7b7b2dca120d5ff20&pageSize=10&page=0",
"uri": "/autoattendant/system/search/?enterpriseSid=ENc4a6ddacbea548f7b7b2dca120d5ff20&pageSize=10&page=0"
},
"code": 200,
"message": "OK"
}
{
"errorCode": "490",
"message": "AutoAttendant System not found",
"data": {
"sid": "MNb4d808cd18a44aaae33c7aec05aac63"
}
}
Update Auto Attendant System
This endpoint will be used to update an existing auto attendant system.
Request Parameters
| Parameter | Description |
|---|---|
autoAttendantSid |
Unique Id of AA system. |
name |
Name of the Auto Attendant system |
PhoneNumbers |
List of phone numbers to be assigned to this system. |
Extensions |
Extensions to be included. |
Description |
Description of the Auto Attendant system. |
enterpriseSid |
Optional Enterprise id. If the user wants to move AA system from one enterprise to another, they have to pass the enterpriseId of target Enterprise. |
Response Body
Response Body will carry Code, corresponding message and AA system data if updating the AA-System was successful.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
AA system data as explained in the table below |
Data Parameters
| Data parameters | Description |
|---|---|
sid |
Unique ID generated by system. |
dateUpdated |
Timestamp when this AA system was updated. |
dateCreated |
Timestamp when this Menu was created. |
accountEmail |
CPaaS Account that created this particular Record |
uri |
Unique URI that you can call to get only this specific AA system |
name |
Name of the AA system. |
description |
Description of the AA system. |
status |
Status of the AA system. |
aaNumbers |
List of phone numbers assigned to the AA system. |
extensions |
List of Extensions assigned to the AA system. |
enterpriseSid |
Sid of the enterprise the AA system belongs to. |
timeoutSeconds |
Timeout duration of the AA system. |
timeoutMaxOccurance |
Consecutive timeout occurrences are allowed to timeout after which timeout action is performed. |
timeoutAction |
Action type and action data )if needed) to perform after timeout. |
invalidExtensionMaxOccurance |
Consecutive occurrences that the user presses invalid extension to perform invalid extension action. |
invalidExtensionAction |
Action type and action data (if needed) to perform after invalid extension max occurrences. |
invalidInputMaxOccurance |
Consecutive occurrences that the user presses unknown input. |
invalidInputAction |
Action type and action data (if needed) to perform after invalid input max occurrences. |
timezoneId |
Time zone in which AA system is being used. |
Response Parameters
Update AA-System API will return error code and corresponding HTTP error as mentioned in Common Response Error Codes section. Below is a list of all possible errors.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
467 |
409 |
Enterprise not found |
Enterprise for which menu is to be added is not found. |
Create AA System, Update AA System |
493 |
409 |
PhoneNumber is not an Extension number |
extension number assigned is not configured as extension |
Create AA System, Update AA System |
491 |
409 |
PhoneNumber not found |
Phone number is to be added is not found. |
Create AA System. Update AA System |
490 |
409 |
AutoAttendant System not found |
AA system id is not found |
Create AA System, Update AA System |
Example
{
"name": "Marketing",
"description": "this is marketing",
“enterpriseSid”: “ EN801e792d86504368a9385314e8c5c4d6”,
"numbers": [
"123-123123",
"12312-412"
],
"extensions": [
"101",
"102"
]
}
From the bash terminal you can run the command below:
curl -X PUT \
https://your_custom_domain.com/autoattendant/system/AA9fc6143123d048579f7d5b5d76572e1d \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d ' {
"name": "Sales
}’
If AA-System was updated successfully, below is the response returned:
{
"data": {
"sid": "AAa95f0d7ea0ce4863b2935523074bf466",
"dateUpdated": "2020-01-29T05:32:31+0000",
"dateCreated": "2020-01-21T13:36:20+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/system/search/AAa95f0d7ea0ce4863b2935523074bf466",
"name": "Ent2 AA test1",
"description": "Test AA for Ent2",
"status": "ACTIVE",
"aaNumbers": [
"1671331666"
],
"extensions": [
"1671331777"
],
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"timeoutSeconds": 2,
"timeoutAction": {},
"invalidExtensionAction": {},
"invalidInputAction": {},
"timezoneId": "Asia/Calcutta"
},
"code": 200,
"message": "OK"
}
If the update of the AA system fails, below is the response returned. Exact error code and message will depend on the error occurred.
{
"errorCode": "490",
"message": "AutoAttendant System not found",
"data": {
"sid": "AAa95f0d7ea0ce4863b29355074bf466"
}
}
Phone Number
Get list of Phone Numbers
This endpoint is used to get a list of AA-Systems.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Phonenumbers records to return, starting from 0. |
pageSize |
Number of records returned per page. |
| If the search API is called is called without page and pageSize parameters, by default pageSize will be set to 10 and page will be set to 0 to avoid retrieving all data in a single API call. |
Filtering
The following filtering parameters are supported.
| Query Parameter | Description |
|---|---|
enterpriseSid |
Optional Parameter. Only show AA-System for this particular enterprise. |
startTime |
Optional parameter. Only show AA-System 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. |
endTime |
Optional parameter. Only show AA-System 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. |
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 |
|---|---|
phoneNumber |
Sort by phone number |
dateCreated |
Sort by created date |
Response Body
Response Body will carry Code, corresponding message and data of Phone numbers 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
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
data of search as explained in table below |
Data parameters
| Data Parameter | Description |
|---|---|
result |
list of Phone number data as explained in the Data Parameter section. |
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 |
uri |
Unique URI that you can call to get records |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/phonenumber/search?enterpriseSid=EE0912eklmda3e13m \
--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": "PH440d21f6599d46f5930e995251273429",
"dateUpdated": "2020-01-21T13:44:44+0000",
"dateCreated": "2020-01-21T13:37:03+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/phonenumber/search/PH440d21f6599d46f5930e995251273429",
"number": "1671331777",
"isExtension": true,
"extension": "777"
},
{
"sid": "PH2996ad9926c9482aa1fe4da7e425a92a",
"dateUpdated": "2020-01-21T13:36:48+0000",
"dateCreated": "2020-01-21T13:36:48+0000",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/autoattendant/phonenumber/search/PH2996ad9926c9482aa1fe4da7e425a92a",
"number": "1671331666",
"isExtension": false,
"autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466"
}
],
"pageSize": 10,
"total": 2,
"page": 0,
"numPages": 1,
"start": 0,
"end": 1,
"firstPageUri": "/autoattendant/phonenumber/search/?enterpriseSid=EN838bcdf35f9d421fad3ab516195b873b&pageSize=10&page=0",
"uri": "/autoattendant/phonenumber/search/?enterpriseSid=EN838bcdf35f9d421fad3ab516195b873b&pageSize=10&page=0"
},
"code": 200,
"message": "OK"
}
Get Single Phone number
Single phone number search API allows users to retrieve a specific phone number.
Response Parameters
Search Enterprise 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 |
PhoneNumber not found |
Phonenumber not found in the system. |
Delete Phonenumber, Update Phonenumber, Get Phonenumber |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/phonenumber/search/PH440d21f6599d46f5930e995251273429 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"sid": "PH440d21f6599d46f5930e995251273429",
"dateUpdated": "2020-01-21T13:44:44+0000",
"dateCreated": "2020-01-21T13:37:03+0000",
"accountEmail": "jane.doe@yourdomain.com",
"uri": "/autoattendant/phonenumber/search/PH440d21f6599d46f5930e995251273429",
"number": "1671331777",
"isExtension": true,
"extension": "777"
},
"code": 200,
"message": "OK"
}
Update Phone numbers
This endpoint is used to update an existing phone number. A user can choose to make an extension an autoattendant number, or vice-versa.
Request Parameters
| Parameter | Description |
|---|---|
phonenumberSid |
Unique id of the phonenumber. |
isExtension |
If the number being added is an extension. If set to false, the number will be considered as an AA number. |
enterpriseSid |
Optional enterprise id. If a user wants to move a phoneNumber from one enterprise to another, they have to pass the enterpriseId of the destination enterprise. |
extensionSpokenName |
Spoken name of the extension. |
extension |
Extension number of the phone number. |
Response Body
The response body contains code, corresponding message and data of the phone number, if it was successfully updated. The HTTP response will be 200 OK.
The response returned is in JSON format as shown in the example below.
| Parameter | Description |
|---|---|
ode |
Sub-error response code |
message |
Message describing the error if an error occurred. Or a success message if successful. |
data |
Phone number Data as explained in the table below. |
Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique phoneNumber Sid. |
accountEmail |
Unique CPaaS account that created/updated this particular phone number. |
dateCreated |
Timestamp when this Enterprise was created. |
dateUpdated |
Timestamp when this Enterprise was updated. |
number |
Phone number |
isExtension |
Equals true if the number being added is an extension. Equals false if the number is considered an AA number. |
uri |
Unique URI that you can call to get only this specific PhoneNumber. |
enterpriseSid |
Sid of the enterprise the phoneNumber belongs to. |
extension |
Extension assigned to the number. |
extensionSpokenName |
Name of the user the extension belongs to. |
Update phoneNumber API can also return error code and corresponding HTTP crror as mentioned in the Common Response Error Codes section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
467 |
409 |
Enterprise not found |
Enterprise for which phoneNumber is to be added is not found. |
Create,update phonenumber |
491 |
409 |
PhoneNumber not found |
Phone number id not found |
Create,update phonenumber |
490 |
409 |
AutoAttendant System not found |
AA system Id is not found |
Create,update phonenumber |
Example
{
"autoAttendantSid":"AA1dff3a6c89a34e12b4c31eb177e82e3f"
}
From the bash terminal you can run the command below:
curl -X PUT \
https://your_custom_domain.com/autoattendant/phoneNumbers/ENb6eb071d21124dbab20b095c25f1274f \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d ' {
"autoAttendantSid":"AA1dff3a6c89a34e12b4c31eb177e82e3f"
}
’
If the phone number was successfully updated, below is the response returned:
{
"data": {
"sid": "PH2996ad9926c9482aa1fe4da7e425a92a",
"dateUpdated": "2020-01-21T13:36:48+0000",
"dateCreated": "2020-01-21T13:36:48+0000",
"accountEmail": "jane.doe@yourdomain.com",
"uri": "/autoattendant/phonenumber/search/PH2996ad9926c9482aa1fe4da7e425a92a",
"number": "1671331666",
"isExtension": false,
"autoAttendantSid": "AA1dff3a6c89a34e12b4c31eb177e82e3f"
},
"code": 200,
"message": "OK"
}
If the creation fails, below response is returned with a corresponding HTTP error code.
{
"errorCode": "491",
"message": "PhoneNumber not found",
"data": {
"sid": "PH2996ad9926c9482aa14da7e425a92a"
}
}
RCML
Get RCML
RCML is a markup language that instructs the core platform on what to do with incoming communication on specific channels - Voice or SMS. For more details please check out the RCML Overview documentation.
If you are trying to integrate an Auto Attendant system with a 3rd party application, your application may want to get access the RCML generated, based on incoming call and schedule setup for a number. For example, if Auto Attendant is integrated with Number Masking for a sales executive. In this case the executive would want to take official calls only between working hours and play a custom announcement during non working hours. The API’s exposed below can be easily integrated into Number Masking to achieve this functionality.
Supported Operations
HTTP GET: Get RCML setup for given Phone Number. The RCML returned will depend on the time of day when the API call was made. Auto Attendant System will execute the business logic to find the correct System, Schedule and corresponding Menu and then RCML will be returned.
Role based Authorization
-
ENTERPRISE_ADMIN users can search for RCML for numbers setup for their own enterprise only.
-
AA_ADMIN users do not have access to this API.
Response Body
The response body will contain the code, corresponding message and data of the RCML if successfully created. The HTTP response will be 200 Created (OK).
The response returned is a JSON format as shown in the example below.
| Parameter | Description |
|---|---|
code |
Sub-error response code |
message |
Message describing the error, if samee occurred. |
data |
Application data as explained in the Data Parameters section below. |
Data Parameter
| Data Parameter | Description |
|---|---|
rcml |
RCML generated |
enterpriseSid |
Sid of the enterprise. |
autoAttendantSid |
Auto Attendant SID which matched for passed number. |
menuSid |
Menu Sid which matched from given autoAttendantSid for Timestamp matching “asOf” parameter. |
asOf |
Timestamp when business logic was executed to find out RCML |
timezoneId |
Time Zone for which autoAttendantSid is setup. |
url |
Absolute URL of this RCML API call. |
Create application API can also return error code and corresponding HTTP error as explained in the Common Response Error Code section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
491 |
409 |
PhoneNumber not found |
Phone Number passed is not found |
|
490 |
409 |
Auto Attendant System not found |
Passed Number doesn’t have any AA system assigned |
|
498 |
409 |
No Schedule entry found for Auto Attendant system |
For given “asOf” no Menu is assigned |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/rcml/search/19960639901 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"rcml": "<Response><Gather action=\"https://your_custom_domain.com/autoattendant/internal/rcml?PreviousMenuSid=MN93d68cb1cd7743708e2b127dbe242d70&MenuSid=MN93d68cb1cd7743708e2b127dbe242d70&Organization=OR8732e31fbea24c36952698ed1e7054a6\" timeout=\"1\" input=\"dtmf\" actionOnEmptyResult=\"true\"><Say>There is no announcement assigned to this Menu.</Say></Gather></Response>",
"enterpriseSid": "EN70b163ea4290498287c06b8e286abbc2",
"autoAttendantSid": "AA920d5a7df87d47519f082e4942d328c9",
"menuSid": "MN93d68cb1cd7743708e2b127dbe242d70",
"asOf": "2020-08-26T10:03:21+0000",
"timezoneId": "Asia/Calcutta",
"uri": "/autoattendant/rcml/search/919960639901"
},
"code": 200,
"message": "OK"
},
"code": 200,
"message": "OK"
}
If the generation of RCML fails, corresponding error code and message is returned along with HTTP error response.
{
"code": "490",
"message": "AutoAttendant System not found",
"data": "919960639901"
}
Usage Records
Get Usage Records
Numbers are either main phone numbers or extension phone numbers added for a given enterprise. Usage Records keeps track of Number additions for a given month. For example if a number was added on the 5th day of Month and removed on 25th day of the same month, still that number will be counted under Usage Records for that particular month. However from next month onward it will not be counted as it was deleted. If the number was not deleted, the Usage Records count will include that number for next month and hence its monthly recurring count.
Filtering
Usage filters will return usage records for the passed filter. Following filtering parameters are supported.
| Query Parameter | Description |
|---|---|
startTime |
Only include usage that has occurred on or after this date. Format is YYYY-MM-DD. All dates are in GMT. As a convenience, you can also specify offsets to today. For example, StartDate=-30days will make StartDate be 30 days before today. |
endTime |
Only include usage that has occurred on or before this date. Format is YYYY-MM-DD. All dates are in GMT. As a convenience, you can also specify offsets to today. For example, EndDate=+30days will make EndDate be 30 days from today. |
organisationSid |
Mandatory for SUPPORT_ADMIN users. Only include Usage records for Specific Organisation. Only users with SUPPORT_ADMIN role can pass this parameter. If users with any other role passes this parameter, it’s ignored. |
enterpriseSid |
Optional. Only include Usage records for specific Enterprise.+ If CSP_ADMIN is calling this API and enterpriseSid is not passed, Usage Records for the entire Organisation is retrieved. For ENTERPRISE_ADMIN use this parameter is ignored. |
Response Body
Response Body will carry Code, corresponding message and data of Usage Records 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
| Code | Description |
|---|---|
usageRecords |
data of Usage Records as explained in table below |
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 |
uri |
Unique URI that you can call to get records |
Data parameters
Data Parameter |
Description |
category |
The category of Usage Records. As of today only “phonenumbers” is supported |
description |
Description of Usage Records |
startDate |
The first date for which usage is included in this UsageRecord. The date is specified in GMT and formatted as YYYY-MM-DD |
endDate |
The last date for which usage is included in the UsageRecord. The date is specified in GMT and formatted as YYYY-MM-DD. |
asOf |
Usage records up to date as of this timestamp, formatted as YYYY-MM-DDTHH:MM:SS+00:00. All timestamps are in GMT |
count |
The number of usage events, such as the number of calls. In this case Phone Numbers including Extension Phone Numbers provisioned |
countUnit |
The units in which count is measured, such as calls for calls or messages for SMS. In this case Phone Numbers |
usage |
The amount used to bill usage and measured in units described in usage_unit. |
usageUnit |
The units in which usage is measured, such as minutes for calls or messages for SMS. |
uri |
Unique URI that you can call to get records |
Example of Numbers Usage
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/phonenumber/usage/records?startDate=2019-07-01&endDate=2019-07-23
\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned.
{
"usageRecords":
[
{
"description":"Total Numbers created",
"enterpriseSid":"ACae6e420f425248d6a26948c17a9e2acf",
"startDate":"2019-07-01",
"endDate":"2019-07-23",
"count":"2123",
“countUnit”:”numbers”
"usage": "2123",
"usageUnit": "numbers",
"uri":"/autoattendant/phonenumber/usage/records?startDate=2019-07-01&endDate=2019-07-23"
}
],
"pageSize": 10,
"total": 1,
"page": 0,
"numPages": 1,
"start": 0,
"end": 1,
"firstPageUri":"/autoattendant/phonenumber/usage/records?startDate=2019-07-01&endDate=2019-07-23&pageSize=10&page=0",
"uri":"/autoattendant/phonenumber/search/?enterpriseSid=EN838bcdf35f9d421fad3ab516195b873b&pageSize=10&page=0"
}
Request Subresource
The main UsageRecords list resource supports a variety of convenience subresources. In general these take the form:
/autoattendant/phonenumbers/usage/records/{Subresource}
Supported subresources are:
| Subresource | Description |
|---|---|
daily |
Return Usage record on a daily basis. If no date filter is passed, last 30 days usage is retrieved. |
monthly |
Return Usage record on a monthly basis. If no date filter is passed, last 12 months usage is retrieved |
yearly |
Return Usage record on yearly basis. If no date filter is passed, only this year and previous year usage is retrieved. |
today |
Return Usage record today. |
yesterday |
Return Usage record yesterday. |
thismonth |
Return Usage record this month. |
lastmonth |
Return Usage record last month. |
Example:
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/autoattendant/phonenumber/usage/records/daily?startDate=2019-07-21&endDate=2019-07-23 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"usageRecords":
[
{
"description":"Total Numbers created",
"enterpriseSid":"ACae6e420f425248d6a26948c17a9e2acf",
"startDate":"2019-07-21",
"endDate":"2019-07-21",
"count":"101",
"countUnit":"numbers"
"usage": "101",
"usageUnit":"numbers",
"uri":"/autoattendant/phonenumber/usage/records/daily?startDate=2019-07-21&endDate=2019-07-21"
},
{
"description":"Total Numbers Created",
"enterpriseSid":"ACae6e420f425248d6a26948c17a9e2acf",
"startDate":"2019-07-22",
"endDate":"2019-07-22",
"count":"134",
"countUnit":"numbers"
"usage": "134",
"usageUnit":"numbers",
"uri":"/autoattendant/phonenumber/usage/records/daily?startDate=2019-07-22&endDate=2019-07-23"
}
],
"pageSize": 10,
"total": 1,
"page": 0,
"numPages": 1,
"start": 0,
"end": 1,
"firstPageUri":"/autoattendant/phonenumber/usage/records/daily?startDate=2019-07-21&endDate=2019-07-23&pageSize=10&page=0",
"uri":"/autoattendant/phonenumber/usage/recordsdaily?startDate=2019-07-21&endDate=2019-07-23&pageSize=10&page=0"
}
In the above example if startDate and endDate parameters are not passed, 30 records will be shown.