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

Base Resource URI

https://$DOMAIN

Add User Resource URI

/autoattendant/user

Supported Operations

HTTP POST: Add 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:
* BG_ADMIN
* AA_ADMIN

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.

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.

Base Resource URI

https://$DOMAIN

Get User list Resource URI

/autoattendant/user/search

Supported Operations

HTTP GET: Get User list

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

email

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 users 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.

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.

Base Resource URI

https://$DOMAIN

Get Single User Resource URI

/autoattendant/user/search/{userId}

Supported Operations

HTTP GET: 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.

Base Resource URI

https://$DOMAIN

Update User Resource URI

/autoattendant/user/{UserSid}

Supported Operations

HTTP PUT: Update User

Request Parameters

Parameter Description

UserSid

Unique id of the user.

status

Status of the user. Could be one of the following:

- ACTIVE
- SUSPENDED
- DELETED

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.

Base Resource URI

https://$DOMAIN

Add Announcement Resource URI

/autoattendant/announcement

Supported Operations

HTTP POST: Add announcement

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.
- play: Make an announcement by playing an audio file. In that case upload announcement file should be called to upload the announcement file.

body

Optional. Mandatory if type is set tp say.

Text-to-speech body. Please visit the Say RCML documentation for more information.

language

Optional. Mandatory if type is set tp say.

Text-to-speech language as explained in the Say RCML documentation.

voice

Optional. Mandatory if type is set to say.

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.
- play: Make an announcement by playing an audio file.

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 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 endpoint lets you upload an audio file for the announcement to the Auto Attendant System.

Base Resource URI

https://$DOMAIN

Upload Announcement Resource URI

/autoattendant/file/announcement/{announcementSid}

Supported Operations

HTTP POST: Upload audio file

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.

Base Resource URI

https://$DOMAIN

Get Announcement List Resource URI

/autoattendant/user/search

Supported Operations

HTTP GET: Get Announcement list

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:

Sort Attributes

Parameter Description

name

Sort by name

dateCreated

Sort by created date

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.

Base Resource URI

https://$DOMAIN

Get Single Announcement Resource URI

/autoattendant/announcement/search/{announementSid}

Supported Operations

HTTP GET: 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.

Base Resource URI

https://$DOMAIN

Update Announcement Resource URI

/autoattendant/announcement/{announcementSid}

Supported Operations

HTTP PUT: Update 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.

Base Resource URI

https://$DOMAIN

Delete Announcement Resource URI

/autoattendant/announcement/{announcementSid}

Supported Operations

HTTP DELETE: Delete announcement

Request Parameters

Parameter Description

announcementSid

SID to uniquely identify an announcement.

Response Body

The response body will carry code, corresponding message and announcement data, if 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.

Base Resource URI

https://$DOMAIN

Add Menu Resource URI

/autoattendant/menu

Supported Operations

HTTP POST: Add 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 (0-9 and *).

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 Name must have been defined as an extension.

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.

Base Resource URI

https://$DOMAIN

Get Menu List Resource URI

/autoattendant/menu/search

Supported Operations

HTTP GET: Get Menu list

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.

Sort Attributes

Parameter Description

name

Sort by name.

dateCreated

Sort by created date.

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.

Base Resource URI

https://$DOMAIN

Get Single Menu Resource URI

/autoattendant/menu/search/{menuSid}

Supported Operations

HTTP GET: 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.

Base Resource URI

https://$DOMAIN

Update Menu Resource URI

/autoattendant/menu/{MenuSid}

Supported Operations

HTTP PUT: Update 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.

Base Resource URI

https://$DOMAIN

Delete Menu Resource URI

/autoattendant/menu/{MenuSid}

Supported Operations

HTTP DELETE: Delete Menu

Request Parameters

Parameter Description

menuSid

SID to uniquely identify a 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.

Base Resource URI

https://$DOMAIN

Add Schedule Resource URI

/autoattendant/schedule

Supported Operations

HTTP POST: Add schedule

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),
- DATE_RANGE (special days 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)
Entries parameters:
Data Parameter Description

day

Day of the week. Possible values: 1 to 7 (Monday to Sunday).

startTime

Start time in HH:MM format.

endTime

endTime in HH:MM format.

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

Base Resource URI

https://$DOMAIN

Get Schedule Resource URI

/autoattendant/schedule/search

Supported Operations

HTTP GET: Specific 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.

Base Resource URI

https://$DOMAIN

Get AA system list Resource URI

/autoattendant/system/search

Supported Operations

HTTP GET: Get AA-System list

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:

Sort Attributes

Parameter Description

name

Sort by name

dateCreated

Sort by created date

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.

Base Resource URI

https://$DOMAIN

Get Single AA system Resource URI

/autoattendant/system/search/{AAsystemSid}

Supported Operations

HTTP GET: 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.

Base Resource URI

https://$DOMAIN

Update AA-System Resource URI

/autoattendant/system/{autoAttendantSid}

Supported Operations

HTTP PUT: Update 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 ACTIVE and SUSPENDED.

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 TZDB 2005r (Time Zone Database) and maintained by https://www.iana.org/time-zones.

For example for US mountain Timezone, pass US/Mountain.

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 Hangup the call.

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 Hangup the call.

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 Hangup the call.

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.

Base Resource URI

https://$DOMAIN

Get Phone Number list Resource URI

/autoattendant/phonenumber/search

Supported Operations

HTTP GET: Get Phone Number list

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.

Base Resource URI

https://$DOMAIN

Get Single Phone number Resource URI

/autoattendant/phonenumber/search/{phonenumberSid}

Supported Operations

HTTP GET: 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.

Base Resource URI

https://$DOMAIN

Update phone number Resource URI

/autoattendant/phonenumber/{phoneNumberSid}

Supported Operations

HTTP PUT: Update Phone number

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.

Base Resource URI

https://$DOMAIN

Get AA Usage Resource URI

/autoattendant/phonenumber/usage/records

Supported Operations

HTTP GET: List usage records for numbers

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.

Base Resource URI

https://$DOMAIN

Get RCML Resource URI

/autoattendant/rcml/search/{phoneNumber}

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 parameter.

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&amp;MenuSid=MN93d68cb1cd7743708e2b127dbe242d70&amp;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"
}