Auto Attendant API

Overview

Auto Attendant API allows Enterprise Accounts to Edit Autoattendant, manage users, assign phone numbers and assign extensions.

CPaaS Auto Attendant API’s can be broadly classified as below operations

Where ever API returns 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 offset ±[hh][mm] will always be +0000.

Create Operation

Create allows Enterprise admins to create users,announcement,schedule,menu, and can edit auto attendant systems, phone numbers.

AA Admins can create schedules, menus, upload/record announcements.

Create User

This endpoint will be used to create user depending on role as explained below.

  • SUPPORT can add another user with role SUPPORT(This role is not yet defined to be done in future)

  • CSP_ADMIN can create users with role ENTERPRISE_ADMIN (a.k.a BG Admin) and AA_ADMIN

  • ENTERPRISE_ADMIN can create users with role ENTERPRISE_ADMIN and AA_ADMIN within same Enterprise

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: SUPPORT (This is specifically for Support Not yet implemented), CSP_ADMIN, ENTERPRISE_ADMIN, AA_ADMIN, USER_ADMIN(Not yet Implemented)

status

Optional. Will be set to active if not passed. Possible values are: ACTIVE, SUSPENDED, DELETED

enterpriseSid

Sid of the enterprise the user belongs to.

Response Body

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

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

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

User data as explained in the table below.
Data Parameter
Data Parameter Description

sid

Unique User Id

accountEmail

Unique CPaaS Account that created this particular user

dateCreated

Timestamp when this User was created

dateUpdated

Timestamp when this User was updated

name

Name of this user

emailId

Email Id of the user created

role

Role of the user

status

Status of the user(ACTIVE/INACTIVE)

uri

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

Response Parameters

Create User API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return

Error Code HTTP Status Error Message Description Category

499

409

Error in creating subaccount on CPaaS

Error while creating subaccount 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 subaccount belongs to a different Admin account

user id is already subaccount to 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"
    }
}

Create Announcement

Creating an announcement will upload an audio file to AA System and will populate the uri in Database.

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 which case below parameters are mandatory
- play: Make an announcement by playing an audio file. In this case Upload Announcement file should be called to upload Announcement File.

body

Text-to-speech body. Please visit Say-RCML to understand more.

language

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

voice

Voice of speech. . Options depend upon the TTS providers and are as below:

- Google: Male and Female
- AWS Polly: Male and Female
- Acapela: Male and Female
- Voicerss: Female(only)

Response Body

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

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

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

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 this particular announcement

dateCreated

Timestamp when this announcement was created

dateUpdated

Timestamp when this announcement was updated

uri

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

enterpriseSid

Sid of the enterprise the announcement belongs to.

fileUri

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

type

Type of the announcement. Possible options are:

- say: Make an announcement from text-to-speech, in which case below parameters are mandatory.
- play: Make an announcement by playing an audio file.

body

Text-to-speech body

language

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

voice

Voice of speech. Options depend upon the TTS providers and are as below:

- Google: Male and Female

- AWS Polly: Male and Female

- Acapela: Man and Woman

- Voicerss: Female(only)

Response Parameters

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

Error Code HTTP Status Error Message Description Category

467

409

Enterprise not found

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

Create Announcement

490

409

AutoAttendant System not found

AA 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 Male/Female for Google or Awspolly, Man/Woman for Acapela and only female for Voicerss

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 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 will depend on error occurred

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

Upload Announcement file

This API will upload an audio file to S3 for the announcement.

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

Sid to uniquely identify an announcement

file

Audio file in wav format to be uploaded in the recommended bitrate.

Please visit Media Server Audio File Format to find out more about the supported audio file formats.

Response Body

The response body will carry the code, corresponding message and data of the Announcement, if the file was successfully uploaded and linked to the announcement. HTTP response 200 (OK) will be returned.

The response is returned in the JSON body 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 occured), or success message.

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.
Rest of the response parameters are the same as explained in Response Data Parameter of Create Announcement.

Response Parameters

Create announcement API will return an errorcCode 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 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": "mainbgadmin@ent1.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"
    }
}

Create Schedule

This API creates a schedule for an AA 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 autoAttendant system as explained below in Schedule parameters section

scheduleType

Type of the schedule. Possible Values: WEEKLY(weekly schedule), DATE_RANGE(special days schedule)
Schedule parameters:
Data Parameter Description

entries

List Schedule Timeframes as explained below in Entries parameters section (in case of weekly schedule)

menuSid

Menu sid of which entries/Special days belong to.

scheduleType

Type of the schedule entries. Possible Values: 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

Response Body will carry Code, corresponding message and unique-id if creation of schedule was successful.

