Navbar
shell
  • Voice API Introduction
  • Authentication
  • Calls
  • Conferences
  • Conference participants
  • VoxXML
  • VoxXML Examples
  • Callbacks
  • Errors
  • 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

    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

    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:

    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

    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

    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

    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

    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

    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

    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

    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

    Example:

    <Reject/>
    

    Content

    None

    Attributes

    None

    Say

    The Say block uses Amazon Polly to auto-generate text-to-speech.

    Supported Resources

    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

    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:

    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:

    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