Overview

Zang Cloud is a robust development platform — create what you need, integrate it seamlessly with your current communications systems and go! Getting started with Zang Cloud is easy. The first thing you need to do is Sign Up for an account. A trial account comes with complimentary credit to help you get started with the platform and with building/testing your initial application. Developing on the Zang platform is actually free and you're only charged on a per-usage basis. Once you have experimented or tested your use case, you can upgrade to a production account by clicking on the Request Production Access button found in the Dashboard of your account. This will unlock the trial account restrictions and also allow you to add funds to your account.

Getting Started with InboundXML

InboundXML describes how Zang should handle a call and SMS. It's basically instructions that tell Zang what to do when you receive an inbound call or SMS. Hence the name InboundXML! Upon receiving a call or SMS, Zang follows the InboundXML instructions, enabling developers to easily build telephony apps with all the same function and power found in traditional phone systems.

Once you have created your account, you'll want to head right over to Numbers > Buy A Phone Number to purchase a phone number. Feel free to purchase any of the pre-populated numbers or search for a number by area code. Once you have purchased a number, you will be automatically routed to the settings for that number.

Every number purchased on the Zang platform will have a Voice Request URL and SMS Request URL assigned by default. The URL's are as follows:

Voice Request URL: http://www.zang.io/ivr/welcome/call
SMS Request URL: http://www.zang.io/ivr/welcome/sms

Let's go ahead and place a call to your newly purchased Zang number. The result will be a short say message:


<Response>
  <Say>Welcome to your new Zang Account.</Say>
  <Say voice="woman">Let us know if we can help you in any way during your development.</Say>
</Response>
                      

Now let's go ahead and send an SMS to your newly purchased Zang number from an SMS-capable number, preferably your mobile phone. The result will be an outbound-reply from Zang:


<Response>
  <Sms>Welcome to Zang! Let us know if we can help you in any way during your development.</Sms>
</Response>
                      

That's all there is to it! Please check out the rest of the documentation and feel free to experiment. If you run into any issues, feel free to contact our support team: support@zang.io.

Request

Parameters you can include for a InboundXML Request

When handling an inbound call or SMS, Zang requests either the Voice or SMS Request URL (or any other subsequent URLs Zang may interact with) using standard HTTP GET or POST methods. The method can be specified on a case by case basis, but both send the following default request parameters to Zang with information about the call or SMS taking place. If the initial request method is GET, these values are sent as URL query parameters. If it is POST, they are sent as POST parameters.

Default Voice Request Parameters

Parameter
  • AccountSid

    Alphanumeric string identifying the account this call occurred through.

  • ApiVersion

    The version of the API the call is using.

  • Direction

    The direction of the call.

  • CallerName

    The name registered to the phone calling.

  • To

    The number called.

  • From

    The number calling.

  • CallSid

    Alphanumeric string identifying this call.

  • CallStatus

    Status of the call. May be: queued, ringing, in-progress, completed, busy, failed, no-answer, or canceled.

  • UrlBase

    The base URL that was consulted at call connection.

  • Unblocked

    Boolean value specifying whether the inbound number calling was unblocked. This parameter will only be default for DIDs that have unblocking enabled.

  • ForwardedFrom

    The number this call was forwarded from. This parameter will only be present if the call was forwarded.

Default SMS Request Parameters

Parameter
  • AccountSid

    Alphanumeric string identifying the account this SMS occurred through.

  • ApiVersion

    The version of the API the SMS is using.

  • To

    The number that received the SMS message.

  • From

    The number that sent the SMS message.

  • SmsSid

    Alphanumeric string identifying this SMS resource.

  • SmsStatus

    Status of the SMS.

Number and Date Formats

Zang tries to change all phone numbers to E.164 format (e.g. (123)-456-7890 to 1234567890). If it can not, it uses the raw number input.

In addition, the date "1:22 PM PDT on January 12th, 2012 " would be displayed as "Thu, 12 Jan 2012 01:22:00 -4000" to adhere to UTC in RFC 2822 format.

Response

Parameters you can expect back from Zang when you submit InboundXML Requests

Zang numbers can be configured to respond to calls or SMS messages with InboundXML. This page will explains the process. If no response, and subsequent charge, is desired simply remove the request URL for voice and/or SMS and you're all set.

Interpreting InboundXML

When Zang receives an InboundXML document, the "instructions" are contained within the <Response> </Response> elements. Zang begins reading at <Response> and behaves accordingly as it encounters each new instruction element until the end of the </Response>. All InboundXML elements are camelCased and are categorized as either Verbs or Nouns.


<Response>
 <Say>You are about to execute a new call</Say>
  <Dial action="http://webhookr.com/interpreter-voice-sample">4125551680</Dial>
  <Say>We have passed the Dial. The call will now be terminated</Say>
 <Hangup/>
</Response>
                                

InboundXML Verbs and Nouns