Parameter Description

code

Sub-error code for response

message

Message describing error if error occurred or success message

data

Schedule data explained in Request Parameters section below

Response Parameters

Create Schedule API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return

Error Code HTTP Status Error Message Description Category

490

409

AutoAttendant System not found

AutoAttendant Sid passed does not exist

Create schedule, Update schedule

502

409

Menu not found

Menu Sid passed does not exist

Create schedule, Update schedule

Weekly Schedule Example

{
	"autoAttendantSid":"AAa95f0d7ea0ce4863b2935523074bf466",
"scheduleType":"WEEKLY",
"schedule":[
	{"menuSid":"MN8922ed9aba854ce3afe17b0f1725e2b5",
	"scheduleType":"WEEKLY",
	"entries":[
		{"day":1,
		"startTime":"01:00",
		"endTime":"04:00"

		}
		]
	}
	]
}

From the bash terminal you can run the command below:

curl -X POST \
  https://your_custom_domain.com/autoattendant/schedule\
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"autoAttendantSid":"AAa95f0d7ea0ce4863b2935523074bf466",
            "scheduleType":"WEEKLY",
             "schedule":[
	{"menuSid":"MN8922ed9aba854ce3afe17b0f1725e2b5",
	"scheduleType":"WEEKLY",
	"entries":[
		{"day":1,
		"startTime":"01:00",
		"endTime":"04:00"

		}
		]
	}
	]
}’

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

{
    "data": {
        "autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
        "scheduleType": "WEEKLY",
        "schedule": [
            {
                "menuSid": "MN8922ed9aba854ce3afe17b0f1725e2b5",
                "scheduleType": "WEEKLY",
                "entries": [
                    {
                        "day": 1,
                        "startTime": "01:00",
                        "endTime": "04:00"
                    }
                ]
            }
        ]
    },
    "code": 200,
    "message": "OK"
}

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

{
    "errorCode": "490",
    "message": "AutoAttendant System not found",
    "data": {
        "sid": "AAa95f0d7ea0ce483b2935523074bf466"
    }
}

Special Days Schedule Example

{
  "autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
  "schedule": [
    {
      "startDate": "2020-01-22",
      "endDate": "2020-01-22",
      "menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
      "scheduleType": "DATE_RANGE"
    },
    {
      "startDate": "2020-01-30",
      "endDate": "2020-01-30",
      "menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
      "scheduleType": "DATE_RANGE"
    },
    {
      "startDate": "2020-01-23",
      "endDate": "2020-01-23",
      "menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
      "scheduleType": "DATE_RANGE"
    }
  ],
  "scheduleType": "DATE_RANGE"
}

From the bash terminal you can run the command below:

curl -X POST \
  https://your_custom_domain.com/autoattendant/schedule\
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
  "schedule": [
    {
      "startDate": "2020-01-22",
      "endDate": "2020-01-22",
      "menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
      "scheduleType": "DATE_RANGE"
    },
    {
      "startDate": "2020-01-30",
      "endDate": "2020-01-30",
      "menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
      "scheduleType": "DATE_RANGE"
    },
    {
      "startDate": "2020-01-23",
      "endDate": "2020-01-23",
      "menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
      "scheduleType": "DATE_RANGE"
    }
  ],
  "scheduleType": "DATE_RANGE"
}\’

If creation of Special days Schedule is successful, below is the response returned:

{
  "data": {
    "autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
    "scheduleType": "DATE_RANGE",
    "schedule": [
      {
        "menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
        "scheduleType": "DATE_RANGE",
        "entries": [],
        "startDate": "2020-01-22",
        "endDate": "2020-01-22"
      },
      {
        "menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
        "scheduleType": "DATE_RANGE",
        "entries": [],
        "startDate": "2020-01-30",
        "endDate": "2020-01-30"
      },
      {
        "menuSid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
        "scheduleType": "DATE_RANGE",
        "entries": [],
        "startDate": "2020-01-23",
        "endDate": "2020-01-23"
      }
    ]
  },
  "code": 200,
  "message": "OK"
}

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

{
    "errorCode": "490",
    "message": "AutoAttendant System not found",
    "data": {
        "sid": "AAa95f0d7ea0ce483b2935523074bf466"
    }
}

Create Menu

This endpoint will be 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

Name of the menu

keys

List of Action Type and action Data for each of the keys explained in below key data parameters: section.

enterpriseSid

Sid of the enterprise the menu belongs to.

autoAttendantSid

Auto attendant sid the menu belongs to.

colorCode

Color code of the menu

announcementSid

optional announcement sid for the menu.

timeoutSeconds

