Voice API Introduction

Welcome the Voxtelesys Voice REST API. This API offers an easy, secure solution to create and control voice calls. If 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/v0

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/v0/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!

Create a call

Request:

curl --request POST
    --header 'Authorization: Bearer APIKEY' 
    --header 'Content-Type: application/json' 
    --data '{ "to":"+15556667777", "from":"+15556668888", "voice_trunk_group_id":90001 "voxxml":"<Response><Say voice=\"Joanna\" language=\"en-US\">Hello!</Say></Response>" }'
    --url 'https://voiceapi.voxtelesys.net/api/v0/calls'

Response:

{
  "status": "queued",
}

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 in E.164 format.	+15556667777
from	string	yes	The number to originate the call from in E.164 format.	+15556668888
voice_trunk_group_id	number	yes	The outbound trunk group to use for the outgoing call.	90001
voxxml	string	no	VoxXML to execute after connecting. If both voxxml and url are present, then voxxml will not be used.	<Response><Say voice='Joanna' language='en-US'>Hello!</Say></Response>
timeout	number between 0 and 600	no	The integer number of seconds to allow before ending the call due to no answer. Defaults to 60 seconds.	120
url	valid URI string	no	URL to download VoxXML from. If url is present, it will be used instead of voxxml.	https://example.com
method	GET or POST as string	no	Method to use when fetching XML via the provided URL. Defaults to POST.	GET
record	boolean	no	If true, the entire call will be recorded. Defaults to false.	true
recording_track	inbound, outbound, or both	no	Sets which side of the call to record. Defaults to both. outbound records only the audio generated by the VoxXML, and inbound records only the callee's voice.	inbound
recording_channel	mono or dual	no	Sets the number of channels in the audio recording file. Defaults to mono.	dual
recording_status_callback	valid URI string	no	The absolute URL to send callbacks to when the status of the recording is updated.	http://example.com
recording_status_callback_method	GET or POST as string	no	The HTTP method to use for recording status callbacks.	GET
recording_status_callback_event	string containing in-progress, completed, and/or failed, separated by spaces	no	The recording statuses for which callbacks should be sent. Defaults to completed.	in-progress completed failed

Every payload must contain either voxxml or url. If both are present, then the VoxXML that is fetched from the URL is used instead of voxxml.

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.

VoxXML

Calls are controlled through VoxXML. VoxXML provides an action or a series of actions to be taken by a call. 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 verb. All verbs to be used by the API must be enclosed in <Response> tags, or else the verb will be rejected by the API.

For people familiar with XML, <Response> is the root element of the XML document.

Answer

If a call is in the setup stage and has not yet been answered, then the <Answer> verb will answer the call. Only the first call to <Answer> has an effect.

Attributes

<Answer> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
history	disable, compact, full	disable	no	history="full"

history

The history attribute determines if the <Answer> verb should be logged in the history array of the CDR. The default is to not log.

For <Answer>, both compact and full have the same effect of logging an empty payload to the history array.

Example

Example 1:

<Response>
  <Answer/>
  <Redirect>/next</Redirect>
</Response>

1. Answer the call and redirect to the /next URL.

Dial

The <Dial> verb connects the current caller to another party.

Nouns

You may choose to nest plain text (a string representing a valid phone number) in <Dial> to tell Voxtelesys a phone number to call.

You may also choose to nest up to 10 <Number> nouns within the <Dial> verb.

Attributes

<Dial> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
action	relative or absolute URL	none	no	action="https://example.com/callback"
answerOnBridge	true, false	false	no	answerOnBridge="true"
callerId	valid phone number	inbound caller's caller ID	no	callerId="800-800-8000"
hangupOnStar	true, false	false	no	hangupOnStar="true"
method	GET, POST	POST	no	method="GET"
history	disable, compact, full	disable	no	history="full"
output	alphanumeric name up to 50 characters	none	no	output="example"
ringTone	au, be, cn, cz, de, dk, es, fi, fr, hu, il, in, jp, pl, uk, us	us	no	ringTone="au"
timeout	integer between 5 and 600	30	no	timeout="60"
timeLimit	integer greater than 0	none	no	timeLimit="120"
record	do-not-record, record-from-ringing, record-from-answer, record-from-ringing-dual, record-from-answer-dual	do-not-record	no	record="record-from-ringing"
recordingTrack	inbound, outbound, both	both	no	recordingTrack="inbound"
recordingStatusCallback	relative or absolute URL	none	no	recordingStatusCallback="https://example.com/callback"
recordingStatusCallbackMethod	GET, POST	POST	no	recordingStatusCallbackMethod="GET"
recordingStatusCallbackEvent	in-progress, completed, failed	completed	no	recordingStatusCallbackEvent="in-progress completed failed"