InboundXML verbs are elements that define the behavior the call or SMS should have when executing the InboundXML. Nouns are simply the specifics of the behavior defined by the verb elements. Nouns are always nested within verb elements and can be either other xml elements or plain text.

<Conference>

Like the <Number> element, the <Conference> element is only nested within the <Dial> element. Instead of dialing a number, the <Conference> element allows the ongoing call to connect to a conference room.

The conference room name is nested within the <Conference> element, and all calls connected to the same conference room name will be in the room together.

By default, all callers will hear hold music until two callers are in the room. To change this behavior, startConferenceOnEnter may be set to ‘true’ or ‘false’. The waitUrl attribute may be used to set a custom MP3. For greater customization, the URL of an InboundXML document can be used while callers are waiting as well. If an InboundXML document is used, the <Gather>, <Record> and <Dial> elements are not allowed.

When callers enter or exit the room, a beep is heard if the beep attribute is set to the default value of ‘true’. A participant can be initially muted by setting the muted attribute to ‘true’.

The conference room can be limited to a certain number of participants by setting the maxParticipants attribute. The endConferenceOnExit attribute is used to end a conference when an specific user (or any one of many users) exits.

Attribute
  • muted

    Boolean value specifying if the conference should be muted. Default Value: false. Allowed Value: true or false.

  • beep

    Boolean value specifying if a beep should play upon entrance to conference. Default Value: false. Allowed Value: true or false.

  • startConferenceOnEnter

    Boolean value specifying if conference should begin upon entrance. Default Value: false. Allowed Value: true or false.

  • endConferenceOnExit

    Boolean value specifying if conference should end upon a specific users exit. Default Value: false. Allowed Value: true or false.

  • maxParticipants

    The maximum number of participants allowed in the conference call. Default Value: 40. Allowed Value: integer from 1 to 40.

  • waitSound

    URL to inboundXML where conference participants can be sent to while they wait for entrance into the conference. Only method supported at this time.

  • hangupOnStar

    Boolean value specifying if pressing * should end the conference. Default Value: false. Allowed Value: true or false.

  • callbackUrl

    URL where some parameters specific to will be sent when participants enter and exit the conference and once it is completed. There is only one callbackUrl allowed per conference. The first callbackUrl will be the only one used.

  • callbackMethod

    Method used to request the callback URL. Default Value: POST. Allowed Value: POST or GET.

  • digitsMatch

    Specifies digits that Zang should listen for and send to the callbackUrl if a caller inputs them. Separate additional digits or digit patterns with a comma. Allowed Value: Pattern made up of the digits 0-9, #, or *.

  • stayAlone

    Boolean value specifying if the caller should stay alone in the conference call. Default Value: false. Allowed Value: true or false.

  • record

    Boolean value specifying if the conference should be recorded. Default Value: false. Allowed Value: true or false.

  • recordCallbackUrl

    URL to sound that the recording will be sent to from the conference.

  • recordFileFormat

    File format in which the recording will be saved in. Default Value: mp3. Allowed Value: mp3 or wav.


Nesting

In addition to the default <Response> element, the <Conference> element must also be nested within the following <Dial> verb. No other elements may be nested within the <Conference> element.

The InboundXML below will start a conference with the name “ZangExampleChat” when the number using the XML is called. The maximum participants allowed in this conference is 5 and pressing * will end this conference.


<Response>
  <Dial>
    <Conference startConferenceOnEnter="true" callbackUrl="http://webhookr.com/conf-callback" hangupOnStar="true" maxParticipants="5">ZangExampleChat</Conference>
  </Dial>
</Response>
                                        

<Dial>

The <Dial> element starts an outgoing dial from the current call. Once the dial is complete, the next element in the InboundXML document will be processed unless the action attribute is set. If the action attribute is set, the result of the dial is submitted as a GET or POST (depending on the method attribute) to the action URL, and the call will continue using the InboundXML in said URL.

By default, the outgoing call will timeout after 30 seconds if it is not answered. However, the timeout attribute can be used to set a custom time. The length of the call is limited by the timeLimit attribute, which is 4 hours (14400 seconds) by default.

Setting the hangupOnStar attribute to ‘true’ will allow the original call to terminate the outgoing call without having to hangup by dialing ‘*’. The original call then continues with the current InboundXML document, or if a URL was passed, the response from the action attribute.

The callerId attribute can be set to any number, and will default to the caller id of the original caller. The number to be dialed should be nested within the <Dial> element. For more options, use the <Number>, <Sip> or <Conference> elements instead of a simple phone number.