timeout duration of the menu

timeoutAction

Action type and action data to perform after timeout. Possible actionType are: Transfer to Phone, Dial by extension, Dial by name, Go To Menu, Return to previous menu, Replay Menu, Announcement Return, Announcement Hangup, Hangup

Key data parameters

key Parameter Description

menuKey

menu key ex: 0-9, #, *

menuAction

Contains action type and action data if needed of each key. Possible actionType are as below. Transfer to Phone. Dial by extension. Dial by name. Go To Menu. Return to previous menu. Replay Menu. Announcement Return. Announcement Hangup. Hangup

Response Body

Response Body will carry Code, corresponding message and unique-id if creation of menu was successful.

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Menu data explained in the table below.

Data Parameter

Data Parameter Description

sid

Unique Menu Id

accountEmail

Unique CPaaS Account that created this particular Record

dateCreated

Timestamp when this Menu was created

dateUpdated

Timestamp when this Menu was updated

name

Name of this Menu

autoAttendantSid

autoattendant sid of this menu

announcementSid

announcement sid assigned to this menu

keys

Keys data explained in key data parameters section.

enterpriseSid

Sid of the enterprise the menu belongs to.

colorCode

Color code of the menu

timeoutSeconds

Timeout duration of the menu

timeoutAction

Time out action type and action data of the menu

uri

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

Response Parameters

Create Menu API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return

Error Code HTTP Status Error Message Description Category

467

409

Enterprise not found

Enterprise for which menu is to be added is not found.

Create Menu, Update Menu

500

409

Announcement not found

Announcement sid is not found

Create menu, Update Menu

490

40

AutoAttendant System not found

AA 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 creation of menu is successful, below is the response returned:

{
    "data": {
        "sid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
        "dateUpdated": "2020-01-27T09:16:13+0000",
        "dateCreated": "2020-01-27T09:16:13+0000",
        "accountEmail": "jane.doe@yourcompany.com",
        "uri": "/autoattendant/menu/search/MN064163a7f3c74f4594d5a8dc55bc4c33",
        "name": "weekendmenu",
        "autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
        "enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
        "keys": [
            {
                "menuKey": "1",
                "menuAction": {
                    "actionType": "ANNOUNCEMENT_HANGUP",
                    "actionData": "AN5067f6f1c8f546dd909df1f50ee9f935"
                }
            }
        ],
        "timeoutSeconds": 1,
        "timeoutAction": {
            "actionType": "ANNOUNCEMENT_HANGUP",
            "actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
        },
        "announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e"
    },
    "code": 200,
    "message": "OK"
}

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

{
    "errorCode": "490",
    "message": "AutoAttendant System not found",
    "data": {
        "sid": "AAa95f0d7ea0ce4863b235523074bf466"
    }
}

Update Operation

Update allows CSP admins to update users, auto attendant systems. AA Admins can update schedule, menus, upload/record announcements.

Update User

This endpoint will be used to update existing users.

  • SUPPORT can make changes to all users irrespective of role

  • CSP_ADMIN can make changes to all users with ENTERPRISE_ADMIN and AA_ADMIN role within its Organisation

  • ENTERPRISE_ADMIN can make changes to other users with ENTERPRISE_ADMIN and AA_ADMIN role 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

enterpriseSid

Optional Enterprise id. If user wants to move user from one enterprise to another, pass the enterpriseId of target Enterprise.

Response Body

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

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

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

User data as explained in the Data Parameter section

Response Parameters

Create User API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return

Error Code HTTP Status Error Message Description Category

499

409

Error in creating subaccount on CPaaS

A user already exists in the DB with provided emailId

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 subaccount belongs to a different Admin account

user id is already subaccount to different 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 User update is successful, below is the response returned:

{
    "data": {
        "sid": "RCSb4ba60022d87407db2134146e3bd4ceb",
        "dateUpdated": "2020-01-29T05:21:28+0000",
        "dateCreated": "2020-01-21T13:35:19+0000",
        "accountEmail": "derick.adams@nuso.cloud",
        "uri": "/autoattendant/user/search/RCSb4ba60022d87407db2134146e3bd4ceb",
        "emailId": "testbg@nuso-ent2.com",
        "status": "SUSPENDED",
        "role": "BG_ADMIN",
        "name": "Ent2 Test BG 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"
    }
}

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
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 code for response

message

Message describing error if error occured or success message

data

Announcement data as explained in the table Data Parameter of Response Body of Create Announcement

Response Parameters

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

Error Code HTTP Status Error Message Description Category

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 type can be:

- Male/Female for Google or Awspolly
- Man/Woman for Acapela
- Only female for Voicerss

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":"cspadmin1@nmorgtest1.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":"female"
   },
   "code":200,
   "message":"OK"
}

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

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

Update Menu

This endpoint will 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

Parameter Description

name

Name of the menu

keys

List of Action Type and action Data for each of the keys explained in key data parameters section.

enterpriseSid

Sid of the enterprise the menu belongs to.

autoAttendantSid

Auto attendant sid the menu belongs to.

colorCode

Color code of the menu.

announcementSid

optional announcement sid for the menu.

timeoutSeconds

timeout duration of the menu

timeoutAction

Action type and action data to perform after timeout. Possible actionType are: Transfer to Phone, Dial by extension, Dial by name, Go To Menu, Return to previous menu, Replay Menu, Announcement Return, Announcement Hangup, Hangup.

Response Body

Response Body will carry Code, corresponding message and menu data if updating the menu was successful.

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

menu data as explained in the Data Parameter section

Response Parameters

Update Menu API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, below are the Error that it can return

Error Code HTTP Status Error Message Description Category

467

409

Enterprise not found

Enterprise for which menu is to be added is not found.

Create Menu, Update Menu

500

409

Announcement not found

Announcement sid is not found

Create menu, Update Menu

490

409

AutoAttendant System not found

AA system Id is not found

Create menu, Update Menu

502

409

Menu not found

Menu sid is not found

Create menu, Update Menu

Example

{
  "name": "weekendmenu",
  "autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
  "enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
  "keys": [
    {
      "menuKey": "1",
      "menuAction": {
        "actionType": "ANNOUNCEMENT_HANGUP",
        "actionData": "AN5067f6f1c8f546dd909df1f50ee9f935"
      }
    }
  ],
  "timeoutSeconds": 1,
  "timeoutAction": {
    "actionType": "ANNOUNCEMENT_HANGUP",
    "actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
  },
  "announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e",
  "colorCode": "#e56052"
}

From the bash terminal you can run the command below:

curl -X PUT \
  https://your_custom_domain.com/autoattendant/menu/ AA9fc6143123d048579f7d5b5d76572e1d \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "weekendmenu",
  "autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
  "enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
  "keys": [
    {
      "menuKey": "1",
      "menuAction": {
        "actionType": "ANNOUNCEMENT_HANGUP",
        "actionData": "AN5067f6f1c8f546dd909df1f50ee9f935"
      }
    }
  ],
  "timeoutSeconds": 1,
  "timeoutAction": {
    "actionType": "ANNOUNCEMENT_HANGUP",
    "actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
  },
  "announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e",
  "colorCode": "#e56052"
}

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

{
  "data": {
    "sid": "MN064163a7f3c74f4594d5a8dc55bc4c33",
    "dateUpdated": "2020-01-29T05:28:11+0000",
    "dateCreated": "2020-01-27T09:16:13+0000",
    "accountEmail": "jane.doe@yourcompany.com",
    "uri": "/autoattendant/menu/search/MN064163a7f3c74f4594d5a8dc55bc4c33",
    "name": "weekendmenu",
    "autoAttendantSid": "AAa95f0d7ea0ce4863b2935523074bf466",
    "enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
    "colorCode": "#e56052",
    "keys": [
      {
        "menuKey": "1",
        "menuAction": {
          "actionType": "ANNOUNCEMENT_HANGUP",
          "actionData": "AN5067f6f1c8f546dd909df1f50ee9f935"
        }
      }
    ],
    "timeoutSeconds": 1,
    "timeoutAction": {
      "actionType": "ANNOUNCEMENT_HANGUP",
      "actionData": "AN42b3d3e952ff47ecba9d487095a2bc4e"
    },
    "announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e"
  },
  "code": 200,
  "message": "OK"
}

If updating the Menu fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "502",
    "message": "Menu not found",
    "data": {
        "sid": "MN064163a7f3c74f4594d5dc55bc4c33",
        "keys": []
    }
}

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

Unique Id of AA system.

name

Name of the Auto attendant system

PhoneNumbers

List of phone numbers to be assigned to this system

Extensions

Extensions to be included

Description

Description of the AA system

enterpriseSid

Optional Enterprise id. If user wants to move AA system from one enterprise to another, pass the enterpriseId of target Enterprise.

Response Body

Response Body will carry Code, corresponding message and AA system data if updating the AA-System was successful.

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

AA system data as explained in the table below
Data Parameters
Data parameters Description

sid

Unique ID generated by system

dateUpdated

Timestamp when this AA system was updated

dateCreated

Timestamp when this Menu was created

accountEmail

CPaaS Account that created this particular Record

uri

