Auto Attendant API
Overview
CPaaS Auto Attendant (AA) is designed for business customers who want to provide an automated means of directing incoming calls to the appropriate person within the organization.Typically to offload this task from a receptionist and also offer a simple menu system ("For menu, press 1, for transfer to phone, press 2." etc.).To learn more about the AA System please have a look at the Auto Attendant General Documentation.
This document contains important information regarding the setup and management of Auto Attendant using the API.
To find out more about the Console user interface, check out the Auto Attendant Console documentation.
Restcomm Auto Attendant API’s can be broadly classified as below operations
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. |
Users
This endpoint is used to create an user depending on the role as explained below.
-
Enterprise Admin (also known as BG_ADMIN) can create users with role Enterprise Admin and AA Admin (also known as AA_ADMIN)
-
AA Admin (also known as AA_ADMIN).The only difference between Enterprise Admin and AA Admin is that AA Admin cannot add any new users and cannot make changes to Extensions.
Create User
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: |
status |
Optional. Will be set to ACTIVE if not passed. Possible values are: |
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.
Parameter | Description |
---|---|
code |
Sub-error code for response |
message |
Message describing the error, if an error occurred or success message, in case of successful operation. |
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 in 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 list 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 User API will return an error code and a corresponding HTTP error as mentioned in the 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.
-
BG_ADMIN can make changes to other users with BG_ADMIN and AA_ADMIN roles 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 |
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 |
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
Announcements are associated with menus, action data for specific actions (like press of a key, for example) or error handling.
Create Announcement
This API endpoint is used to create an Announcement for an Enterprise.
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 |
Optional. Mandatory if Text-to-speech body. Please visit the Say RCML documentation for more information. |
language |
Optional. Mandatory if Text-to-speech language as explained in the Say RCML documentation. |
voice |
Optional. Mandatory if Voice of speech. The voice options are 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. |
file_uri |
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. Possible options are |
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 endpoint lets you upload an audio file for the announcement to the Auto Attendant System.
Request Parameters
Parameter | Description |
---|---|
announcementSid |
Mandatory. Sid to uniquely identify an announcement. |
file |
Mandatory. 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 get a list of Announcements.
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" } }
Menu
Menu allows Enterprise Users to set a specific action to be executed based on a key pressed by the caller.
Create Menu
This endpoint is used to create a menu.
Request Parameters
Parameter | Description |
---|---|
name |
Mandatory. Name of the menu. |
keys |
Optional. List of action type and action data for each of the keys, as explained in the key data parameters section below. |
enterpriseSid |
Mandatory. Sid of the enterprise the menu belongs to. |
autoAttendantSid |
Mandatory. Auto Attendant sid the menu belongs to. |
colorCode |
Optional. Color code of the menu. |
announcementSid |
Optional. Optional announcement sid for the menu. |
timeoutSeconds |
Optional. Timeout duration of the menu. |
timeoutMaxOccurance |
Optional. The amount of allowed consecutive Timeouts before the timeoutAction gets executed. If set, it overwrites the global timeoutSeconds defined at the Auto Attendant level. |
timeoutAction |
Optional. Action type and action data to perform after a timeout. If set, it overwrites the global timeoutSeconds defined at the Auto Attendant level. Possible actionType values are explained in the Action Type table. |
ringbackToneSid |
Optional announcement sid that will be played as a Ringback Tone whenever an extension is dialed, or the call is transferred to Phone. For example, if a caller wants to connect to the Sales department when an extension is dialed, instead of hearing the usual ringback tone, the Enterprise may want to play an announcement like: “Hold on the line while we are connecting you to Sales.”, or any other marketing message. If not assigned, the default will be the one set by your operator. |
Key data parameters
key Parameter | Description |
---|---|
menuKey |
A menu key ( |
menuAction |
Contains actionType and actionData (if needed) for each key. actionType values are defined in the table below. |
Action Type table
actionType | Description | actionData |
---|---|---|
ANNOUNCEMENT_HANGUP |
Play the selected Announcement and hang up the call. |
Yes.Announcement sid to be played. |
ANNOUNCEMENT_RETURN |
Play the selected Announcement and return to the Menu options.The system will replay the Menu Announcement. |
Yes.Announcement sid to be played. |
DIAL_BY_EXTENSION |
Dial the Extension number entered by the caller. |
Yes.Announcement sid to be played. |
DIAL_BY_NAME |
Listen to the speech of the caller and dial the corresponding extension.For this to work correctly the |
Yes.Announcement sid to be played. |
GO_TO_MENU |
Play the selected Menu. |
Yes.Menu sid to go to. |
HANGUP |
Hang Up the call. |
No |
REPLAY_MENU |
Replay the existing Menu. |
No |
RETURN_TO_PREVIOUS_MENU |
Replay the previous Menu. |
No |
TRANSFER_TO_PHONE |
Transfer the call to a specified Phone Number. |
Yes. Phone number. |
An announcement can be set for both Dial by name and Dial by extension action.In case no announcement is selected for the action types mentioned above, then the Dial by name will default to: "Please say the name", and dial by extension will default to: "Please press the extension number".
|
Response Body
The response body will carry code, corresponding message and unique id if the creation of a menu is successful.
Parameter | Description |
---|---|
code |
Sub-error code for response |
message |
Message describing the error if an error occurred, or a success message if the operation was successful. |
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. |
timeoutMaxOccurance |
The amount of allowed consecutive Timeouts before the timeoutAction gets executed. |
timeoutAction |
Time out action type and action data of the menu. |
ringbackToneSid |
Ringback tone announcement sid assigned to this menu. |
uri |
Unique URI that you can call to get only this specific menu. |
Response Parameters
Create Menu API will return an error code along with a 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 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 the menu is successful, the following response is 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 the menu fails, below is the response returned. The exact error code and message depend on the occurred error.
{ "errorCode": "490", "message": "AutoAttendant System not found", "data": { "sid": "AAa95f0d7ea0ce4863b235523074bf466" } }
Get list of Menus
This endpoint is used to get a list of menus.
Paging
The following paging parameters are supported
Query Parameter | Description |
---|---|
page |
Which page of the Menu records to return, starting from 0. |
pageSize |
Number of records returned per page. |
When the search API is called without page and pageSize parameters set, by default pageSize will equal 10 and page will be 0 to avoid retrieving all the data in a single API call.
|
Filtering
The following filtering parameters are supported.
Query Parameter | Description |
---|---|
name |
Optional. Only show menus that match the name text partially or fully. |
enterpriseSid |
Optional. Only show Menus for this particular enterprise. |
startTime |
Optional. 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 the UTC timezone. |
endTime |
Optional. 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 the UTC timezone. |
Sorting Information
You can use the SortBy
GET query parameter to determine by which attribute you would like to sort by and in what order. The order can either be asc
for ascending or 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 a list of the 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 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/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 can be used to update an existing menu.
Request Parameters
Takes all the request parameters explained in Create Menu Request Parameters section.
Response Body
The response body will contain an error code, a corresponding message and a menu data, if updating the menu was successful.
Parameter | Description |
---|---|
code |
Sub-error code response. |
message |
Message describing the error, if an error occurred, Or a success message, if the operation successful. |
data |
Menu data as explained in the Data Parameters section. |
Response Parameters
Update menu API will return an error code, and a 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 the 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 depend on the error occurred.
{ "errorCode": "502", "message": "Menu not found", "data": { "sid": "MN064163a7f3c74f4594d5dc55bc4c33", "keys": [] } }
Delete Menu
This endpoint is used to delete an existing menu.
Response Body
The response body will contain an error code, a corresponding message and a 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 a success message if the operation was successful. |
data |
Menu data as described in the Data Parameters section. |
Response Parameters
Delete menu API will return an error code, and a 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 does not 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. |
The menu is being used in a schedule. |
Delete Menu |
509 |
409 |
This menu cannot be deleted as it has announcements assigned to it. |
An 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 the deletion of the menu is successful, below is the response 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 the deletion of the menu fails, below is the response returned.The exact error code and message depend on the error occurred.
{ "code":465, "message":"Menu Not Found”, “data”:{ “sid”:”AA9fc6143123d048579f7d5b5d76572e1d” } }
Schedule
Schedule allows Enterprise Users to select a menu based on day and time of on incoming call.
Create Schedule
This API endpoint 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.(In case of Special days Schedule) |
endDate |
end date of the special days schedule.(In case of Special days Schedule) |
Response Body
Thw response body will carry an error code, a corresponding message and an unique id if the creation of schedule is successful.
Parameter | Description |
---|---|
code |
Sub-error code response. |
message |
Message describing the error if an error occurred, or a success message if the operation is successful. |
data |
Schedule data as explained in the Entries parameters. |
Response Parameters
Create Schedule API will return an error code and a 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. |
The Auto Attendant Sid passed does not exist. |
Create schedule, Update schedule |
502 |
409 |
Menu not found. |
The 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 the 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 the schedule fails, below is the response returned. The 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 the 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. The exact error code and message 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" }
Auto Attendant System
Get list of AA-Systems
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 the AA-System records to return, starting from 0. |
pageSize |
Number of records returned per page. |
If the search API is called without setting the page and pageSize parameters, by default pageSize will be 10 and page will be 0 to avoid retrieving all the 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 |
A 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 AA search API allows users to retrieve specific AA System.
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 |
Mandatory. Unique Id of AA system. |
name |
Optional. Name of the Auto Attendant system. |
aaNumbers |
Optional. List of phone numbers to be assigned to this system. |
extensions |
Optional. Extensions to be included. |
description |
Optional. Description of the Auto Attendant system. |
status |
Optional. Status of the Auto Attendant system. The only possible values are |
timezoneId |
Optional. Set the timezone where the AA System is being used. The timezone should be passed in a format that is compatible with the For example for US mountain Timezone, pass If not defined, the default timezone is UTC. |
timeoutSeconds |
Optional. Set the Timeout seconds to wait for the caller action. If not defined, the default is 5 seconds. |
timeoutMaxOccurance |
Optional. Set how many consecutive Timeout occurrences are allowed after which below defined action will be performed. If not defined, default is 3. Callers will hear the same Menu Announcement till occurrences exhausts. |
timeoutAction |
Optional. Set the action as defined in Action Type section and respective data of the action if needed to carry out that particular action. If not defined, the default is to |
invalidInputMaxOccurance |
Optional. Set the number of occurrences the user presses unknown input after which an action will be performed. If not defined, the default is 3. The callers will hear the same Menu Announcement until the number of occurrences is reached. |
invalidInputAction |
Optional. Set the action as defined in Action Type section and respective data of the action if needed to carry out that particular action. If not defined, the default is to |
invalidExtensionMaxOccurance |
Optional. Set the number of occurrences the user presses Invalid Extension after which an action will be performed. If not defined, the default is 3. |
invalidExtensionAction |
Optional. Set the action as defined in Action Type section and respective data of the action if needed to carry out that particular action. If not defined, the default is to |
Response Body
Response Body will carry an error code, a corresponding message and AA system data if updating the AA-System is 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 allowed 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 Phone numbers
assigned to your enterprise.If you don’t see the phone numbers listed, please contact your service provider.
Paging
The following paging parameters are supported
Query Parameter | Description |
---|---|
page |
Which page of Phone Numbers records to return, starting from 0. |
pageSize |
Number of records returned per page. |
If the search API is called without specifying the 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 |
A list of Phone number data. |
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 Phone Number. |
isExtension |
If the number being added is an extension. If set to false, the number will be considered as an AA number. |
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" } }
Usage Records
Get Usage Records
Numbers are either main Phone Numbers or Extension Phone Numbers and are billable units for your Enterprise.Usage Records keeps track of Number additions for a given month.For example, if a number was added on the 5th day of the month and removed on the 25th day of the same month, it will still be counted under Usage Records for that particular month.However, from the 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 the 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. |
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.
Third-Party Integration
This section is for advanced users who are trying to leverage the scheduling capability of Auto Attendant and integrate with their own application built on the top of the Restcomm platform.
RCML API
If you are trying to integrate an Auto Attendant system with your own custom application, your application may have to get access to the RCML generated, based on incoming calls and schedule setup for a number.For more details please check out the RCML Overview documentation.
For example, if an 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 APIs exposed below can be easily integrated into Number Masking to achieve this functionality.
Supported Operations
HTTP GET: Get RCML setup for a given Phone Number. The RCML returned will depend on the time of day when the API call was made. The 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 an error code, a 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 it 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 the passed number. |
menuSid |
Menu Sid which matched from the given autoAttendantSid for Timestamp matching |
asOf |
Timestamp when business logic was executed to find out RCML. |
timezoneId |
Timezone for which autoAttendantSid is setup. |
url |
Absolute URL of the RCML API call. |
Create application API can also return an error code and a 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 does not 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, a corresponding error code and a message are returned along with the HTTP error response.
{ "code": "490", "message": "AutoAttendant System not found", "data": "919960639901" }