Attribute
  • action

    URL where some parameters specific to will be sent for further processing. The calling party can be redirected here upon the hangup of the B leg caller.

  • method

    Method used to request the action URL. Default Value: POST. Allowed Value: POST or GET.

  • timeLimit

    The duration in seconds a call made through should occur for before ending. Default Value: 14400. Allowed Value: integer greater than or equal to 1.

  • callerId

    Number to display as calling. Defaults to the ID of phone being used.

  • hideCallerId

    Boolean value specifying if the caller ID should be hidden or not. Default Value: false. Allowed Value: true or false.

  • dialMusic

    URL to an InboundXML document to be executed in place of the call ringtone (a or would be appropriate in this document).

  • callbackUrl

    URL requested when the dialed call connects and ends. Note that this URL only receives parameters containing information about the call, the call does not execute XML given as a callbackUrl.

  • callbackMethod

    Method used to request the callback URL. Default Value: POST. Allowed Value: POST or GET.

  • confirmSound

    Boolean value specifying if a sound should play when dial is successful. Defaults Value: false.

  • digitsMatch

    Specifies digits that Zang should listen for and send to the callbackUrl if a caller inputs them. Separate additional digits or digit patterns with a comma. Allowed Value: Pattern made up of the digits 0-9, #, or *.

  • straightToVm

    Boolean value specifying if call should be redirected to voicemail immediately. Note: only works if dialing TO a mobile number. Default Value: false. Allowed Value: true or false.

  • heartbeatUrl

    A URL Zang can request every 60 seconds during the call to notify of elapsed time and pass other general information.

  • hearbeatMethod

    Method used to request the heartbeatUrl. Default Value: POST. Allowed Value: POST or GET.

  • ifMachine

    Specifies the number to list the call as forwarded from.

  • ifMachineUrl

    The URL Zang will redirect to if a voicemail machine is detected while the ifMachine=“redirect” attribute is set.

  • ifMachineMethod

    The method used to request the ifMachineUrl. Default Value: POST. Allowed Value: POST or GET.

  • record

    Specifies if this call should be recorded. Allowed positive values are "true" - any other value will default to "false".

  • recordDirection

    Specifies which stream of call audio to record. “in” to record the incoming caller audio, “out” to record the outgoing caller audio, or “both” to record all audio on the call. “out” audio can only be captured if an outbound is performed during the call. “in” blocks any subsequent InboundXML elements until the inbound audio recording is finished (via finishOnKey or timeout). Default Value: both. Allowed Value: in, out, both.

  • recordCallbackUrl

    URL where some parameters specific to the recording will be sent for further processing.

The following <Dial> specific parameters are also forwarded to the callbackUrl and action URL.

Attribute
  • DialCallStatus

    Status of the dial. May be completed, busy, no-answer, failed, or canceled.

  • DialCallSid

    The call sid of the outgoing dial.

  • DialCallDuration

    The length of the dialed call in seconds.

The following parameters are also forwarded to the heartbeatUrl.

Attribute
  • ElapsedTime

    The elapsed time of the dialed call in seconds.

  • AnsweredTime

    The date and time the call was answered.

An Error Had Occurred

If for any reason you hear "An Application Error Has Occurred" message playing to you while you are on the call that means that your InboundXML document contains issues. In order to resolve issues, please visit Notifications > Developers located in your Zang dashboard.

Nesting

In addition to the default <Response> element, the <Dial> element cannot be nested within any other verbs besides the default <Response> element. The <Number>, <Conference>, <User> and <Sip> elements can be nested within the <Dial> element.

The InboundXML below will dial the nested number and send the action parameters to the given URL.


<Response>
    <Dial callbackUrl="http://webhookr.com/zang-inbound-dial-example" method="GET">(555)555-5555</Dial>
</Response>
                                        

<Gather>

The <Gather> element allows callers to input digits to the call using their keypads which are then sent via POST or GET to a URL for further processing. There are many ways to get creative with <Gather> but its most common use case is in creating IVR menus. This is accomplished by nesting prompts for input from the caller using the <Say> or <Play> elements.

By default, an unlimited number of digits can be gathered. <Gather> will timeout after 5 seconds or once the ‘#’ key is pressed. The gathered digits will then be submitted to the current InboundXML document. This default behavior of <Gather> can be altered using the provided element attributes.

Attribute
  • input

    A list of inputs that Zang should accept. Default value is "dtmf". Accepted values are "dtmf", "speech", or "speech dtmf"

  • hints

    A set of words or phrases that Zang should listen for. Commas should seperate words.

  • language

    BCP-47 language tags. Defaults to en-US

  • action

    URL where the flow of the call and the gathered digits will be forwarded to (if digits are input).

  • method

    Method used to request the action URL. Default value is POST. Available methods are GET and POST.

  • timeout

    The number of seconds should wait for digits to be entered before requesting the action URL. Timeout resets with each new digit input. Default value is 5 seconds. Timeout accepts any integer greater than or equal to 0.

  • finishOnKey

    The key a caller can press to end the . Default value is #. Acceptable values are digits from 0 to 9, # or *

  • numDigits

    The maximum number of digits to . Default value is set to no limit. Acceptable value is any integer greater than or equal to 0.

In addition to the default voice request parameters, the following gather-specific parameter is also forwarded to the action URL.