action

The action attribute accepts a URL as its argument. The URL tells Voxtelesys where to make a POST or GET request after the dialed call ends.

If you do not provide an action URL, <Dial> will finish and Voxtelesys will move on to the next VoxXML verb in the document.

See Webhooks: Dial for more information on the HTTP request sent using the <Dial> verb.

answerOnBridge

If the call has not yet been answered, answerOnBridge="true" will cause the inbound call to ring until the dialed number answers.

Effectively, Voxtelesys will send a 18x SIP code when the initial call connects to Voxtelesys. Once the <Dial> call connects, Voxtelesys will answer with a 200.

callerId

The callerId attribute allows you to specify the caller ID to display on the <Dial> call. By default this is set to the inbound caller's number.

For example: 1. Someone with a caller ID of 800-800-8000 calls your Voxtelesys number. 2. You tell Voxtelesys to execute a <Dial> verb to 900-900-9000 to handle the inbound call. 3. The called party (900-900-9000) will see 800-800-8000 as the caller ID on the incoming call.

hangupOnStar

The hangupOnStar attribute lets the initial caller hang up on the called party by pressing the * key on their phone.

When two parties are connected using <Dial>, Voxtelesys blocks execution of further verbs until the caller or callee party hangs up. The hangupOnStar feature allows the initial caller to hang up on the party they called without having to hang up the phone (which would end the Voxtelesys processing session).

When the caller presses *, Voxtelesys will hang up on the called party. If an action URL was provided, Voxtelesys will fetch and process the VoxXML provided by the URL.

If no action was provided, Voxtelesys continues on to the next verb in the current VoxXML document.

method

The method attribute accepts either GET or POST. This tells Voxtelesys whether to request the action URL via HTTP GET or POST, with POST as its default value.

history

The history attribute determines if the <Dial> verb should be logged in the history array of the CDR. The default is to not log.

The <Dial> verb will also generate an element in the history array for the user's input, if either compact or full is used.

output

The output attribute accepts an alphanumeric variable name, up to 50 characters. The final status of <Dial> is saved to this variable via the <output>.status variable.

ringTone

The ringTone attribute allows you to override the ringback tone that Voxtelesys will play back to the caller while executing the <Dial>.

Accepted values are: au, be, cn, cz, de, dk, es, fi, fr, hu, il, in, jp, pl, uk, us.

timeout

The timeout attribute sets the limit in seconds that <Dial> will wait for the dialed party to answer the call. This tells Voxtelesys how long to let the call ring before giving up and setting no-answer as the DialCallStatus.

timeout's default value is 30 seconds, the minimum allowed value is five seconds, and the maximum value is 600 seconds.

timeLimit

The timeLimit attribute sets the maximum duration of <Dial> in seconds.

For example, by setting a time limit of 120 seconds, <Dial> will automatically hang up on the called party two minutes into the phone call.

record

The record attribute tells Voxtelesys whether to record the dialed call. By default, the value is do-not-record. If a recording is desired, you can specify either mono-channel or dual-channel.

Mono-channel recordings involve combining both the caller and the callee into a single channel in the audio recording file. For mono-channel recordings, the options are:

• record-from-ringing: start the recording as soon as the dialed call rings.
• record-from-answer: start the recording once the dialed callee answers.

Dual-channel recordings, on the other hand, separate the caller's and callee's voices into separate channels in the audio recording file. The options for dual channel are:

record-from-ringing-dual: start the recording as soon as the dialed call rings (dual-channel). record-from-answer-dual: start the recording once the dialed callee answers (dual-channel).

recordingTrack

The recordingTrack attribute specifies which side of the dialed call to record. The options are inbound, outbound, and both, and the default is both. If outbound is specified, then only the voice of the dialed callee will be recorded. If inbound is specified, the only the voice of the dialing caller will be recorded. If inbound or outbound is specified, then the resulting audio recording will always be mono-channel.