Unique URI that you can call to get only this specific AA system

name

Name of the AA system

description

Description of the AA system.

status

Status of the AA system.

aaNumbers

List of phone numbers assigned to the AA system

extensions

List of Extensions assigned to the AA system

enterpriseSid

Sid of the enterprise the AA sytem belongs to.

timeoutSeconds

timeout duration of AA system

timeoutMaxOccurance

Consecutive timeout occurrences are allowed being timeout after which timeout action to perform.

timeoutAction

Action type and Action data if needed to perform after timeout

invalidExtensionMaxOccurance

Consecutive occurrences that the user presses invalidextension 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 Code. In addition, below are the Error that it can return

Error Code HTTP Status Error Message Description Category

467

409

Enterprise not found

Enterprise for which menu is to be added is not found.

Create 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": "derick.adams@nuso.cloud",
        "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 aa system fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "490",
    "message": "AutoAttendant System not found",
    "data": {
        "sid": "AAa95f0d7ea0ce4863b29355074bf466"
    }
}

Update Phone numbers

This endpoint will be used to update an existing phone number. 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 phonenumber

isExtension

if the number being added is an extension. If set to false, the number will be considered an AA number.

enterpriseSid

Optional Enterprise id. If user wants to move phoneNumber from one enterprise to another, pass the enterpriseId of target Enterprise.

extensionSpokenName

extension spoken name of the extension

extension

Extension number of the phone number

Response Body

Response Body will carry Code, corresponding message and data of Phone number if it was successfully updated. HTTP response will be 200 OK.

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

Parameter Description

ode

Sub-error code for response

message

Message describing error if error occurred or success message

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

true if the number being added is an extension. false if the number will be 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 Error as mentioned in Common Response Error Code. In addition below are the Error that it can return

Error Code HTTP Status Error Message Description Category

467

409

Enterprise not found

Enterprise for which 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 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": "derick.adams@nuso.cloud",
        "uri": "/autoattendant/phonenumber/search/PH2996ad9926c9482aa1fe4da7e425a92a",
        "number": "1671331666",
        "isExtension": false,
        "autoAttendantSid": "AA1dff3a6c89a34e12b4c31eb177e82e3f"
    },
    "code": 200,
    "message": "OK"
}

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

{
    "errorCode": "491",
    "message": "PhoneNumber not found",
    "data": {
        "sid": "PH2996ad9926c9482aa14da7e425a92a"
    }
}

Delete Operation

Delete allows CSP admins to delete users, auto attendant systems. AA Admins can delete menus,announcements.

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

Response Body will carry Code, corresponding message and Announcement data if delete was successful.

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Announcement data as explained in the Data Parameter section.

Response Parameters

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

Error Code HTTP Status Error Message Description Category

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

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 deleting 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 deleting of 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"
    }
}

Delete Menu

This endpoint will be 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

Response Body will carry Code, corresponding message and Menu data if deletion of the menu was successful.

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Menu data describe in table Data Parameter section

Response Parameters

Delete Menu API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return

Error Code HTTP Status Error Message Description Category

502

409

menu not found

Menu SID doesn’t exist in the system

Update Menu, Delete Menu, Get Menu

506

409

This menu cannot be deleted as it is being used in a schedule.

menu is being used in a schedule

Delete Menu

509

409

This menu cannot be deleted as it has announcements assigned to it.

announcement is assigned to the menu

Delete Menu

Example

From the bash terminal you can run the command below:

curl -X DELETE \
  https://your_custom_domain.com/autoattendant/menu/ MN73b19aeef8d54073809d21edc8eb760b\
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If deleting 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 deleting the Menu fails, below is the response returned. Exact error code and message will depend on error occurred

{
     "code":465,
     "message":"Menu Not Found”,
           “data”:{
    “sid”:”AA9fc6143123d048579f7d5b5d76572e1d”
  }
}

Read Operation

Read Operations is basically session Detail Record that gives list of PhoneNumbers, Users, Announcement, Schedule, Menu, AA-System.

Get list of Users

This endpoint will be used to get list of user.

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

pageSize

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

Filtering

Following filtering parameters are supported

Query Parameter Description

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

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

email

Sort by email

dateCreated

Sort by created date

Response Body

Response Body will carry Code, corresponding message and data of User 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 Users data as explained in the Data Parameter section.

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

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

nextPageUri

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

uri

Unique URI that you can call to get records

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://your_custom_domain.com/autoattendant/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

Single Enterprise search API allows users to retrieve specific User.

Base Resource URI

https://$DOMAIN

Get Single User Resource URI

/autoattendant/user/search/{userId}

Supported Operations