Parameter
  • Digits

    All gathered digits, not including finishOnKey.

  • SpeechResult

    All captured speech to text words

Languages

Bellow you can find the list of all supported languages

Afrikaans (South Africa)af-ZA
Amharic (Ethiopia)am-ET
Armenian (Armenia)hy-AM
Azerbaijani (Azerbaijani)az-AZ
Indonesian (Indonesia)id-ID
Malay (Malaysia)ms-MY
Bengali (Bangladesh)bn-BD
Bengali (India)bn-IN
Catalan (Spain)ca-ES
Czech (Czech Republic)cs-CZ
Danish (Denmark)da-DK
German (Germany)de-DE
English (Australia)en-AU
English (Canada)en-CA
English (Ghana)en-GH
English (United Kingdom)en-GB
English (India)en-IN
English (Ireland)en-IE
English (Kenya)en-KE
English (New Zealand)en-NZ
English (Nigeria)en-NG
English (Philippines)en-PH
English (South Africa)en-ZA
English (Tanzania)en-TZ
English (United States)en-US
Spanish (Argentina)es-AR
Spanish (Bolivia)es-BO
Spanish (Chile)es-CL
Spanish (Colombia)es-CO
Spanish (Costa Rica)es-CR
Spanish (Ecuador)es-EC
Spanish (El Salvador)es-SV
Spanish (Spain)es-ES
Spanish (United States)es-US
Spanish (Guatemala)es-GT
Spanish (Honduras)es-HN
Spanish (Mexico)es-MX
Spanish (Nicaragua)es-NI
Spanish (Panama)es-PA
Spanish (Paraguay)es-PY
Spanish (Peru)es-PE
Spanish (Puerto Rico)es-PR
Spanish (Dominican Republic)es-DO
Spanish (Uruguay)es-UY
Spanish (Venezuela)es-VE
Basque (Spain)eu-ES
Filipino (Philippines) fil-PH
French (Canada)fr-CA
French (France)fr-FR
Galician (Spain)gl-ES
Georgian (Georgia)ka-GE
Gujarati (India)gu-IN
Croatian (Croatia)hr-HR
Zulu (South Africa)zu-ZA
Icelandic (Iceland)is-IS
Italian (Italy)it-IT
Javanese (Indonesia)jv-ID
Kannada (India)kn-IN
Khmer (Cambodian)km-KH
Lao (Laos)lo-LA
Latvian (Latvia)lv-LV
Lithuanian (Lithuania)lt-LT
Hungarian (Hungary)hu-HU
Malayalam (India)ml-IN
Marathi (India)mr-IN
Dutch (Netherlands)nl-NL
Nepali (Nepal)ne-NP
Norwegian Bokmål (Norway)nb-NO
Polish (Poland)pl-PL
Portuguese (Brazil)pt-BR
Portuguese (Portugal)pt-PT
Romanian (Romania)ro-RO
Sinhala (Sri Lanka)si-LK
Slovak (Slovakia)sk-SK
Slovenian (Slovenia)sl-SI
Sundanese (Indonesia)su-ID
Swahili (Tanzania)sw-TZ
Swahili (Kenya)sw-KE
Finnish (Finland)fi-FI
Swedish (Sweden)sv-SE
Tamil (India)ta-IN
Tamil (Singapore)ta-SG
Tamil (Sri Lanka)ta-LK
Tamil (Malaysia)ta-MY
Telugu (India)te-IN
Vietnamese (Vietnam)vi-VN
Turkish (Turkey)tr-TR
Urdu (Pakistan)ur-PK
Urdu (India)ur-IN
Greek (Greece)el-GR
Bulgarian (Bulgaria)bg-BG
Russian (Russia)ru-RU
Serbian (Serbia)sr-RS
Ukrainian (Ukraine)uk-UA
Hebrew (Israel)he-IL
Arabic (Israel)ar-IL
Arabic (Jordan)ar-JO
Arabic (United Arab Emirates)ar-AE
Arabic (Bahrain)ar-BH
Arabic (Algeria)ar-DZ
Arabic (Saudi Arabia)ar-SA
Arabic (Iraq)ar-IQ
Arabic (Kuwait)ar-KW
Arabic (Morocco)ar-MA
Arabic (Tunisia)ar-TN
Arabic (Oman)ar-OM
Arabic (State of Palestine)ar-PS
Arabic (Qatar)ar-QA
Arabic (Lebanon)ar-LB
Arabic (Egypt)ar-EG
Persian (Iran)fa-IR
Hindi (India)hi-IN
Thai (Thailand)th-TH
Korean (South Korea)ko-KR
Chinese, Mandarin (Traditional, Taiwan)cmn-Hant-TW
Chinese, Cantonese (Traditional, Hong Kong)yue-Hant-HK
Japanese (Japan)ja-JP
Chinese, Mandarin (Simplified, Hong Kong)cmn-Hans-HK
Chinese, Mandarin (Simplified, China)cmn-Hans-CN