recordingStatusCallback

The recordingStatusCallback attribute accepts a relative or absolute URL. If a recordingStatusCallback is given, then an HTTP request will be sent to the specified URL with information for each recording status that is requested in recordingStatusCallbackEvent.

In addition to the base parameters sent with every webhook, the following parameters are sent to the RecordingStatusCallback URL:

Parameter	Description
RecordingSid	The unique ID of the recording.
RecordingUrl	The URL of the recorded audio file
RecordingDuration	The duration of the audio recording.
RecordingStatus	The status of the recording. The possible values are in-progress, completed, and failed.
RecordingChannels	The number of channels in the final recording file.
RecordingSource	The method used to create this recording. For <Dial>, this will always be DialVerb.

The possible values for RecordingStatus are:

Value	Description
in-progress	The recording has started.
completed	The recording has finished and has been uploaded.
failed	The recording failed to be uploaded and is not accessible.

recordingStatusCallbackMethod

The recordingStatusCallbackMethod attribute specifies which HTTP method to use when sending a callback to the recordingStatusCallback URL. The default is POST.

recordingStatusCallbackEvent

The recordingStatusCallbackEvent attribute accepts a list of events for which HTTP callbacks should be sent to recordingStatusCallback. To specify more than one event, separate each event name with a space. The default is completed, and the available events are:

• in-progress: the recording has started.
• completed: the recording has finished and has been uploaded.
• failed: the recording failed to be uploaded and is not available.

Examples

Example 1:

<Response>
  <Say>Hello. Please stay on the line while I transfer you to an agent.</Say>
  <Dial>13003003000</Dial>
</Response>

1. Simple usage: Welcome the caller and transfer them to an agent.

Do

The <Do> conditional allows you to implement do/while-style looping.

Attributes

<Do> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
expression	string expression to evaluate	none	yes	expression="${menu.speech}=~'(support|sales)'"
maxLoops	integer > 0	1	no	maxLoops="5"

expression

The expression attribute accepts a string of conditionals to evaluate. If the expression evaluates to true, then all verbs nested inside <Do> are executed. Otherwise, the nested verbs are ignored and the next VoxXML instruction is executed.

maxLoops

The maxLoops attributes sets the maximum number of loops to execute before exiting the <Do> loop.

Example

Example 1:

<Response>
  <Do expression="${menu.digits}!~(1|2)" maxLoops="3">
    <Gather input="dtmf" output="menu">
      <Say>Hello. Press 1 to speak with support or 2 to speak with sales.</Say>
    </Gather>
  </Do>
</Response>

1. Prompt the caller up to 3 times to enter DTMF 1 or 2.

Gather

The <Gather> verb is used to collect digits or transcribe speech during a call.

Verbs

You may choose to nest the following verbs within <Gather>:

• <Pause>
• <Say>
• <Play>

Attributes

<Gather> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
action	relative or absolute URL	none	no	action="https://example.com/callback"
actionOnEmptyResult	true, false	false	no	actionOnEmptyResult="true"
method	GET, POST	POST	no	method="GET"
numDigits	integer > 0	unlimited	no	numDigits="4"
finishOnKey	0-9, #, *, and "" (empty string)	#	no	finishOnKey="0#*"
language	BCP-47 language tags	en-US	no	language="en-US"
input	dtmf, speech, dtmf speech	dtmf	no	input="dtmf"
history	disable, compact, full	disable	no	history="full"
output	alphanumeric name	none	no	output="example"
profanityFilter	true, false	false	no	profanityFilter="true"
timeout	integer > 0	5	no	timeout="10"
speechTimeout	integer > 0 or auto	timeout attribute value	no	speechTimeout="30"

action

The action attribute accepts an absolute or relative URL as its argument. When the caller finished entering digits (or the timeout is reached), Voxtelesys will make an HTTP request to this URL.

After <Gather> ends and Voxtelesys sends its request to your action URL, the current call will continue using the VoxXML you send back from that URL. Because of this, any VoxXML verbs that occur after your <Gather> are unreachable if action is provided.

If you do not provide an action parameter, Voxtelesys will continue onto the next verb in the current VoxXML document.

See Webhooks: Gather for more information on the HTTP request sent with the <Gather> verb.

actionOnEmptyResult