HTTP GET: Specific User

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

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 command below:

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”:”test@yourcompany.com”,
           “role”: “AA-Admin”,
           “enterpriseSid”: “ EN801e792d86504368a9385314e8c5c4d6”,
        "uri":/autoattendant/user/search/ AAEb6eb071d21124dbab20b095c25f1274f "
} }

Get list of Announcement

This endpoint will be used to delete an existing user.

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

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 table 2.2.5.1 Data Parameter.

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

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

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

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 fails

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

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

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"
}

Get RCML

RCML is a markup language that instructs the core platform on what to do with incoming communication on specific channels - Voice or SMS. For more details please refer to RCML

If you are trying to integrate an Auto Attendant system with 3rd party Application, your Application may want to get access to RCML generated based on in-coming call and Schedule setup for the Number. For example, consider 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 custom Announcement during non working hours. The API’s exposed here can be easily integrated into Number Masking to achieve this feature.

Base Resource URI

https://$DOMAIN

Get Schedule Resource URI

/autoattendant/rcml/search/{phoneNumber}

Supported Operations

HTTP GET: Get RCML setup for given Phone Number. RCML returned will depend on the time of day API call is made. Auto Attendant System will execute the business logic to find the correct System, Schedule and corresponding Menu and then RCML is returned.

Role based Authorization

  • ENTERPRISE_ADMIN users can search for RCML for numbers setup for their own Enterprise only.

  • AA_ADMIN : Doesn’t have access to this API.

Response Body

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

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

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Application data as explained in the Data Parameter below.
Data Parameter
Data Parameter Description

rcml

RCML generated

enterpriseSid

Sid of the enterprise.

autoAttendantSid

Auto Attendant SID which matched for passed number

menuSid

Menu Sid which matched from given autoAttendantSid for Timestamp matching “asOf” parameter

asOf

Timestamp when business logic was executed to find out RCML

timezoneId

Time Zone for which autoAttendantSid is setup.

url

Absolute URL of this RCML API call

Create Application API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return

Error Code HTTP Status Error Message Description Category

491

409

PhoneNumber not found

Phone Number passed is not found

490

409

AutoAttendant System not found

Passed Number doesn’t have any AA system assigned

498

409

No Schedule entry found for auto attendant system

For given “asOf” no Menu is assigned

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://your_custom_domain.com/autoattendant/rcml/search/19960639901 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "rcml": "<Response><Gather action=\"https://your_custom_domain.com/autoattendant/internal/rcml?PreviousMenuSid=MN93d68cb1cd7743708e2b127dbe242d70&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 generation of RCML fails, corresponding error code and message is returned along with HTTP Error Response

{
    "code": "490",
    "message": "AutoAttendant System not found",
    "data": "919960639901"
}

Get list of Menus

This endpoint will be used to get 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 Menu records to return, starting from 0.

pageSize

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

Filtering

Following filtering parameters are supported

Query Parameter Description

name

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

enterpriseSid

Optional Parameter. Only show Menus for this particular enterprise.

startTime

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

endTime

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

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in 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 Menu 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 Menu data as explained in the Data Parameter section.

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

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

nextPageUri

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

uri

Unique URI that you can call to get records

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://your_custom_domain.com/autoattendant/menu/search?autoAttendantSid=AA1dff3a6c89a34e12b4c31eb177e82e3f \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

Below is the response returned:

{
    "data": {
        "result": [
            {
                "sid": "MNb4d808cd188a44aaae33c7aec05aac63",
                "dateUpdated": "2020-01-28T07:00:47+0000",
                "dateCreated": "2020-01-28T07:00:41+0000",
                "accountEmail": "jane.doe@yourcompany.com",
                "uri": "/autoattendant/menu/search/MNb4d808cd188a44aaae33c7aec05aac63",
                "name": "weekdays",
                "autoAttendantSid": "AA1dff3a6c89a34e12b4c31eb177e82e3f",
                "enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
                "colorCode": "#e56052",
                "keys": [
                    {
                        "menuKey": "1",
                        "menuAction": {
                            "actionType": "HANGUP"
                        }
                    }
                ],
                "announcementSid": "AN42b3d3e952ff47ecba9d487095a2bc4e"
            }
        ],
        "pageSize": 10,
        "total": 1,
        "page": 0,
        "numPages": 1,
        "start": 0,
        "end": 0,
        "firstPageUri": "/autoattendant/menu/search/?autoAttendantSid=AA1dff3a6c89a34e12b4c31eb177e82e3f%20&pageSize=10&page=0&%20name=sunday",
        "uri": "/autoattendant/menu/search/?autoAttendantSid=AA1dff3a6c89a34e12b4c31eb177e82e3f%20&pageSize=10&page=0&%20name=sunday"
    },
    "code": 200,
    "message": "OK"
}