Nesting

If nested <Say> or <Play> elements are present, the timeout attribute starts after either the first key to be gathered is pressed or say/play prompt completes. If the <Gather> fails to execute, the very next verb will be executed.

Tips

In addition to the default <Response> element, the <Gather> element cannot be nested within any other verbs besides the default element. The <Say>, <Play>, and <Pause> elements can all be nested within the <Gather> element.

The InboundXML below will prompt the caller to enter a four digit pin and then forward the input digits to the action URL using the GET method.


<Response>
  <Gather method="GET" numDigits="4" finishOnKey="#" action="http://example.com/example-callback-url/say?example=simple.xml">
    <Say>Please enter your 4 digit pin.</Say>
  </Gather>
</Response>
                                        

The InboundXML below will prompt the caller to speak and if hint is matched forward the speech results to the action URL using the GET method.


<Response>
  <Gather input="speech" language="en-US" timeout="10" hints="sales" action="http://example.com/example-callback-url/gather-speech?example=simple.xml">
    <Say>Please say sales for sales.</Say>
  </Gather>
</Response>
                                        

<Hangup>

The <Hangup> element will hangup the current call.

Attribute
  • schedule

    Specifies in seconds when a hangup should occur during a call. Allowed Value: integer greater than or equal to 0

  • reason

    Reason for the hangup. It can be rejected or busy. Default is none.

Schedule Attribute

The schedule Attribute will not keep the call active if there are no elements after hangup. It will terminate the call.

Nesting

In addition to the default <Response> element, the <Hangup> element cannot be nested within any other elements. No other elements may be nested within the <Hangup> element.


<Response>
  <Hangup/>
</Response>
                                        

<Mms>

Zang allows MMS messages to be sent during a call using the <Mms> element. The Mms receiver (to attribute) must be a valid phone number. The sender (from attribute) must be one of your registered Zang numbers. The text of the message should be placed inside the element and can not be longer than 160 characters.

The action attribute can be used to direct the Mms to a new InboundXML document for processing. If directed to a new InboundXML using the action attribute, all InboundXML beneath the <Mms> element in the originating InboundXML document is disregarded. Similarly, the statusCallback attribute is provided to report the outcome of the MMS transmission.

Attribute
  • to

    The phone number that will receive the SMS message. If this parameter is not specified, the SMS will be sent back to the number that made the request to the Zang number’s SMS request URL.

  • from

    The number that will display as sending the SMS message. This should be one of your Zang numbers. If this parameter is not specified, the default from number is the Zang number hosting the SMS request URL.

  • action

    URL to direct Zang to once the <Sms> element is executed. Parameters specific to <Sms> are sent here along with the request.

  • method

    Method used to request the action URL. Default Value: POST. Allowed Value: POST or GET.

  • statusCallback

    URL where the status of the SMS can be sent.

  • mediaUrl

    URL of an image to be sent in the message.

The InboundXML below will send an MMS that reads “This is a test MMS from Zang Cloud!” to the number that Zang received the incoming message from.


<Response>
  <Mms From="{{To}}" To="{{From}}" mediaUrl="https://tinyurl.com/lpewlmo">This is a test MMS from Zang Cloud!</Mms>
</Response>
                                        

<Number>

The <Number> element must be nested within the <Dial> element. <Number> can be used to dial multiple phones simultaneously by using additional <Number> elements. If multiple <Number> elements are used to specify additional calls, the first call to answer is connected, and the rest of the outgoing calls are canceled. <Number> can also be used to send DTMF tones to called parties with the sendDigits attribute.

Attributes
  • sendDigits

    Specifies which DTMF tones to play to the called party. w indicates a half second pause.

Nesting

In addition to the default <Response> element, the <Number> element must also be nested within the <Dial> verb. No other elements may be nested within the <Number> element.

The InboundXML below will dial the nested number. When the call connects it will wait one second before sending the digits “12” to the call and then wait a half second before sending the digits “3221” to the call.


<Response>
  <Dial>
    <Number sendDigits='ww12w3221'>(555)555-5555</Number> 
  </Dial>
</Response>
                                        

<Pause>

The <Pause> element will pause the call for the number of seconds set by the length attribute.

Attribute
  • length

    The length in seconds the pause should be. Default Value: 1. Allowed Value: integer greater than 0, less than 99999

Nesting

In addition to the default <Response> element, the <Pause>*element can also be nested within the <Gather> verb. No other elements may be nested within the <Pause> element.

The InboundXML below will say “hello.” and then pause for 5 seconds before saying “Are you still there?”.


<Response>
  <Say>Hello.</Say>
    <Pause length='5'/>
  <Say>Are you still there?</Say>
</Response>
                                        

<Ping>

The <Ping> element is provided as a flexible way to send the default voice request parameters to a URL during a call. The URL to ping is nested within the opening and closing tags of this element.

