Voice API Introduction
Welcome the Voxtelesys Voice REST API. This API offers an easy, secure solution to create and control voice calls. If at any point you have questions or would like more information please reach out to support.
Base URL
All URLs referenced in this document have the following base:
https://voiceapi.voxtelesys.net/api/v1
This API is served over HTTPS to ensure data privacy. Unencrypted HTTP is not supported.
Number Formatting
This API uses E.164 number formatting. E.164 is an international standard for the PSTN that ensures number uniqueness. E.164 numbers are formatted [country code][subscriber number] and can have a maximum of 15 digits.
Examples:
E.164 Format | Country | Country Code | Subscriber Number |
---|---|---|---|
17019299797 | US | 1 | 7019299797 |
Authentication
Request:
curl -X GET \
--url https://voiceapi.voxtelesys.net/api/v1/calls \
--header 'authorization: Bearer YOUR_API_KEY'
The Voxtelesys Voice API uses API keys to authenticate requests. You can view and manage your API keys via the Voxtelesys Portal. Be sure to keep your API keys secure, and do not share in publicly accessible areas such as GitHub, client-side code, etc.
To use your API key, simply pass the key in the Authorization
header:
Authorization: Bearer YOUR_API_KEY
Calls
The calls resource gives you the ability to create a new outbound call and control ongoing calls. You are able to provide the VoxXML for new calls to execute and, likewise, edit the VoxXML of existing calls. The provided VoxXML can be as simple as a single-line command, or as complex as a fully-featured IVR!
List calls
Request:
curl --request GET \
--header 'Authorization: Bearer YOUR_API_KEY' \
--url 'https://voiceapi.voxtelesys.net/api/v1/calls'
Response:
{
"page": 1,
"page_size": 50,
"page_count": 1,
"count": 1,
"results": [
{
"id": "f5157dfe-0629-e358-6b08-8fbea78ab4bd",
"to": "15556667777",
"from": "15556668888",
"status": "answered",
"created_time": "2021-07-27T19:02:19.979Z",
"modified_time": "2021-07-27T19:02:20.544Z",
"answer_time": "2021-07-27T19:02:20.474Z",
"hangup_time": "2021-07-27T17:55:52.936Z",
}
]
}
Endpoint for retrieving a list of calls, both active and complete. Calls are accessible for 7 days after completion.
HTTP Request
GET /calls
Query Parameters
Param | Type | Description | Example |
---|---|---|---|
page | integer |
page number starting from 1; default 1 | 1 |
page_size | integer |
number of records to retrieve per page; default 25 | 50 |
HTTP Response
The response will include paginated information about all calls, both active and complete, in a JSON format.
The following fields may be contained within the response, and are omitted when they are not applicable:
Field | Type | Description | Example |
---|---|---|---|
page | number | Which page number of the results is currently displayed | "page": 2 |
page_size | number | The maximum number of results returned with this query | "page_size": 50 |
page_count | number | The number of pages of results that are available | "page_count": 3 |
count | number | The number of results that are available | "count": 2 |
results | array | Calls currently in the system | |
results.id | string | UUID to identify the individual call with | "id": "f5157dfe-0629-e358-6b08-8fbea78ab4b" |
results.to | string | E.164 formatted number that call was addressed to | "to": "15554448899" |
results.from | string | E.164 formatted number that call was made from | "from": "15553338877" |
results.status | string | Current state of the call | "status": "failed" |
results.created_time | string | Timestamp of when the call entered the system | "created_time": "2021-07-27T19:02:19.979Z" |
results.modified_time | string | Timestamp of when the call information was most recently changed | "modified_time": "2021-07-27T19:02:19.979Z" |
results.answer_time | string | Timestamp of when the call was answered | "answer_time": "2021-07-27T19:02:19.979Z" |
results.hangup_time | string | Timestamp of when the call was ended | "hangup_time": "2021-07-27T19:02:19.979Z" |
results.error | object | Error object describing why the call failed | |
results.error.code | number | Code to describe the type of error that occurred | "code": 5105 |
results.error.description | string | Description of the error that occurred | "description": "internal server error" |
results.error.time | string | Timestamp of when the error was recorded | "time": "2021-09-21T14:14:17.000Z" |
Call Status
Calls can be in several different statuses. The meaning of the status can differ between inbound and outbound calls.
Some statuses are "final": once the call has reached a final status, it should not change.
Status | Inbound calls | Outbound calls | Is final? |
---|---|---|---|
queued | N/A | Call has been submitted to the API | No |
processing | Call has been recognized by the API | Call has been recognized by the API | No |
ringing | N/A | Call is ringing the destination number | No |
answered | Call has been answered by the API | Call has been answered by the destination number | No |
complete | Call was successfully ended after being answered | Call was successfully ended after being answered | Yes |
busy | N/A | Call was not answered because the destination is busy | Yes |
failed | Call encountered an error and was aborted | Call encountered an error and was aborted | Yes |
no_answer | N/A | Call was not answered by the destination number | Yes |
Create a call
Request:
curl --request POST
--header 'Authorization: Bearer APIKEY'
--header 'Content-Type: application/json'
--data '{ "to":"15556667777", "from":"15556668888", "voxXML":"<Response><Say voice=\"Joanna\" language=\"en-US\">Hello!</Say></Response>" }'
--url 'https://voiceapi.voxtelesys.net/api/v1/calls'
Response:
{
"id": "8d658f67-3879-4938-bbad-863878bd5341",
"to": "15556667777",
"from": "15556668888",
"status": "queued",
"created_time": "2021-07-28T12:59:26.145Z",
"modified_time": "2021-07-28T12:59:26.145Z"
}
Endpoint for creating a new outgoing call. The created call will execute the provided VoxXML upon answer.
HTTP Request
POST /calls
HTTP Body
The body of the request should be JSON with the following data:
Field | Type | Required | Description | Example |
---|---|---|---|---|
to | string | yes | The number to dial | 15556667777 |
from | string | yes | The number to originate the call from | 15556668888 |
voxXML | string | yes | VoxXML to execute after connecting | <Say voice='Joanna' language='en-US'>Hello!</Say> |
For more information on the VoxXML
field, see the VoxXML section of the documentation.
HTTP Response
The response will include information about the newly created call.
Modify a call
Request:
curl --request POST
--header 'Authorization: Bearer APIKEY'
--header 'Content-Type: application/json'
--data '{ "voxXML":"<Response><Hangup/></Response>" }'
--url 'https://voiceapi.voxtelesys.net/api/v1/calls/8d658f67-3879-4938-bbad-863878bd5341'
Endpoint for updating an ongoing call. The provided VoxXML will interrupt and replace the existing VoxXML.
HTTP Request
POST /calls/{id}
PATCH /calls/{id}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of call | 8d658f67-3879-4938-bbad-863878bd5341 |
HTTP Body
The body of the request should be JSON with a single field:
Field | Type | Required | Description | Example |
---|---|---|---|---|
voxXML | string | yes | VoxXML to execute | <Say voice='Joanna' language='en-US'>Hello!</Say> |
For more information on the VoxXML
field, see the VoxXML section of the documentation.
HTTP Response
On success, an empty response with a 204
status code is returned.
Delete a call
Request:
curl --request DELETE
--header 'Authorization: Bearer APIKEY'
--url 'https://voiceapi.voxtelesys.net/api/v1/calls/b9d7599c-b63c-48b7-e608-e5bc53b23c57'
Endpoint for deleting a call. If the call is ongoing, then the call will be immediately hung up.
HTTP Request
DELETE /calls/{id}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of call | 8d658f67-3879-4938-bbad-863878bd5341 |
HTTP Response
On success, an empty response with a 204
status code is returned.
Conferences
Conferences represent individual conference rooms, referenced by an ID and a name. Calls can be sent to conference rooms via the conference room's name. Furthermore, VoxXML can be used to take action on conference rooms, such as playing audio or text-to-speech.
There is no endpoint for creating a conference, as conferences are created automatically when one or more calls are sent to the respective conference room.
List conferences
Request:
curl --request GET \
--header 'Authorization: Bearer YOUR_API_KEY' \
--url 'https://voiceapi.voxtelesys.net/api/v1/conferences'
Response:
{
"page": 1,
"page_size": 50,
"page_count": 1,
"count": 1,
"results": [
{
"id": "c0904ce2-9081-4fa1-4ade-8278d347fcac",
"name": "room1",
"status": "complete",
"created_time": "2021-07-27T13:59:27.344Z",
"modified_time": "2021-07-27T14:00:26.619Z"
}
]
}
This endpoint retrieves a list of conferences.
HTTP Request
GET /conferences
Query Parameters
Param | Type | Description | Example |
---|---|---|---|
page | integer |
page number starting from 1; default 1 | 1 |
page_size | integer |
number of records to retrieve per page; default 25 | 50 |
HTTP Response
The response will include paginated information about all conferences, both active and complete, in a JSON format.
The following fields may be contained within the response, and are omitted when they are not applicable:
Field | Type | Description | Example |
---|---|---|---|
page | number | Which page number of the results is currently displayed | "page": 2 |
page_size | number | The maximum number of results returned with this query | "page_size": 50 |
page_count | number | The number of pages of results that are available | "page_count": 3 |
count | number | The number of results that are available | "count": 2 |
results | array | Conferences currently in the system | |
results.id | string | UUID to identify the individual conference with | "id": "f5157dfe-0629-e358-6b08-8fbea78ab4b" |
results.name | string | The name assigned to the conference | "name": "room3" |
results.status | string | Current state of the conference | "status": "complete" |
results.created_time | string | Timestamp of when the conference's first participant joined | "created_time": "2021-07-27T19:02:19.979Z" |
results.modified_time | string | Timestamp of when the conference information was most recently changed | "modified_time": "2021-07-27T19:02:19.979Z" |
results.error | object | Error object describing why the conference failed | |
results.error.code | number | Code to describe the type of error that occurred | "code": 5105 |
results.error.description | string | Description of the error that occurred | "description": "internal server error" |
results.error.time | string | Timestamp of when the error was recorded | "time": "2021-09-21T14:14:17.000Z" |
Conference Status
Conferences can be in several different statuses.
Some statuses are "final": once the conference has reached a final status, it should not change.
Status | Meaning | Is final? |
---|---|---|
queued | Conference has been submitted to the API | No |
in_progress | Conference exists and has one or more participants | No |
complete | Conference has ended | Yes |
conf_failed | Conference encountered an error and was aborted | Yes |
Modify a conference
Request:
curl --request POST
--header 'Authorization: Bearer APIKEY'
--header 'Content-Type: application/json'
--data '{ "voxXML":"<Response><Hangup/></Response>" }'
--url 'https://voiceapi.voxtelesys.net/api/v1/conferences/c0904ce2-9081-4fa1-4ade-8278d347fcac'
Endpoint for updating an ongoing conference. The provided VoxXML will interrupt and replace the existing VoxXML.
HTTP Request
POST /conferences/{id}
PATCH /conferences/{id}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of conference | 8d658f67-3879-4938-bbad-863878bd5341 |
HTTP Body
The body of the request should be JSON with the following data:
Field | Type | Required | Description | Example |
---|---|---|---|---|
voxXML | string | yes | VoxXML to execute | <Say voice='Joanna' language='en-US'>Hello!</Say> |
For more information on the VoxXML
field, see the VoxXML section of the documentation.
HTTP Response
On success, an empty response with a 204
status code is returned.
Delete a conference
Request:
curl --request DELETE
--header 'Authorization: Bearer APIKEY'
--url 'https://voiceapi.voxtelesys.net/api/v1/conferences/b9d7599c-b63c-48b7-e608-e5bc53b23c57'
Endpoint for deleting a conference room. If the conference is ongoing, all participant calls will be immediately hung up.
HTTP Request
DELETE /conferences/{id}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of conference | 8d658f67-3879-4938-bbad-863878bd5341 |
HTTP Response
On success, an empty response with a 204
status code is returned.
Conference participants
Conference Participants represent individual members in a conference room. Members are associated to their conference room by the room's ID. VoxXML can be used to take action on participants, such as playing audio to a specific participant, using text-to-speech, or taking that member out of the conference.
List conference participants
Request:
curl --request GET \
--header 'Authorization: Bearer YOUR_API_KEY' \
--url 'https://voiceapi.voxtelesys.net/api/v1/conferences/b9d7599c-b63c-48b7-e608-e5bc53b23c57/participants'
Response:
{
"page": 1,
"page_size": 50,
"page_count": 1,
"count": 1,
"results": [
{
"id": "70fe317e-6bf7-484c-b964-dbed00d09684",
"label": "person1",
"created_time": "2021-08-02T16:43:43.576Z",
"modified_time": "2021-08-02T16:43:43.678Z",
"joined_time": "2021-08-02T16:43:43.576Z",
"conference_id": "0be37c87-c204-8832-1058-3119a606be89"
}
]
}
This endpoint retrieves a list of conference participants.
HTTP Request
GET /conferences/{conf_id}/participants
Query Parameters
Param | Type | Description | Example |
---|---|---|---|
page | integer |
page number starting from 1; default 1 | 1 |
page_size | integer |
number of records to retrieve per page; default 25 | 50 |
conf_id | string |
ID of conference | 8d658f67-3879-4938-bbad-863878bd5341 |
HTTP Response
The response will include paginated information about all participants of that particular conference, in a JSON format. Participants will be removed from this list as they leave the conference.
The following fields may be contained within the response, and are omitted when they are not applicable:
Field | Type | Description | Example |
---|---|---|---|
page | number | Which page number of the results is currently displayed | "page": 2 |
page_size | number | The maximum number of results returned with this query | "page_size": 50 |
page_count | number | The number of pages of results that are available | "page_count": 3 |
count | number | The number of results that are available | "count": 2 |
results | array | Participants in the selected conference | |
results.id | string | UUID to identify the individual participant with | "id": "f5157dfe-0629-e358-6b08-8fbea78ab4b" |
results.label | string | Text label assigned to this participant | "label": "sam" |
results.created_time | string | Timestamp of when the participant was created in the system | "created_time": "2021-07-27T19:02:19.979Z" |
results.modified_time | string | Timestamp of when the participant information was most recently changed | "modified_time": "2021-07-27T19:02:19.979Z" |
results.joined_time | string | Timestamp of when the participant joined the conference | "joined_time": "2021-07-27T19:02:19.979Z" |
results.conference_id | string | UUID of the conference this individual is participating in | "conference_id": "f5157dfe-0629-e358-6b08-8fbea78ab4b" |
results.error | object | Error object describing why the participant processing failed | |
results.error.code | number | Code to describe the type of error that occurred | "code": 5105 |
results.error.description | string | Description of the error that occurred | "description": "internal server error" |
results.error.time | string | Timestamp of when the error was recorded | "time": "2021-09-21T14:14:17.000Z" |
Modify a conference participant
Request:
curl --request POST
--header 'Authorization: Bearer APIKEY'
--header 'Content-Type: application/json'
--data '{ "xml":"<Response><Hangup/></Response>" }'
--url 'https://voiceapi.voxtelesys.net/api/v1/conferences/c0904ce2-9081-4fa1-4ade-8278d347fcac/participants/0be37c87-c204-8832-1058-3119a606be89'
Used for sending new VoxXML commands to an existing conference participant.
HTTP Request
POST /conferences/{conf_id}/participants/{id}
PATCH /conferences/{conf_id}/participants/{id}
Query Parameters
Param | Type | Description | Example |
---|---|---|---|
conf_id | string |
ID of conference | 8d658f67-3879-4938-bbad-863878bd5341 |
id | string |
ID of conference participant | 8d658f67-3879-4938-bbad-863878bd5341 |
HTTP Body
The body of the request should be JSON with the following data:
Field | Type | Required | Description | Example |
---|---|---|---|---|
voxXML | string | yes | VoxXML to execute | <Say voice='Joanna' language='en-US'>Hello!</Say> |
For more information on the VoxXML
field, see the VoxXML section of the documentation.
HTTP Response
On success, an empty response with a 204
status code is returned.
VoxXML
Calls, conferences, and conference participants are all controlled through VoxXML. VoxXML provides an action or a series of actions to be taken by a call, a conference, or a participant of a conference. VoxXML can be single actions for the call to take, or can be multiple actions chained together. Entire call flows or IVRs can be set up using VoxXML.
Example of VoxXML:
<Response>
<Say>This is a test IVR</Say>
<Number>15556667788</Number>
<Hangup/>
</Response>
Each action to be taken can be referred to as a "command". All commands to be used by the API must be enclosed in <Response>
tags, or else the commands will be rejected by the API.
For people familiar with XML, <Response>
is the root element of the XML document.
Conference
The Conference block is used to send a call to a conference.
Supported Resources
- Calls
Example:
<Conference muted='false' startConferenceOnEnter='false' beep='true'>room1</Conference>
Content
Must contain the name of the conference to connect to. Valid names are alphanumeric strings.
Attributes
Attribute | Accepts | Default | Required | Description | Example |
---|---|---|---|---|---|
muted | true ,false |
false |
no | Sets whether this call will already be muted when entering the conference. | muted='true' |
beep | true ,false ,onEnter ,onExit |
true |
no | Sets whether a beeping noise will be played into the conference when the participant enters or leaves. | beep='onExit' |
startConferenceOnEnter | true ,false |
true |
no | Sets whether the conference, if not yet started, will start once this caller enters. | startConferenceOnEnter='true' |
endConferenceOnExit | true ,false |
false |
no | Sets whether the conference will automatically end once this caller exits. | endConferenceOnExit='false' |
participantLabel | Any string composed of a-z, 0-9 | Empty string | no | Sets a useful identifier for finding the participant later. | participantLabel='bob' |
statusCallbackEvent | List of supported keywords | Empty string | no | Sets the events that callbacks should be initiated on. | statusCallbackEvent='start end dtmf' |
statusCallback | URL | Empty string | no | Sets the URL that callbacks should be sent to. | statusCallback='https://example.com/callback' |
statusCallbackMethod | GET or POST |
POST |
no | Sets what HTTP method should be used for sending callbacks. | statusCallbackMethod='GET' |
Dial
The Dial block is used to call another resource.
Supported Resources
- Calls
Example:
<Dial>
<Number>15556667777</Number>
<Number>15556668888</Number>
<Number>15556668888</Number>
</Dial>
Content
The Dial block can be used several ways. The Dial block can contain one of the following:
- A single, literal number to dial
- A set of Number blocks to dial in parallel (first number to answer wins; others are canceled)
- A single Conference block to connect to.
Attributes
Attribute | Accepts | Default | Required | Description | Example |
---|---|---|---|---|---|
statusCallbackEvent | List of supported keywords | Empty string | no | Sets the events that callbacks should be initiated on. | statusCallbackEvent='ringing answered' |
statusCallback | URL | Empty string | no | Sets the URL that callbacks should be sent to. | statusCallback='https://example.com/callback' |
statusCallbackMethod | GET or POST |
POST |
no | Sets what HTTP method should be used for sending callbacks. | statusCallbackMethod='GET' |
callerId | Any string composed of a-z, 0-9 | The caller's phone number/extension | no | Sets the outgoing caller ID | 15556667777 |
Gather
The Gather block is used for collecting input during a call. The collected input will be stored in the $GATHER
variable.
Supported Resources
- Calls
Example:
<Gather input='dtmf speech' loop='1' repeatDelay='7s' numDigits='4' timeout='10'>
<Say voice='Joanna' language='en-US'>Please enter conference ID</Say>
</Gather>
Content
VoxXML to be executed while waiting for the user's input. Acceptable nouns include Say
and Play
.
Attributes
Attribute | Accepts | Default | Required | Description | Example |
---|---|---|---|---|---|
repeatDelay | Integer from 0 to 60 |
0 |
no | Specifies delay (in seconds) before the contained VoxXML is repeated. | repeatDelay='1' |
timeout | Integer | 30 |
no | Specifies how long (in seconds) the Gather statement will wait for complete input before exiting early. Time values greater than 60 seconds will be set to 60 seconds. |
timeout='10' |
speechTimeout | Integer | 30 |
no | Specifies how long (in seconds) the Gather statement will wait for silence when taking speech input. Time values greater than 60 seconds will be set to 60 seconds. |
speechTimeout='30' |
loop | Integer values greater than or equal to zero | 1 |
no | Specifies the number of times the VoxXML specified in the Gather block will be played. Setting to 0 will cause to loop indefinitely. |
loop='5' |
numDigits | Integer values greater than zero | 1 |
no | Specifies the number of digits the user must enter before input is considered complete. | numDigits='4' |
finishOnKey | 0 -9 , # , * , or an empty value |
# |
no | When any of the specified characters is encountered (DTMF), input will stop and the Gather statement will be done. | finishOnKey='0#*' |
language | en-US , en-GB , es-US , fr-CA , fr-FR , en-AU , it-IT , de-DE , pt-BR , ja-JP , ko-KR , zh-CN |
en-US |
no | Language code to indicate the input language. | language='en-US' |
input | dtmf ,speech ,dtmf speech |
dtmf |
no | Specifies which method(s) will be used to get input. | input='dtmf' |
statusCallbackEvent | List of supported keywords | Empty string | no | Sets the events that callbacks should be initiated on. | statusCallbackEvent='partialResult fullResult' |
statusCallback | URL | Empty string | no | Sets the URL that callbacks should be sent to. | statusCallback='https://example.com/callback' |
statusCallbackMethod | GET or POST |
POST |
no | Sets what HTTP method should be used for sending callbacks. | statusCallbackMethod='GET' |
Hangup
The Hangup block is used to end a call or conference.
Supported Resources
- Calls
- Conferences
- Participants
Example:
<Hangup/>
Content
None
Attributes
None
If
The If block is used to conditionally execute a piece of XML. If the comparison is met, then the XML is executed. Otherwise, it is skipped.
Supported Resources
- Calls
- Conferences
- Participants
Example:
<If variable='$GATHER' test='EQUAL' value='1|english'>
<Say voice='Joanna' language='en-US'>You have chosen english.</Say>
</If>
Content
VoxXML to be conditionally executed.
Attributes
Attribute | Accepts | Default | Required | Description | Example |
---|---|---|---|---|---|
variable | Any variables used by the scripting language | none | yes | Usually used with the $GATHER variable |
variable='$GATHER' |
test | EQUAL ,NOTEQUAL |
none | yes | The type of comparison to make | test='NOTEQUAL' |
value | 0 -9 ,a -z |
none | yes | The value to compare the variable against. | value='room1' |
Note that multiple values can be compared against, using the |
to separate them: value='room1|1'
.
Number
The Number block dials a phone number.
The Number block can also be used inside a Dial
block to dial multiple numbers at once.
Supported Resources
- Calls
Example:
<Number>15556667777</Number>
Content
A phone number in E.164 format (15556667777).
Attributes
Attribute | Accepts | Default | Required | Description | Example |
---|---|---|---|---|---|
statusCallbackEvent | List of supported keywords | Empty string | no | Sets the events that callbacks should be initiated on. | statusCallbackEvent='ringing answered' |
statusCallback | URL | Empty string | no | Sets the URL that callbacks should be sent to. | statusCallback='https://example.com/callback' |
statusCallbackMethod | GET or POST |
POST |
no | Sets what HTTP method should be used for sending callbacks. | statusCallbackMethod='GET' |
callerId | Any string composed of a-z, 0-9 | The caller's phone number/extension | no | Sets the outgoing caller ID | 15556667777 |
Pause
The Pause block pauses execution of the script for a given length of time.
Supported Resources
- Calls
- Conferences
- Participants
Example:
<Pause length='10'/>
Content
None
Attributes
Attribute | Accepts | Default | Required | Description | Example |
---|---|---|---|---|---|
length | Integer from 1 to 60 |
1 |
no | Specifies duration (in seconds) execution should be paused for. | length=10 |
Play
The Play block plays an audio file for a call, conference, or a participant of a conference. The audio file must be provided via either HTTP or HTTPS.
Supported Resources
- Calls
- Conferences
- Participants
Example:
<Play>https://example.com/myfile.mp3</Play>
Content
An HTTP or HTTPS URL leading to a valid audio file. The file may be cached locally.
If any particular caching is desired, set the Cache-Control HTTP header either using no-cache
or no-store
(to disable all caching) or set the max-age
value appropriately.
These values should be respected, but no guarantees are made. If no cache settings are given, files are cached for up to an hour.
Attributes
Attribute | Accepts | Default | Required | Description | Example |
---|---|---|---|---|---|
loop | Integers greater than or equal to zero. | 1 |
no | Specifies the number of times the audio file will be played. Set to 0 to loop indefinitely. |
loop='3' |
repeatDelay | Integer 0 to 60 |
0 |
no | Specifies delay (in seconds) that will occur before the file is played again or until the next piece of VoxXML is run. | repeatDelay='3' |
Redirect
The Redirect block fetches a piece of external VoxXML and executes its contents. When the fetched VoxXML is done being executed, the XML processing will exit; that is, statements after a Redirect block will not be run. If the Redirect block fails to fetch the VoxXML, then it will continue processing the existing VoxXML normally.
Supported Resources
- Calls
- Conferences
- Participants
Example:
<Redirect method='GET'>https://example.com/myscript.xml</Redirect>
Content
An HTTP or HTTPS URL pointing to a valid VoxXML segment to be executed. The MIME type must be set to one of text/xml
, application/xml
, or text/plain
.
Attributes
Attribute | Accepts | Default | Required | Description | Example |
---|---|---|---|---|---|
method | GET ,POST |
POST |
no | Specifies whether an HTTP GET or POST request should be used to fetch the data. | method='GET' |
Reject
The Reject block rejects a call without answering.
A Reject block can only be used as the first piece of VoxXML to be executed. A Reject block will have no effect if used after a call has been answered or after a call has executed other pieces of VoxXML.
Reject is most commonly used as a reply to incoming calls fetching their XML via URL. See Callbacks: API for more information.
Supported Resources
- Calls
Example:
<Reject/>
Content
None
Attributes
None
Say
The Say block uses Amazon Polly to auto-generate text-to-speech.
Supported Resources
- Calls
- Conferences
- Participants
Example
<Say voice='Joanna' language='en-US'>Thank you.</Say>
<Say voice='Joanna' language='en-US' separateNumbers='true'>You entered the numbers $GATHER</Say>
Content
A piece of text to be read to the call, conference, or conference participant. If the $GATHER variable has content to be read back to the user, it can be used along with regular text.
Attributes
Attribute | Accepts | Default | Required | Description | Example |
---|---|---|---|---|---|
loop | Integers greater than or equal to zero | 1 |
no | Specifies the number of times the audio will be played. Set to 0 to loop indefinitely. |
loop='3' |
repeatDelay | Integer 0 to 60 |
0 |
no | Specifies delay (in seconds) before the file is played again or until the next piece of VoxXML is executed. | repeatDelay='10' |
voice | Name of a voice | Joanna |
no | Specifies the "voice" to use when speaking, as provided by Amazon Polly. To see what language/voice pairs are available, see the Amazon Polly informational page. "Standard" voices are currently supported. | voice='Kendra' |
language | Language code | None | no | Selects what language the text is in, if using a voice that supports multiple languages. If no language code is selected, the default language for the chosen voice will be used. To see what language/voice pairs are available, see the Amazon Polly informational page. "Standard" voices are currently supported. | language='fr-FR' |
separateNumbers | true ,false |
false |
no | Specifies whether multi-digit sequences should be said as individual numbers. | separateNumbers='true' |
The number 1824 with separateNumbers
set to false
would be pronounced "one thousand eight hundred twenty-four". With separateNumbers
set to true
, it would be pronounced "one eight two four". This can be useful to for reading out phone or ID numbers.
SetMute
The SetMute block sets a conference or a participant in a conference to be either muted or not muted.
Supported Resources
- Conferences
- Participants
Example:
<SetMute muted='false'/>
Content
None
Attributes
Attribute | Accepts | Default | Required | Description | Example |
---|---|---|---|---|---|
muted | true ,false |
false |
no | Specifies whether the participant or conference should be muted or not muted. | muted='true' |
VoxXML Examples
Simple IVR
Simple IVR:
<Response>
<Say voice='Joanna' language='en-US'>Thank you for calling</Say>
<Gather input='dtmf' loop='3' repeatDelay='5' numDigits='1' timeout='60'>
<Say voice='Joanna' language='en-US'>For United States support, press 1.</Say>
<Say voice='Joanna' language='en-US'>For Canadian support, press 2.</Say>
</Gather>
<If variable='$GATHER' test='EQUAL' value='2'>
<Say voice='Joanna' language='en-US' loop='1' repeatDelay='3'>Dialing Canadian support. Please wait.</Say>
<Number>15556668888</Number>
<Say voice='Joanna' language='en-US' loop='1'>Call has ended. Goodbye.</Say>
<Hangup/>
</If>
<Say voice='Joanna' language='en-US' loop='1' repeatDelay='3'>Dialing United States support. Please wait.</Say>
<Number>15556667777</Number>
<Say voice='Joanna' language='en-US' loop='1'>Call has ended. Goodbye.</Say>
<Hangup/>
</Response>
This VoxXML sample shows how a business could redirect incoming calls to the appropriate support office.
In this script:
- The caller is greeted using a
Say
block - A
Gather
block is used to retrieve one digit of DTMF from the caller- Meanwhile,
Say
blocks read the menu options to the caller
- Meanwhile,
- If the digit
2
is entered, Canadian support is dialed using aNumber
block - If any other digits or no digit at all is pressed, US support is dialed
Complex IVR
Complex IVR:
<Response>
<Say voice='Joanna' language='en-US' loop='1'>Hello, and welcome.</Say>
<Gather input='dtmf' loop='3' repeatDelay='5' numDigits='1' timeout='60'>
<Say voice='Joanna' language='en-US'>For support, press one.</Say>
<Say voice='Joanna' language='en-US'>To join a conference, press two.</Say>
<Say voice='Joanna' language='en-US'>For updates on hours of operation, press three.</Say>
</Gather>
<If variable='$GATHER' test='EQUAL' value='1'>
<Say voice='Joanna' language='en-US' loop='1' repeatDelay='3'>Dialing support. Please wait.</Say>
<Number>15556667777</Number>
<Say voice='Joanna' language='en-US' loop='1'>Call has ended. Goodbye.</Say>
<Hangup/>
</If>
<If variable='$GATHER' test='EQUAL' value='2'>
<Gather input='dtmf' loop='1' repeatDelay='5' numDigits='4' timeout='30'>
<Say voice='Joanna' language='en-US'>Please enter conference ID</Say>
</Gather>
<If variable='$GATHER' test='EQUAL' value='2233'>
<Gather input='dtmf speech' loop='1' repeatDelay='7' numDigits='4' timeout='10'>
<Say voice='Joanna' language='en-US'>Please enter pin</Say>
</Gather>
<If variable='$GATHER' test='EQUAL' value='1111'>
<Conference muted='false' startConferenceOnEnter='false' beep='true'>2233</Conference>
<Say voice='Joanna' language='en-US'>Conference has ended. Thank you</Say>
<Hangup/>
</If>
<If variable='$GATHER' test='EQUAL' value='9999'>
<Conference startConferenceOnEnter='true' endConferenceOnExit='true' muted='false' beep='true'>2233</Conference>
<Say voice='Joanna' language='en-US'>Conference has ended. Thank you</Say>
<Hangup/>
</If>
<Say voice='Joanna' language='en-US'>Invalid pin. Goodbye.</Say>
<Hangup/>
</If>
<If variable='$GATHER' test='EQUAL' value='3344'>
<Gather input='dtmf speech' loop='1' repeatDelay='7' numDigits='4' timeout='10'>
<Say voice='Joanna' language='en-US'>Please enter pin</Say>
</Gather>
<If variable='$GATHER' test='EQUAL' value='1111'>
<Conference muted='false' startConferenceOnEnter='false' beep='true'>3344</Conference>
<Say voice='Joanna' language='en-US'>Conference has ended. Thank you</Say>
<Hangup/>
</If>
<If variable='$GATHER' test='EQUAL' value='9999'>
<Conference startConferenceOnEnter='true' endConferenceOnExit='true' muted='false' beep='true'>3344</Conference>
<Say voice='Joanna' language='en-US'>Conference has ended. Thank you</Say>
<Hangup/>
</If>
<Say voice='Joanna' language='en-US'>Invalid pin. Goodbye.</Say>
<Hangup/>
</If>
<Say voice='Joanna' language='en-US'>Invalid conference. Goodbye.</Say>
<Hangup/>
</If>
<If variable='$GATHER' test='EQUAL' value='3'>
<Play>https://example.com/hours-of-operation.mp3</Play>
<Hangup/>
</If>
<Say voice='Joanna' language='en-US'>No option selected. Goodbye.</Say>
</Response>
This VoxXML sample shows how a business could use the Voxtelesys API to handle incoming calls with a more complex IVR flow.
Several features are demonstrated:
- Caller is greeted.
- DTMF is used to either send the caller to support, let them join a conference, or give them an update on hours of operation.
- If the user chooses support, a
Number
block is used to dial the direct support number. - If the user chooses to join a conference, they are asked for a conference ID and a PIN.
- The PIN either starts the conference immediately or mutes them until the conference begins.
- If the user chooses to hear hours of operation, a
Play
block is used to retrieve and play an MP3 file with the business's hours recorded.
Callbacks
Callbacks (also known as webhooks) allow software to receive notifications from the Voxtelesys Voice API when certain events happen. These notifications are sent as HTTP GET or POST requests to a URL of your choice. For example, the API could be configured to send a POST request to https://api.yourwebsite.com/conference_state whenever a person enters or leaves a conference. This would allow your program to take action, such as updating an information page or announcing something to the rest of the conference (using the voice API).
Callbacks using POST requests will send the event data as a JSON body, and callbacks sent using GET requests will send the event data URL-encoded query parameters in the URL.
Most callbacks are enabled on a per-command basis using VoxXML. The exception are api-type callbacks, which are explained separately below.
VoxXML callbacks can only be specified on Call resources - if setting callbacks for a conference, the first participant to enter the conference will determine what callbacks are used for the remainder of that conference.
Information on callbacks are below.
API
Events of type "api" are events that do not originate from any VoxXML. They occur based on settings in the Voxtelesys Portal.
incomingCall
If an API-enabled number is set to use a URL as its source of VoxXML, then each incoming call will generate a single POST request to the given URL.
The POST request will contain information about the call, and will expect to be given valid VoxXML for the incoming call to execute.
If the <Reject>
command is sent, the call will be rejected without answering.
JSON from POST request:
{
"type": "api",
"event": "incoming_call",
"time": "2021-08-30T20:49:35Z",
"call_id": "889317ac-6864-4d14-bbf7-d0779786b006",
"to": "15556667777",
"from": "15556668888"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be api |
Says what initated this event | api |
event | Will always be incoming_call |
Says what VoxXML event this is | incoming_call |
call_id | An alphanumeric UUID | The UUID of this call for the Voice API | 8d658f67-3879-4938-bbad-863878bd5341 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-01-05T16:01:03Z06:00 |
to | A phone number or extension | The number/extension that was called | 15556667777 |
from | A phone number or extension | The number/extension that sent the call | 15556668888 |
Gather
partialResult
A partialResult event is sent when only some of the DTMF has been entered or some speech has been recognized - each digit press or segment of recognized speech will send the following data:
JSON from POST request:
{
"type": "gather",
"event": "partial_input",
"call_id": "3d0716cc-10b4-4c73-a494-6069017c2d54",
"time": "2021-08-12T14:23:31Z",
"partial_input": "7",
"input_method": "dtmf"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be gather |
Says what VoxXML command block initated this event | gather |
event | Will always be partial_input |
Says what VoxXML event this is | partial_input |
call_id | An alphanumeric UUID | The UUID of this call for the Voice API | 8d658f67-3879-4938-bbad-863878bd5341 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-01-05T16:01:03Z06:00 |
partial_input | String | The input gathered so far, either from DTMF or speech detection | 446 |
input_method | String, dtmf or speech |
The method used to gather the input so far | dtmf |
fullResult
A fullResult event is sent once all of the DTMF has been entered or all speech has been recognized (or the timeout has expired). A single event with the following data will be sent:
JSON from POST request:
{
"type": "gather",
"event": "complete_input",
"call_id": "3d0716cc-10b4-4c73-a494-6069017c2d54",
"time": "2021-08-12T14:23:35Z",
"complete_input": "7785",
"input_method": "dtmf"
}
Field | Type | Description | Example |
---|---|---|---|
type | Will always be gather |
Says what VoxXML command block initated this event | gather |
event | Will always be complete_input |
Says what VoxXML event this is | complete_input |
call_id | An alphanumeric UUID | The UUID of this call for the Voice API | 8d658f67-3879-4938-bbad-863878bd5341 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-01-05T16:01:03Z06:00 |
complete_input | String | The final input from either DTMF or speech detection | 4465 |
input_method | String, dtmf or speech |
The method used to gather the input so far | dtmf |
Dial
A dial block will send the same callbacks as a Number block, including keeping the type designation as "number".
Number blocks inside of a Dial block will have their individual callback parameters ignored - the Dial block will override them.
Number
queued
A queued event is sent when the destination number is being processed by the API.
JSON from POST request:
{
"type": "number",
"event": "queued",
"call_id": "c88f9b06-7ef2-4cfd-9581-ed2da634aff2",
"destination_number": "15556667777",
"time": "2021-08-16T19:37:04Z"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be number |
Says what VoxXML command block initiated this event | number |
event | Will always be queued |
Says what VoxXML event this is | queued |
call_id | An alphanumeric UUID | The UUID of this call for the Voice API | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
destination_number | A phone number in E.164 format | The phone number being dialed | 15556667777 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-01-05T16:01:03Z06:00 |
ringing
A ringing event is sent when the destination number is being rung by the API.
JSON from POST request:
{
"type": "number",
"event": "ringing",
"call_id": "c88f9b06-7ef2-4cfd-9581-ed2da634aff2",
"destination_number": "15556667777",
"time": "2021-08-16T19:37:04Z"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be number |
Says what VoxXML command block initiated this event | number |
event | Will always be ringing |
Says what VoxXML event this is | ringing |
call_id | An alphanumeric UUID | The UUID of this call for the Voice API | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
destination_number | A phone number in E.164 format | The phone number being dialed | 15556667777 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-01-05T16:01:03Z06:00 |
answered
An answered event is sent when the dialed number is answered.
JSON from POST request:
{
"type": "number",
"event": "answered",
"call_id": "c88f9b06-7ef2-4cfd-9581-ed2da634aff2",
"destination_number": "15556667777",
"time": "2021-08-16T19:37:05Z"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be number |
Says what VoxXML command block initiated this event | number |
event | Will always be answered |
Says what VoxXML event this is | answered |
call_id | An alphanumeric UUID | The UUID of this call for the Voice API | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
destination_number | A phone number in E.164 format | The phone number being dialed | 15556667777 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-01-05T16:01:03Z06:00 |
complete
A complete event is sent when a call to a number is complete, either because the callee hung up, or because the API was used to terminate the call.
JSON from POST request:
{
"type": "number",
"event": "complete",
"call_id": "c88f9b06-7ef2-4cfd-9581-ed2da634aff2",
"destination_number": "15556667777",
"time": "2021-08-16T19:37:07Z"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be number |
Says what VoxXML command block initiated this event | number |
event | Will always be complete |
Says what VoxXML event this is | complete |
call_id | An alphanumeric UUID | The UUID of this call for the Voice API | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
destination_number | A phone number in E.164 format | The phone number being dialed | 15556667777 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-01-05T16:01:03Z06:00 |
noConnect
A noConnect event is sent when a number never picks up, either because of a timeout or because a different number answered first.
JSON from POST request:
{
"type": "number",
"event": "no_connect",
"call_id": "c88f9b06-7ef2-4cfd-9581-ed2da634aff2",
"destination_number": "15556667777",
"time": "2021-08-16T19:37:07Z"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be number |
Says what VoxXML command block initiated this event | number |
event | Will always be no_connect |
Says what VoxXML event this is | no_connect |
call_id | An alphanumeric UUID | The UUID of this call for the Voice API | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
destination_number | A phone number in E.164 format | The phone number being dialed | 15556667777 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-01-05T16:01:03Z06:00 |
Conference
The first participant added to a conference sets the callback settings for that conference. Subsequent participants' callback settings will have no affect on which callbacks are used.
start
A start event is sent when the first participant joins a conference, even if the participant joins with startConferenceOnEnter='false'
.
JSON from POST request:
{
"type": "conference",
"event": "start",
"time": "2021-08-19T13:27:04Z",
"conference_id": "f1918438-4acf-1bc3-98f9-ac485545ef7a"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be conference |
Says what VoxXML command block initiated this event | conference |
event | Will always be start |
Says what VoxXML event this is | start |
conference_id | An alphanumeric UUID | The voice API UUID of this conference | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-01-05T16:01:03Z06:00 |
end
An end event is sent when a conference has no more participants. It can be triggered by each participant voluntarily leaving, or by a participant with endConferenceOnExit='true'
leaving the conference.
JSON from POST request:
{
"type": "conference",
"event": "end",
"time": "2021-08-19T13:27:04Z",
"conference_id": "f1918438-4acf-1bc3-98f9-ac485545ef7a"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be conference |
Says what VoxXML command block initiated this event | conference |
event | Will always be end |
Says what VoxXML event this is | end |
conference_id | An alphanumeric UUID | The voice API UUID of this conference | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-01-05T16:01:03Z06:00 |
join
A join event is sent when a participant joins a conference.
JSON from POST request:
{
"type": "conference",
"event": "join",
"time": "2021-08-19T13:27:05Z",
"participant_id": "56ce700d-cc4f-4eb9-b1b4-e884ea811c42",
"conference_id": "f1918438-4acf-1bc3-98f9-ac485545ef7a",
"participant_label": "john"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be conference |
Says what VoxXML command block initiated this event | conference |
event | Will always be join |
Says what VoxXML event this is | join |
conference_id | An alphanumeric UUID | The voice API UUID of this conference | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
participant_id | An alphanumeric UUID | The voice API UUID of the participant joining | f1918438-4acf-1bc3-98f9-ac485545ef7a |
participant_label | A string | The label applied to the participant (omitted if unset) | participant1 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-0-05T16:01:03Z06:00 |
leave
A leave event is sent when a participant leaves a conference.
JSON from POST request:
{
"type": "conference",
"event": "leave",
"time": "2021-08-19T13:27:05Z",
"participant_id": "56ce700d-cc4f-4eb9-b1b4-e884ea811c42",
"conference_id": "f1918438-4acf-1bc3-98f9-ac485545ef7a",
"participant_label": "john"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be conference |
Says what VoxXML command block initiated this event | conference |
event | Will always be leave |
Says what VoxXML event this is | leave |
conference_id | An alphanumeric UUID | The voice API UUID of this conference | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
participant_id | An alphanumeric UUID | The voice API UUID of the participant joining | f1918438-4acf-1bc3-98f9-ac485545ef7a |
participant_label | A string | The label applied to the participant (omitted if unset) | participant1 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-0-05T16:01:03Z06:00 |
dtmf
A dtmf event is sent when a participant in a conference presses a button on their phone's number pad.
JSON from POST request:
{
"type": "conference",
"event": "dtmf",
"participant_id": "4e2eb655-205e-4795-a874-b758abbb01e4",
"conference_id": "448e19c7-64dc-81f9-8173-b26aeb124904",
"dtmf": "2",
"time": "2021-08-19T14:48:05Z"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be conference |
Says what VoxXML command block initiated this event | conference |
event | Will always be dtmf |
Says what VoxXML event this is | dtmf |
conference_id | An alphanumeric UUID | The voice API UUID of this conference | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
participant_id | An alphanumeric UUID | The voice API UUID of the participant joining | f1918438-4acf-1bc3-98f9-ac485545ef7a |
participant_label | String | The label applied to the participant (omitted if unset) | george |
dtmf | Digit 0 -9 ,* , or # |
The button that was pressed | 3 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-0-05T16:01:03Z06:00 |
mute
A mute event is sent when a participant is muted. If the API is used to mute a participant who is already muted, a mute event will still be sent.
JSON from POST request:
{
"type": "conference",
"event": "mute",
"time": "2021-08-19T13:27:05Z",
"participant_id": "56ce700d-cc4f-4eb9-b1b4-e884ea811c42",
"conference_id": "f1918438-4acf-1bc3-98f9-ac485545ef7a",
"participant_label": "john"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be conference |
Says what VoxXML command block initiated this event | conference |
event | Will always be mute |
Says what VoxXML event this is | mute |
conference_id | An alphanumeric UUID | The voice API UUID of this conference | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
participant_id | An alphanumeric UUID | The voice API UUID of the participant joining | f1918438-4acf-1bc3-98f9-ac485545ef7a |
participant_label | A string | The label applied to the participant (omitted if unset) | participant1 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-0-05T16:01:03Z06:00 |
unmute
An unmute event is sent when a participant is unmuted. If the API is used to unmute a participant who is already not muted, an unmute event will still be sent.
JSON from POST request:
{
"type": "conference",
"event": "unmute",
"time": "2021-08-19T13:27:05Z",
"participant_id": "56ce700d-cc4f-4eb9-b1b4-e884ea811c42",
"conference_id": "f1918438-4acf-1bc3-98f9-ac485545ef7a",
"participant_label": "john"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be conference |
Says what VoxXML command block initiated this event | conference |
event | Will always be unmute |
Says what VoxXML event this is | unmute |
conference_id | An alphanumeric UUID | The voice API UUID of this conference | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
participant_id | An alphanumeric UUID | The voice API UUID of the participant joining | f1918438-4acf-1bc3-98f9-ac485545ef7a |
participant_label | A string | The label applied to the participant (omitted if unset) | participant1 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-0-05T16:01:03Z06:00 |
muteAll
An muteAll event is sent when an entire conference is muted. If the API is used to mute a conference that was already muted a muteAll event will still be sent.
JSON from POST request:
{
"type": "conference",
"event": "mute_all",
"time": "2021-08-19T13:27:05Z",
"participant_id": "56ce700d-cc4f-4eb9-b1b4-e884ea811c42",
"conference_id": "f1918438-4acf-1bc3-98f9-ac485545ef7a",
"participant_label": "john"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be conference |
Says what VoxXML command block initiated this event | conference |
event | Will always be mute_all |
Says what VoxXML event this is | muteAll |
conference_id | An alphanumeric UUID | The voice API UUID of this conference | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
participant_id | An alphanumeric UUID | The voice API UUID of the participant joining | f1918438-4acf-1bc3-98f9-ac485545ef7a |
participant_label | A string | The label applied to the participant (omitted if unset) | participant1 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-0-05T16:01:03Z06:00 |
unmuteAll
An unmuteAll event is sent when an entire conference is unmuted. If the API is used to unmute a conference that was already unmuted a unmuteAll event will still be sent.
JSON from POST request:
{
"type": "conference",
"event": "unmute_all",
"time": "2021-08-19T13:27:05Z",
"participant_id": "56ce700d-cc4f-4eb9-b1b4-e884ea811c42",
"conference_id": "f1918438-4acf-1bc3-98f9-ac485545ef7a",
"participant_label": "john"
}
Field | Data | Description | Example |
---|---|---|---|
type | Will always be conference |
Says what VoxXML command block initiated this event | conference |
event | Will always be unmute_all |
Says what VoxXML event this is | unmuteAll |
conference_id | An alphanumeric UUID | The voice API UUID of this conference | c88f9b06-7ef2-4cfd-9581-ed2da634aff2 |
participant_id | An alphanumeric UUID | The voice API UUID of the participant joining | f1918438-4acf-1bc3-98f9-ac485545ef7a |
participant_label | A string | The label applied to the participant (omitted if unset) | participant1 |
time | Timestamp with nearest-second precision | The time at which this event was initiated | 2018-0-05T16:01:03Z06:00 |
Errors
Voxtelesys reports outbound messaging errors via HTTP callbacks. Errors while interacting with the REST API are returned in response to the request. If you have any questions or need help resolving errors please contact support.
HTTP errors
Code | Description |
---|---|
401 | Unauthorized - The provided credentials failed. Please see authentication for more details. |
404 | Not Found - The request URL and/or HTTP method was not found. |
422 | Unprocessable Entity - The request data and/or parameters are not valid. |
500 | Internal Server Error - An error occurred within the server. Please contact Voxtelesys with the provided error_id to resolve this error. |
Call Errors
Code | Description |
---|---|
5105 | root element "Response" missing in voxXML |
5106 | bad syntax in voxXML |
5107 | could not reach URL |
5108 | bad mimetype in HTTP VoxXML |
6100 | internal server error |
6101 | internal server error |
6102 | internal server error |
6103 | internal server error |
6104 | internal server error |
6105 | internal server error |
6106 | internal server error |
6107 | internal server error |
6107 | internal server error |
6108 | internal server error |
6109 | internal server error |