The actionOnEmptyResult attribute allows you to force <Gather> to send a webhook to the action URL even when there is no DTMF input. By default, if <Gather> times out while waiting for DTMF input, it will continue on to the next VoxXML instruction.

finishOnKey

The finishOnKey attribute lets you set a value that your caller can press to submit their digits.

For example, if you set finishOnKey to # and your caller enters 1234#, Voxtelesys will immediately stop waiting for more input after they press # and will store 1234 as the entered digits.

If you use an empty string, <Gather> will capture all user input and no key will end the <Gather>. In this case, Voxtelesys ends the <Gather> only after the timeout is reached.

input

The input attribute specifies which inputs (DTMF or speech) Voxtelesys should accept.

If you set input to speech, Voxtelesys will gather speech from the caller for a maximum duration of 60 seconds.

If you set dtmf speech for your input, the first detected input (speech or dtmf) will take precedence. If speech is detected first, finishOnKey will be ignored.

language

The language attribute specifies the language Voxtelesys should recognize from your caller.

This value defaults to en-US.

Acceptables values include: zh-CN,zh-TW,da,nl,en,en-AU,en-IN,en-NZ,en-GB,en-US,fr,fr-CA,de,hi,hi-Lat,id,it,ja,ko,no,pl,pt,pt-BR,pt-PT,ru,es,es-419,sv,ta,tr,uk.

history

The history attribute determines if the <Gather> verb should be logged in the history array of the CDR. The default is to not log.

The <Gather> verb will also generate an element in the history array for the user's input, if either compact or full is used.

method

The method attribute accepts either GET or POST. This tells Voxtelesys whether to request the action URL via HTTP GET or POST, with POST as its default value.

numDigits

The numDigits attribute sets the number of digits you expect from your caller.

The numDigits attribute only applies to DTMF input.

For example, you might wish to set numDigits="5" when asking your caller to enter their 5-digit zip code. Once the caller enters the final digit of 94117, Voxtelesys will immediately submit the data to your action URL.

output

The output attribute accepts an alphanumeric variable name, up to 50 characters. The final status of <Gather> is saved to this variable via the <output>.digits and <output>.speech variables.

profanityFilter

The profanityFilter specifies if Voxtelesys should filter profanities out of your speech transcription. This attribute defaults to false, which replaces all but the intial character in each filtered profane word with asterisks, e.g., "f***."

If you set this attribute to false, Voxtelesys will no longer filter any profanities in your transcriptions.

speechTimeout

The speechTimeout sets the limit (in seconds) that Voxtelesys will wait after a pause in speech before it stops its recognition. This only applies to speech input.

If you use both timeout and speechTimeout in your <Gather>, timeout will take precedence for DTMF input and speechTimeout will take precedence for speech.

If you set speechTimeout to auto, Voxtelesys will stop speech recognition when there is a pause in speech and return the results immediately.

timeout

The timeout allows you to set the limit (in seconds) that Voxtelesys will wait for the caller to press another digit or say another word before it sends data to your action URL.

For example, if timeout is 3, Voxtelesys waits three seconds for the caller to press another key or say another word before submitting their data.

Voxtelesys will wait until all nested verbs execute before it begins the timeout period.

Example

Example 1:

<Response>
  <Gather input="dtmf" action="/next">
    <Say>Hello, to speak with support press one, for sales press two.</Say>
  </Gather>
</Response>

1. Welcome the caller and collect DTMF.

Hangup

The <Hangup> verb ends the call.

Attributes

<Hangup> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
history	disable, compact, full	none	no	history="full"

history

The history attribute determines if the <Hangup> verb should be logged in the history array of the CDR. The default is to not log.

For <Hangup>, both compact and full have the same effect of logging an empty payload to the history array.

Example

Example 1:

<Response>
  <Say>Goodbye.</Say>
  <Hangup/>
</Response>

1. Say "Goodbye." and end the call.

If

The <If> conditional allows you to conditionally execute a piece of XML.

Attributes