Attribute
  • method

    Method used to request ping url. Default Value: POST. Allowed Value: POST or GET.

Nesting

In addition to the default <Response> element, the <Ping> element cannot be nested within any other elements. The <Ping> element cannot nest any other elements within itself. It must only nest the URL which is to be requested.


<Response>
  <Say>Pinging!</Say>
    <Ping>http://webhookr.com/ping-test</Ping>
</Response>
                                        

<Play>

The <Play> element plays an audio file for the caller. The content nested within the <Play> element should be the URL of an audio file. Valid audio file formats are: mp3, wav, gsm, aif.

Attribute
  • loop

    The amount of times the should be repeated. 0 indicates an infinite loop. The default value is 1. Allowed values are integers greater than or equal to 0.

Nesting

In addition to the default <Response> element, the <Play> element can also be nested within the <Gather> verb. The <Play> element cannot nest any other elements within itself. It must only nest the URL or tone stream which will be played to the caller.

Tone Stream

In addition to URLs, the <Play> element can also nest tone_stream for producing different tonal values. After a required syntax of “://%”, tone_stream takes a few parameters to define the tone in the following order: (tone duration, pause duration, tone frequency, [additional frequencies to be combined]).

All durations are in milliseconds, so if a 1 second tone with a 2 second pause between is desired, the first and second parameter values would have to be 1000 and 2000. All tone frequencies are in Hz. For the frequency in Hz of common tones used in current phone systems, see this ITU document.

Tips

Setting the loop value to 0 indicates an infinite loop. This will cause the audio to repeat to the caller until the call is hung up. Quality of the audio may change so it is playable over the telephone network. Higher quality audio files will take longer to play and may even sound worse than lower quality files that degrade less when transcoded to the required format. Additional tone stream frequencies are additive so some knowledge of ring modulation may be useful when creating combinations. Looping of tones can also be achieved alternatively by adding L=; before the % or ;loops= after the parameters. Note that indefinite looping using these nested formats can only be specified by setting loops= -1, rather than 0 as when using the Play loop attribute.

The following plays a dial tone:


<Response>
    <Play loop='100'>tone_stream://%(10000,0,350,440)</Play>
</Response>
                                        

The following plays a busy signal:


<Response>
    <Play loop='100'>tone_stream://%(500,500,480,620)</Play>
</Response>
                                        

The following plays a ringback tone:


<Response>
    <Play loop='100'>tone_stream://%(2000,4000,440,480)</Play>
</Response>
                                        

The following will play the mp3 audio to the caller:


<Response>
    <Play>http://techslides.com/demos/samples/sample.mp3</Play>
</Response>
                                        

<PlayLastRecording>

The <PlayLastRecording> element is used to play back recorded audio to callers. It is especially useful when callers are creating recordings in an IVR which require confirmation before continuing (voicemail greeting creation, account access via voice, etc.)

Element Attributes

The <PlayLastRecording> element does not currently have any attributes.

Recording Background

Recording background attribute needs to be set to false in order for it to work.

Nesting

In addition to the default <Response> element, the <PlayLastRecording> element cannot be nested within any other verbs besides the default element. The <PlayLastRecording> element cannot nest any other elements within itself.

The InboundXML below will record the audio on a call until the # key is pressed, and then play that recorded audio back to the caller.


<Response>
  <Say>Press the pound key when you are finished recording.</Say>
    <Record background="false" action="http://foo-url.com" direction="in" playBeep="True" finishOnKey="#"/>
  <Say>Here is your recording!</Say>
 <PlayLastRecording/>
</Response>
                                        

<Record>

The <Record> element is used to record audio during a call. It can occur anywhere within an InboundXML document but will only begin recording once it has been reached. This means, it would have to be the first element after <Response> for the entire call to be recorded. When the recording is complete, a URL of the recorded audio is created and submitted as a GET or POST to the action URL.

Similar to the <Gather> element, a timeout value sets how much silence to allow before the recording ends, maxLength sets how long the recording may be, and the finishOnKey is used to set which keys will end the recording. By default, the action and method specify that <Record> should make a POST to the URL of the current InboundXML document.

Note: no more than than 5 recordings may be attached to a call