Get Single Menu

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

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

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": []
    }
}

Get list of AA-Systems

This endpoint will be used to get 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 AA-System records to return, starting from 0.

pageSize

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

Filtering

Following filtering parameters are supported

Query Parameter Description

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

list of AA system data as explained in the table 3.4.5.1 Data Parameters.

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

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

nextPageUri

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

uri

Unique URI that you can call to get records

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://your_custom_domain.com/autoattendant/system/search?name=welcome \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

Below is the response returned:

{
   "page":0,
   "num_pages":3,
   "page_size":2,
   "total":6,
   "start":0,
   "end":1,
   "uri":"/autoattendant/system/search",
    "first_page_uri":"/ autoattendant/ system /search?pageSize=2&page=0",
   "previous_page_uri":null,
   "next_page_uri":"/ autoattendant/ system /search?pageSize=2&page=1",
   "data":[
{
         “sid":"AA9fc6143123d048579f7d5b5d76572e1d",
         “accountEmail”:”jane.doe@yourcompany.com”,
         "dateCreated":"2019-07-22 09:53:51",
         "dateUpdated":"2019-07-22 09:54:20",
         "name": "Marketing",
         "description": "this is marketing",
          "numbers": [
          "123-123123",
            "12312-412"
  ],
  "extensions": [
"123-123124",
"123-123125"
  ]
}
  ]
"uri":/autoattendant/system/search/AA9fc6143123d048579f7d5b5d76572e1d" }
]
}

Get Single AA-System

Single Menu search API allows users to retrieve specific Menu.

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": "derick.adams@nuso.cloud",
                "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": "derick.adams@nuso.cloud",
                "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"
    }
}

Get list of Phone Numbers

This endpoint will be used to get list of AA-Systems

Base Resource URI

https://$DOMAIN

Get Phone number list Resource URI

/autoattendant/phonenumber/search

Supported Operations

HTTP GET: Get Phonenumber list

Paging

The following paging parameters are supported

Query Parameter Description

page

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

pageSize

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

Filtering

Following filtering parameters are supported

Query Parameter Description

enterpriseSid

Optional Parameter. Only show AA-System for this particular enterprise.

startTime

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

endTime

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

Sorting Information

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

Sort Attributes

Parameter Description

phoneNumber

Sort by phone number

dateCreated

Sort by created date

Response Body

Response Body will carry Code, corresponding message and data of Phone numbers if it was successfully fetched. HTTP response will be 200 OK.

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

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

data of search as explained in table below
Data parameters
Data Parameter Description

result

list of Phone number data as explained in the Data Parameter section.

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

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

nextPageUri

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

uri

Unique URI that you can call to get records

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://your_custom_domain.com/autoattendant/phonenumber/search?enterpriseSid=EE0912eklmda3e13m \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

Below is the response returned:

{
    "data": {
        "result": [
            {
                "sid": "PH440d21f6599d46f5930e995251273429",
                "dateUpdated": "2020-01-21T13:44:44+0000",
                "dateCreated": "2020-01-21T13:37:03+0000",
                "accountEmail": "derick.adams@nuso.cloud",
                "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": "derick.adams@nuso.cloud",
                "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": "derick.adams@nuso.cloud",
        "uri": "/autoattendant/phonenumber/search/PH440d21f6599d46f5930e995251273429",
        "number": "1671331777",
        "isExtension": true,
        "extension": "777"
    },
    "code": 200,
    "message": "OK"
}

Usage Records

Numbers are either main phone numbers or extension phone numbers added for a given enterprise. Usage Records keeps track of Number additions for a given month. For example if a number was added on the 5th day of Month and removed on 25th day of the same month, still that number will be counted under Usage Records for that particular month. However from next month onward it will not be counted as it was deleted. If the number was not deleted, the Usage Records count will include that number for next month and hence its monthly recurring count.

Base Resource URI

https://$DOMAIN

Get Mapping 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.

organisationSid

Mandatory for SUPPORT_ADMIN users. Only include Usage records for Specific Organisation.

Only users with SUPPORT_ADMIN role can pass this parameter. If users with any other role passes this parameter, it’s ignored.

enterpriseSid

Optional. Only include Usage records for specific Enterprise.+

If CSP_ADMIN is calling this API and enterpriseSid is not passed, Usage Records for the entire Organisation is retrieved.

For ENTERPRISE_ADMIN use this parameter is ignored.

Response Body

Response Body will carry Code, corresponding message and data of Usage Records if it was successfully fetched. HTTP response will be 200 OK.

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

Code Description

usageRecords

data of Usage Records as explained in table below

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

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

nextPageUri

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

uri

Unique URI that you can call to get records
Data parameters

Data Parameter

Description

category

The category of Usage Records.

As of today only “phonenumbers” is supported

description

Description of Usage Records

startDate

The first date for which usage is included in this UsageRecord. The date is specified in GMT and formatted as YYYY-MM-DD

endDate

The last date for which usage is included in the UsageRecord. The date is specified in GMT and formatted as YYYY-MM-DD.

asOf

Usage records up to date as of this timestamp, formatted as YYYY-MM-DDTHH:MM:SS+00:00. All timestamps are in GMT

count

The number of usage events, such as the number of calls.

In this case Phone Numbers including Extension Phone Numbers provisioned

countUnit

The units in which count is measured, such as calls for calls or messages for SMS.

In this case Phone Numbers

usage

The amount used to bill usage and measured in units described in usage_unit.

usageUnit

The units in which usage is measured, such as minutes for calls or messages for SMS.

uri

Unique URI that you can call to get records

Example of Numbers Usage

From the bash terminal you can run the command below:

curl -X GET \
  https://your_custom_domain.com/autoattendant/phonenumber/usage/records?startDate=2019-07-01&endDate=2019-07-23
 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned.

{
	"usageRecords":
      [
       {
        "description":"Total Numbers created",
        "enterpriseSid":"ACae6e420f425248d6a26948c17a9e2acf",
        "startDate":"2019-07-01",
        "endDate":"2019-07-23",
        "count":"2123",
       “countUnit”:”numbers”
       "usage": "2123",
       "usageUnit": "numbers",
  "uri":"/autoattendant/phonenumber/usage/records?startDate=2019-07-01&endDate=2019-07-23"
        }
    ],
   "pageSize": 10,
   "total": 1,
   "page": 0,
   "numPages": 1,
   "start": 0,
   "end": 1,
"firstPageUri":"/autoattendant/phonenumber/usage/records?startDate=2019-07-01&endDate=2019-07-23&pageSize=10&page=0",
"uri":"/autoattendant/phonenumber/search/?enterpriseSid=EN838bcdf35f9d421fad3ab516195b873b&pageSize=10&page=0"
}

Request Subresource

The main UsageRecords list resource supports a variety of convenience subresources. In general these take the form:

/autoattendant/phonenumbers/usage/records/{Subresource}

Supported subresources are:

Subresource Description

daily

Return Usage record on a daily basis. If no date filter is passed, last 30 days usage is retrieved.

monthly

Return Usage record on a monthly basis. If no date filter is passed, last 12 months usage is retrieved

yearly

Return Usage record on yearly basis. If no date filter is passed, only this year and previous year usage is retrieved.

today

Return Usage record today.

yesterday

Return Usage record yesterday.

thismonth

Return Usage record this month.

lastmonth

Return Usage record last month.
Example:

From the bash terminal you can run the command below:

curl -X GET \
  https://your_custom_domain.com/autoattendant/phonenumber/usage/records/daily?startDate=2019-07-21&endDate=2019-07-23 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
  "usageRecords":
  [
        {
        "description":"Total Numbers created",
        "enterpriseSid":"ACae6e420f425248d6a26948c17a9e2acf",
        "startDate":"2019-07-21",
        "endDate":"2019-07-21",
       "count":"101",
       "countUnit":"numbers"
       "usage": "101",
       "usageUnit":"numbers",
   "uri":"/autoattendant/phonenumber/usage/records/daily?startDate=2019-07-21&endDate=2019-07-21"
        },
       {
        "description":"Total Numbers Created",
        "enterpriseSid":"ACae6e420f425248d6a26948c17a9e2acf",
        "startDate":"2019-07-22",
        "endDate":"2019-07-22",
        "count":"134",
       "countUnit":"numbers"
       "usage": "134",
       "usageUnit":"numbers",
        "uri":"/autoattendant/phonenumber/usage/records/daily?startDate=2019-07-22&endDate=2019-07-23"
        }
   ],
   "pageSize": 10,
   "total": 1,
   "page": 0,
   "numPages": 1,
   "start": 0,
   "end": 1,
"firstPageUri":"/autoattendant/phonenumber/usage/records/daily?startDate=2019-07-21&endDate=2019-07-23&pageSize=10&page=0",
"uri":"/autoattendant/phonenumber/usage/recordsdaily?startDate=2019-07-21&endDate=2019-07-23&pageSize=10&page=0"

}

In the above example if you don’t pass “startDate” and “endDate” parameters, 30 records will be shown.