<If> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
expression	string expression to evaluate	none	yes	`expression="${menu.speech}=~'(support

expression

The expression attribute accepts a string of conditionals to evaluate. If the expression evaluates to true, then all verbs nested inside <If> are executed. Otherwise, the nested verbs are ignored and the next VoxXML instruction is executed.

Example

Example 1:

<Response>
  <Gather input="speech" output="menu">
    <Say>Hello. What is the purpose of your call?</Say>
  </Gather>
  <If expression="${menu.speech}=~'(support|sales)'">
    <Say>Transfering you to support or sales.</Say>
  </If>
</Response>

1. Welcome the caller, transcribe input, and evaluate response.

Pause

The <Pause> verb waits silently for a specific number of seconds.

Attributes

<Pause> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
length	integer between 0 and 60	1	no	length=10
history	disable, compact, full	disable	no	history="full"

length

The length attribute specifies how many seconds Voxtelesys will wait silently before continuing on.

history

The history attribute determines if the <Pause> verb should be logged in the history array of the CDR. The default is to not log.

Example

Example 1:

<Response>
  <Pause length="5"></Pause>
  <Say>Hello, and goodbye.</Say>
</Response>

1. Pause for 1 second before playing prompt.

Play

The <Play> verb plays an audio file back to the caller. Voxtelesys retrieves the file from a URL that you provide.

Nouns

The URL of an audio file that Voxtelesys will retrieve and play to the caller.

Attributes

<Play> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
loop	integer > 0	1	no	loop="3"
digits	integer >= 0, w	none	no	digits="1ww2"
history	disable, compact, full	full	no	history="full"

loop

The loop attribute specifies how many times the audio file is played.

digits

The digits attribute lets you play DTMF tones during a call.

For example, if you need to test an IVR system, you can use this feature to simulate digits being pressed to navigate through the menu options.

Include w to introduce a 0.5s pause between DTMF tones. For example, 1w2 will tell Voxtelesys to pause 0.5s before playing DTMF tone 2. To include 1s of pause, simply add ww.

history

The history attribute determines if the <Play> verb should be logged in the history array of the CDR. The default is to not log.

Examples

Example 1:

<Response>
  <Play digits="1ww2"></Play>
  <Hangup/>
</Response>

1. DTMF Usage: Generate DTMF tone 1, wait 1 second, then generate DTMF tone 2.

Example 2:

<Response>
  <Play loops="2">https://example.com/cowbell.mp3</Play>
</Response>

2. URL Usage: Play the cowbell sound clip 2 times.

Record

The <Record> verb records the voice of the caller and generates an audio file that can be downloaded via a URL.

Attributes

<Record> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
action	relative or absolute URL	none	no	action="https://example.com/callback"
method	GET, POST	POST	no	method="GET"
timeout	integer > 0	5 (seconds)	no	timeout="20"
finishOnKey	any digit, #, or *	1234567890*#	no	finishOnKey="3#"
maxLength	integer > 1 and <= 14400 (4 hours)	3600 (1 hour)	no	maxLength="120"
playBeep	true, false	true	no	playBeep="false"
history	disable, compact, full	disable	no	history="full"
recordingStatusCallback	relative or absolute URL	none	no	recordingStatusCallback="https://example.com/callback"
recordingStatusCallbackMethod	GET, POST	POST	no	recordingStatusCallbackMethod="GET"
recordingStatusCallbackEvent	in-progress, completed, failed	completed	no	recordingStatusCallbackEvent="in-progres completed failed"

action

The action attribute accepts a URL as its argument. The URL tells Voxtelesys where to make a POST or GET request after the recording ends.

If you do not provide an action URL, <Record> will finish and Voxtelesys will move on to the next VoxXML verb in the document.

method

The method attribute accepts either GET or POST. This tells Voxtelesys whether to request the action URL via HTTP GET or POST, with POST as its default value.

timeout

The timeout attribute sets the number of seconds of silence for the <Record> verb to allow before ending the recording and setting its status to completed. Once the timeout is reached, the VoxXML fetched from the action URL will be played, or the execution of the current VoxXML will continue if no action URL is provided. The default value of timeout is 5 seconds. To disable this feature, set timeout to 0 seconds.

finishOnKey

The finishOnKey attribute accepts a list of characters that, when pressed, will end the recording, set its status to completed, and proceed with VoxXML execution. More than one character can be specified. For example, if finishOnKey is set to 3#, both the digit "3" and the pound key "#" can be pressed to end the recording. By default, the value is 1234567890*#, which is all characters.

maxLength

The maxLength attribute is the maximum length of the recording, in seconds. The default is 3600 seconds (1 hour), the minimum is 1 second, and the maximum is 14400 seconds (4 hours). For example, if maxLength is set to 60 seconds, the recording will automatically end after 1 minute.

playBeep

The playBeep attribute accepts a boolean that determines whether to play a beep at the beginning of the recording. The default is to play the beep. If playBeep is set to false, then no beep will be played before the recording starts.

recordingStatusCallback

The recordingStatusCallback attribute accepts a relative or absolute URL. If a recordingStatusCallback is given, then an HTTP request will be sent to the specified URL with information for each recording status that is requested in recordingStatusCallbackEvent.

In addition to the base parameters sent with every webhook, the following parameters are sent to the RecordingStatusCallback URL:

Parameter	Description
RecordingSid	The unique ID of the recording.
RecordingUrl	The URL of the recorded audio file
RecordingDuration	The duration of the audio recording.
RecordingStatus	The status of the recording. The possible values are in-progress, completed, and failed.
RecordingChannels	The number of channels in the final recording file. For <Record>, only one channel is supported.
RecordingSource	The method used to create this recording. For <Record>, this will always be RecordVerb.

The possible values for RecordingStatus are:

Value	Description
in-progress	The recording has started.
completed	The recording has finished and has been uploaded.
failed	The recording failed to be uploaded and is not accessible.

recordingStatusCallbackMethod

The recordingStatusCallbackMethod attribute specifies which HTTP method to use when sending a callback to the recordingStatusCallback URL. The default is POST.

recordingStatusCallbackEvent

The recordingStatusCallbackEvent attribute accepts a list of events for which HTTP callbacks should be sent to recordingStatusCallback. To specify more than one event, separate each event name with a space. The default is completed, and the available events are:

• in-progress: the recording has started.
• completed: the recording has finished and has been uploaded.
• failed: the recording failed to be uploaded and is not available.

history

The history attribute determines if the <Record> verb should be logged in the history array of the CDR. The default is to not log.

The <Record> verb will also generate an element in the history array for the user's input, if either compact or full is used.

Examples

Example 1:

<Response>
  <Say>Please leave a message at the beep and press "star" when finished.</Say>
  <Record finishOnKey="*"/>
</Response>

1. Voicemail system

Redirect

The <Redirect> verb transfers control of a call to the VoxXML at a different URL. All verbs after <Redirect> are unreachable and ignored.

Nouns

An absolute or relative 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.

Relative URLs are constructed according to RFC 3986 Section 5.2, where the base URL is taken from the working VoxXML document. Some examples for convenience:

Base URL	Relative URL	Absolute URL
https://fake.com	/next	https://fake.com/next
https://fake.com/file/path	/	https://fake.com/
https://fake.com/file/path	./new	https://fake.com/file/new

Attributes

<Redirect> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
method	GET,POST	POST	no	method="GET"
history	disable, compact, full	full	no	history="full"

history

The history attribute determines if the <Redirect> verb should be logged in the history array of the CDR. The default is to not log.

method

The method attribute determines what HTTP method will be used when making the request to the provided URL.

Examples

Example 1:

<Response>
  <Say>Hello.</Set>
  <Redirect>https://www.example.com/next</Redirect>
</Response>

1. Absolute URL Usage: Welcome the user and redirect to an absolute URL.

Example 2:

<Response>
  <Say>Hello.</Set>
  <Redirect>/next</Redirect>
</Response>

2. Relative URL Usage: Welcome the user and redirect to a relative URL.

Reject

The <Reject> verb rejects an incoming call without billing the customer. This is very useful for blocking unwanted calls.

If the first verb in a VoxXML document is <Reject>, Voxtelesys will not answer the call. The call ends with a status of busy or no-answer, depending on the verb's reason attribute. Any verbs after <Reject> are unreachable and ignored.

Attributes

<Reject> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
history	disable, compact, full	full	no	history="full"
reason	rejected, busy	rejected	no	reason="rejected"

history

The history attribute determines if the <Reject> verb should be logged in the history array of the CDR. The default is to not log.

reason

The reason attribute takes the values rejected and busy. This tells Voxtelesys what message to play when rejecting the call. Selecting busy will play a busy signal to the caller, while selecting rejected will play a standard non-in-service response.

The actual message played back is determined by the caller's service provider, as reason is only manipulating the SIP response code.

Example

Example 1:

<Response>
  <Reject reason="rejected"></Redirect>
</Response>

1. Reject the call with rejected reason.

Say

The <Say> verb converts text to speech (TTS) that is read back to ther caller. <Say> is useful for developing dynamic text that is difficult to pre-record. The verb offers different options for voices, each with its own supported set of languages and genders.

The current TTS engine used by <Say> is Amazon Polly. All voices and languages supported by Polly can be used by <Say>.

The <Say> verb also support SSML. Please see supported SSML tags.

Nouns

The text that is read to the caller. The length is limited to 3,000 UTF-8 single byte characters, not including SSML tags.

Attributes

<Say> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
voice	see Polly docs	Polly.Joana	no	voice="Polly.Joana"
language	see Polly docs	en-US	no	language="en-US"
history	disable, compact, full	disable	no	history="full"
loop	integer > 0	1	no	loop="3"

voice

The voice attribute allows you to select the Polly voice to use when reading the text. Both standard and Neural Polly voices can be used. See Polly docs for a complete list.

The voice attribute has the following syntax:

<engine>.<voice>(-Neural)?

For example:

• Polly.Matthew
• Polly.Matthew-Neural

language

The language attribute allows you to specify a language and locale, with the affiliated accent and pronunciations. The language must match the selected voice. See Polly docs for a complete list.

history

The history attribute determines if the <Say> verb should be logged in the history array of the CDR. The default is to not log.

loop

The loop attribute specifies how many times you'd like the text repeated. The default is once.

Examples

Example 1:

<Response>
  <Say>Hello, and goodbye.</Say>
  <Hangup/>
</Response>

1. Simple Usage: Read back text to the caller, using default voice/language, and end the call.

Example 2:

<Response>
  <Say voice="Polly.Matthew-Neural" languge="en-US">Transfering you to a live agent now.</Say>
  <Redirect>/transferToSupport</Redirect>
</Response>

2. Advanged Usage: Read back text to the caller using a Neural voice from Polly. While it costs more, the Neural TTS is much better than the standard engine.

Set

The <Set> verb allows the developer to set variables. The variable is scoped to the call dialog, meaning once set it is available in subsequent XML and conditionals. Furthermore, any variables set using the <Set> verb are provided on future webhooks via the Vars field. The Vars field is also populated in the call detail record (CDR).

Only string values are supported.

Nouns

The variable's value is provided as plain text in <Set> and has a maximum length of 50 characters.

Attributes

<Set> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
history	disable, compact, full	disable	no	history="full"
output	string (up to 50 characters)	none	no	output="example"

history

The history attribute determines if the <Set> verb should be logged in the history array of the CDR. The default is to not log.

output

The output attribute represents the variable's name.

Example

Example 1:

<Response>
  <Set output="position">support</Set>
  <Redirect>/transferToSupport</Redirect>
</Response>

1. Set a position variable to mark that the caller has reached support then redirect to the transferToSupport URL.

Unset

The <Unset> verb allows the developer to delete a variable.

Attributes

<Unset> supports the following attributes that change its behavior:

Attribute	Accepts	Default	Required	Example
history	disable, compact, full	disable	no	history="full"
output	string (up to 50 characters)	none	no	output="example"

history

The history attribute determines if the <Unset> verb should be logged in the history array of the CDR. The default is to not log.

output

The output attribute represents the variable's name.

Example

Example 1:

<Response>
  <Unset output="menu"></Unset>
  <Redirect>/menu</Redirect>
</Response>

1. Clear the menu variable and then redirect to the menu URL.

Webhooks

Webhooks are user-defined HTTP callbacks. They are triggered by some event in a web application and can facilitate integrating different application or third-party APIs, like Voxtelesys.

Voxtelesys uses webhooks to let your application know when events happen, such as receiving an incoming phone call. When the event occurs, Voxtelsys makes an HTTP request (usually a POST or a GET) to the URL you configured for the webhook. Voxtelesys' request will include details of the event such as the incoming phone number. For POST HTTP requests, the content will be sent in the body as type application/x-www-form-urlencoded.

Some of these webhooks are informational (such as letting you know that a voice call recording is ready for download), and others require your web application to respond (for instance, letting Voxtelesys know what to do when someone calls your Voxtelesys phone number).

Voice Webhooks

Working with the Voxtelesys Voice API, your web application can receive several different types of webhooks.

The first type of webhook is an incoming voice call. When someone dials a phone number associated with your Voxtelesys account, you may choose to process that request within your web application.

The second type of webhook is a status callback, which you will receive after completing an outbound call through Voxtelesys.

The final type of webhook to consider is a recording status callback. Voxtelesys will send one of these callbacks after a call recording is completed and the audio of the recording has been processed into a file.

Request Parameters

Voxtelesys always sends the following parameters when it sends a request to your application to retrieve instructions for how to handle a call.

These will send as either POST parameters or URL query parameters, depending on which HTTP method you've configured.

Parameter	Description
CallSid	A unique identifier for this call, generated by Voxtelesys.
AccountID	Your Voxtelesys account ID.
TrunkID	Your Voxtelesys trunk group ID.
From	The phone number that initiated the call.
To	The phone number of the called party.
CallStatus	A descriptive status for the call.
ApiVersion	The version of the Voxtelesys API used to handle this call.
Direction	A string describing the direction of the call: inbound, outbound-api, outbound-dial
CallerName	The caller name CNAM
ParentCallSid	A unique identifier for the call that created this leg. This parameter is not passed if this is the first leg of a call.
Vars	Set if there are any custom variables set on the call.

Voxtelesys also attempts to look up geographical data based on the To and From phone numbers. If available, Voxtelesys will send the following parameters with its request:

Parameter	Description
FromCity	The city of the caller
FromState	The state or province of the caller
FromZip	The postal code of the caller
FromCountry	The country of the caller
ToCity	The city of the called party
ToState	The state or province of the called party
ToZip	The postal code of the called party
ToCountry	The country of the called party

Voxtelesys will provide the parameters listed above when it makes a request to your application to retrieve instructions for how to handle a call. This might occur when an inbound call comes to your Voxtelesys number, or after a VoxXML verb has completed and you've provided an action URL where Voxtelesys can retrieve the next set of instructions. Depending on what is happening on a call, other variables may also be sent.

Data Formats

Phone Numbers

All phone numbers in requests from Voxtelesys are in E.164 format if possible. For example (231) 685-1234 would come through as +12316851234. However, there are occasionally cases when Voxtelesys cannot normalize an incoming caller ID to E.164. In these situations, Voxtelesys will report the raw caller ID string.

Dates and Times

All dates and times in requests from Voxtelesys are GMT in RFC 2822 format. For example, 6:13 PM PDT on August 19th, 2010 would be ‘Fri, 20 Aug 2010 01:13:42 +0000’.

Dial

Voxtelesys' request to the action URL will send the following parameters:

Parameter	Description
DialCallStatus	The outcome of the <Dial> attempt. See the DialCallStatus section below for details.
DialCallSid	The call sid of the new call leg. This parameter is not sent after dialing a conference.
DialCallDuration	The duration in seconds of the dialed call. This parameter is not sent after dialing a conference, or if a Child call is redirected to a new VoxXML URL before being disconnected.
RecordingUrl	The URL of the recorded audio file, if applicable.

DialCallStatus

If you specify an action URL, Voxtelesys will always pass along the status of the <Dial> attempt.

Possible DialCallStatus values are:

Value	Description
completed	The called party answered the call and was connected to the caller.
answered	When calling a conference, the called party answered the call and was connected to the caller.
busy	Voxtelesys received a busy signal when trying to connect to the called party.
no-answer	The called party did not pick up before the timeout period passed.
failed	Voxtelesys was unable to route to the given phone number. This is frequently caused by dialing a properly formatted but non-existent phone number.
canceled	The call was canceled via the REST API before it was answered.

Gather

Voxtelesys' request to the action URL will send the following parameters:

Parameter	Description
Digits	The collected DTMF.
SpeechResult	The collected transcribed speech.

Record

Voxtelesys' request to the action URL will send the following parameters:

Parameter	Description
RecordingUrl	The URL of the recorded audio file
RecordingDuration	The duration of the audio recording.
Digits	The DTMF characters that were used to end the recording, if applicable. If the recording ended on a hangup, then the value will instead be hangup.

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

Error Response JSON:

{
  "status": "error", // label for error status
  "message": "missing voice_trunk_group_id", // description of error
  "error_id": "330d1614-f204-411f-a518-1f3aa15773e7" // unique error ID
}

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