Attribute
  • action

    URL where some parameters specific to will be sent for further processing.

  • method

    Method used to request the action URL. Default value is POST. Available values are POST and GET.

  • timeout

    The number of seconds should wait during silence before ending. Default timeout value is 5 seconds. Valid value is integer greater than or equal to 0.

  • finishOnKey

    The key a caller can press to end the . Default value is #. Allowed values are digits from 0 to 9, # or *.

  • maxLength

    The maximum length in seconds a recording should be. Default Value: 3600. Allowed Value: integer greater than or equal to 0

  • transcribe

    Boolean value specifying if the recording should be transcribed. Default Value: false. Allowed Value: true or false.

  • transcribeQuality

    Specifies the quality used to process the transcription. Default Value: autoAllowed Value: auto or hybrid.

  • transcribeCallback

    A URL some parameters regarding the transcription will be passed to once it is completed. Allowed Value: Valid URL.

  • playBeep

    Boolean value specifying if a beep should be played when the recording begins. Default Value: false. Allowed Value: true or false.

  • direction

    Specifies which stream of call audio to record. “in” to record the incoming caller audio, “out” to record the out going caller audio, or “both” to record all audio on the call. “out” audio can only be captured if an outbound Dial is performed during the call. “in” blocks any subsequent XML elements until the inbound audio recording is finished (via finishOnKey or timeout). Default Value: both. Allowed Value: in, out, both.

  • fileFormat

    The recording file format. Can be mp3 or wav. Default is mp3. Default Value: mp3. Allowed Value: mp3 or wav

  • background

    Begin recording the call while continuing the execution of any other present InboundXML in the background (true) or block the execution of subsequent InboundXML until the record element finishes (via finishOnKey or timeout). Note that the timeout, finishOnKey, and playBeep attributes have no effect when the background is set to true. Default Value: true. Allowed Value: true or false

  • trimSilence

    Trims all silence from the beginning of the recording. Allowed values are "true" or "false" - any other value will default to "false".

The following recording specific parameters are also forwarded to the action URL.

Attribute
  • Digits

    The key used to end the recording.

  • RecordingDuration

    The length of the recording in seconds.

  • RecordingSid

    Unique recording identifier.

  • RecordingUrl

    A URL leading to an audio file of the recording.

  • RecordingInterference

    Status if we detected any interference during recording. Can be true or false.

The following recording transcription specific parameters are also forwarded to the transcribeCallback URL.

Parameter
  • Duration

    The duration of the recording that was transcribed.

  • Price

    The cost of the transcription.

  • TransactionStatus

    The status of the transcription.

  • TranscriptionSid

    An alphanumeric string identifying the transcription.

  • RecordingUrl

    A URL leading to an audio file of the recording.

  • TranscriptionUrl

    A URL containing the transcription.

  • TranscriptionText

    The text of the transcription.

Nesting

In addition to the default <Response> element, the <Record> element cannot be nested within any other verbs besides the default <Response> element. The <Record> element cannot nest any other elements within itself.

The InboundXML below will prompt the caller for their name and then forward the recorded name to the action URL using the POST method.


<Response>
  <Say>Please state your name.</Say>
    <Record background="false" action="http://webhookr.com/zang-inboundxml-recording-action-example" method="POST" finishOnKey="#"/>
</Response>
                                        

<Redirect>

The <Redirect> element directs the call to another InboundXML document. The URL of the InboundXML document is nested within the <Redirect> element, and the method attribute sets if the request will be a GET or POST. In addition to the default voice request parameters, the parameter UrlBase will also be forwarded when the redirect request is made. UrlBase points to the base InboundXML document where the <Redirect> occurred.

Attribute
  • method

    Method used to request the InboundXML document the call is being redirected to. Default Value: POST. Allowed Value: POST or GET.

Nesting

In addition to the default <Response> element, the <Redirect> element cannot be nested within any other elements. The <Redirect> element cannot nest any other elements within itself. It must only nest the URL that the call should be redirected to.

The InboundXML below will say “You will now be redirected.” and then redirect the call to the given URL. The second <Say> will never execute.


<Response>
  <Say>You will now be redirected.</Say>
    <Redirect method="POST">http://example.com/rest.xml</Redirect>
  <Say>You will never hear this.</Say>
</Response>
                                        

<Reject>

The <Reject> element will reject an incoming call. In order to prevent Zang from answering the call, the '<Reject>' must be the first element in your InboundXML document. The reason attribute will determine if the caller hears a busy signal or a not-in-service message.

Attribute
  • reason

    This allows you to define why the call was rejected. Default Value: rejected. Allowed Values: busy or rejected.

Nesting

In addition to the default <Response> element, the <Reject> element cannot be nested within any other elements. Additionally, no other elements may be nested within the <Reject> element.

The InboundXML below will reject the call and set the reason as “Busy”.


<Response>
  <Reject reason="busy"/>
</Response>
                                        

<Say>

The <Say> element reads text to the caller using our text-to-speech engine. The current version of our <Say> element supports different options for voices, languages, and genders.

Attribute
  • voice

    The gender of the voice that will speak the text. Allowed values are "man" or "woman". The default value is "woman".

  • language

    The language used to speak the text.

  • loop

    The amount of times the text should be repeated. Allowed values are any integer greater than or equal to 0. "0" indicates an infinite loop.

Supported Languages

The following language values are currently supported. The default value is en-us

  • cy-gb

    Welsh

  • da-dk

    Danish

  • de-de

    German

  • en-au

    Australian English

  • en-gb

    British English

  • en-gb-wls

    Welsh English

  • en-in

    Indian English

  • en-us

    US English

  • es-es

    Castilian Spanish

  • es-us

    US Spanish

  • fr-ca

    Canadian French

  • fr-fr

    French

  • is-is

    Icelandic

  • it-it

    Italian

  • ja-jp

    Japanese

  • nb-no

    Norwegian

  • nl-nl

    Dutch

  • pl-pl

    Polish

  • pt-br

    Brazilian Portuguese

  • pt-pt

    Portuguese

  • ro-ro

    Romanian

  • ru-ru

    Russian

  • sv-se

    Swedish

  • tr-tr

    Turksih

Nesting

In addition to the default <Response> element, <Say> can be nested within a <Gather>. Nothing can be nested inside <Say> except the text to be read to the caller.

Text Size

The maximum text size is 4kb. Commas and periods will cause pauses. may speak things such as abbreviations or times differently than you expect so be sure to double check for correct pronunciation.

This InboundXML will repeat “Hello, my name is Michael.” in a man’s voice until the caller hangs up.


<Response>
    <Say voice="man" language="en-us" loop="0">Hello, my name is Michael.</Say>
</Response>
                                        

This InboundXML will repeat “Buenos dias, my nombre is Carolina.” in a woman's voice until the caller hangs up.


<Response>
  <Say voice="woman" language="es-us" loop="0">Buenos dias, mi nombre es Carolina.</Say>
</Response>
                                        

<Sip>

The <Sip> element is nested within the <Dial> element, and is used to call SIP addresses. The desired SIP address to call is nested within <Sip></Sip>, just as with a number when using the <Number> element. However, the opening and closing sip tags (<Sip></Sip>) may be omitted completely by simply prefixing the desired SIP address with “sip:” when using it within the <Dial> element. For example: <Dial>sip:username@domain.com<Dial>

If multiple <Sip> elements are used, the first call to answer is connected and the rest of the outgoing calls are canceled.

Attribute
  • username

    If provided, will be passed along as sip authentication username.

  • password

    If provided, will be passed along as sip authentication password.

Nesting

In addition to the default <Response> element, the <Sip> element must be nested within the <Dial> verb. The <Sip> element cannot nest any other elements within itself. It must only nest the SIP address which is to be called.

The InboundXML below will call the nested SIP account.


<Response>
 <Dial>
  <Sip username="{someusername}" password="{somepassword}">username@domain.com</Sip>
 </Dial>
</Response>
                                        

<Sms>

Zang allows SMS messages to be sent during a call using the <Sms> element. The SMS receiver (to attribute) must be a valid phone number. The sender (from attribute) must be one of your registered Zang numbers. The text of the message should be placed inside the element and can not be longer than 160 characters.

The action attribute can be used to direct the SMS to a new InboundXML document for processing. If directed to a new InboundXML using the action attribute, all InboundXML beneath the <Sms> element in the originating InboundXML document is disregarded. Similarly, the statusCallback attribute is provided to report the outcome of the SMS transmission.

Attribute
  • to

    The phone number that will receive the SMS message. If this parameter is not specified, the SMS will be sent back to the number that made the request to the Zang number’s SMS request URL.

  • from

    The number that will display as sending the SMS message. This should be one of your Zang numbers. If this parameter is not specified, the default from number is the Zang number hosting the SMS request URL.

  • action

    URL to direct Zang to once the element is executed. Parameters specific to are sent here along with the request.

  • method

    Method used to request the action URL. Default Value: POST. Allowed Value: POST or GET.

  • statusCallback

    URL where the status of the SMS can be sent.

In addition to the default voice request parameters, the following parameters are forwarded to the action URL.

Parameter
  • SmsSid

    The Sid Zang has assigned for the SMS message.

  • SmsStatus

    The current status of the SMS message. Either sent or failed.

  • Body

    The text of the SMS message you want to send. 160 character limit.

Nesting

In addition to the default <Response> element, the <Sms> element cannot be nested within any other verbs. The <Sms> element cannot nest any other elements within itself. It must only nest the text which is to be sent in the message.

Rate Limiting

By default, there is a 1 SMS per second rate limit on SMS messages. If you need to send SMS messages at a higher rate, please contact us.

Sms Filtering

All Zang numbers which haven't yet had a user supplied SMS request URL set are provided with the following default SMS filtering behaviors:

  • If a recipient replies to a Zang SMS message with STOP, QUIT, or UNSUBSCRIBE, they will no longer receive SMS messages from that number.
  • The keywords START, YES, or SUBSCRIBE revert this blocking.
  • HELP informs the recipient of the above keywords.

Once an SMS request URL is set, this default behavior stops, allowing developers to implement their own SMS filtering solution.

The InboundXML below will say “I will now send an SMS!” and then send an SMS that reads “Test message sent from Zang!” to the specified from number.


<Response>
  <Sms from="{{To}}" to="{{From}}">This is a test message sent from Zang Cloud</Sms>
</Response>