Tropo WebAPI Development Guide

{"call":} object

Initiates an outbound call or a text conversation. Note that this verb is only valid when there is no active WebAPI call and the maximum session time with Tropo is 2 hours, so the maximum time a call can be connected is also 2 hours.

For voice calls, destinations are specified using a URL format. Supported formats include:

tel: Phone Number - must be proceeded by a + and the country code (ie - +14155551212 for a US #)
sip: SIP protocol address

When this method is called:

A new call is initiated to the destination specified by the "to" parmeter.
If "from" is specified then it will be used as the callerId when making the call. Otherwise, the callerId will be "unknown".
If answerOnMedia is true, the audio from the new call is connected immediately.
The system waits for an answer or other event from the new call up to the specified timeout.
If the call successfully completes within the timeout the call action is considered complete and Tropo will continue to the next action.
If the call fails due to the timeout or network issue the call action is considered incomplete and the state of the call will be FAILED.

Additional dial options:

postd - The DTMF digits to dial after the call has connected
pause - The amount of time to wait before issuing the digits after the call is connected; this exists to allow for large values of time to be defined
p - Defines a one second pause
Example: "+14155551212;postd=1234pp56;pause=5s". This will dial 1234 five seconds after connecting to the phone number, pause for an additional 2 seconds (pp) and then dial 56. This example will do the same thing, though looks a little more complex: "+14155551212;postd=ppppp1234pp56" 'ms' is also supported, so you could define 5000ms instead of 5s.

For SMS and IM conversations, the "to" represents the SMS enabled phone number or IM username. Make sure you supply the appropriate network so Tropo knows how to route this message. While you can define multiple SMS destinations as an array, it won't break the application, only the first destination phone number will actually receive the text message. In order to send an SMS message, you must have a U.S. or Canadian phone number attached to the application.

Note that before you can send to non-U.S. destinations, both for voice and SMS, you need to contact support first to get international dialing enabled. This can be done via an account ticket or via support@voxeo.com.

usage

{ "call": {
    "to": String or Array,
    "allowSignals": String or Array,
    "answerOnMedia": Boolean,
    "channel": string,
    "from": String,
    "headers": Object,
    "name": String,
    "network": String,
    "recording": Array or Object,
    "required": Boolean,
    "timeout": Float } }

fields

to	Data Type: String or Array	Default: (none)	Required
	The destination to make a call to or send a message to. This may currently take one of the following forms: +14155551212 - The telephone number to dial with a '+' and country code. For US numbers, the country code can be omitted. tel:+14155551212 - The telephone number with a tel: prefix sip:username@doamin.com - The SIP URL to dial username - The IM or Twitter user name. Some IM networks like Google Talk and Live Messenger include a domain as part of the user name. For those networks, include the domain: username@gmail.com When making a voice call, you can specify dialing options as part of the number: postd - The DTMF digits to dial after the call has connected pause - The amount of time to wait before issuing the digits after the call is connected Example: "+14155551212;postd=1234pp56;pause=1000ms". This will dial 1234 one second after connecting to the phone number, pause for an additional 2 seconds (pp) and then dial 56 You can also list multiple phone numbers or SIP addresses (or both!) as an array for a voice call; whichever destination picks up first, wins.
allowSignals	Data Type: String or Array	Default: * (any signal)	Optional
	This parameter allows you to assign a signal to this function. Events from the Tropo REST API with a matching signal name will "interrupt" the function (i.e., stop it from running). If it already ran and completed, your interrupt request will be ignored. If the function has not run yet, the interrupt will be queued until it does run. By default, allowSignals will accept any signal as valid; if you define allowSignals as "", it defines the function as "uninterruptible". You can also use an array - the function will stop if it receives an interrupt signal matching any of the names in the array.
answerOnMedia	Data Type: Boolean	Default: false	Optional
	If this is set to true, the call will be considered "answered" and audio will begin playing as soon as media is received from the far end (ringing / busy signal / etc).
channel	Data Type: string	Default: voice	Optional
	This defines the channel used to place new calls. For phone calls it is "VOICE", for SMS and instant messaging it is "TEXT".
from	Data Type: String	Default: (none)	Optional
	If multiple contact methods for a given network are attached to an application, this field allows you to specify which one it comes from. For example, if you have two phone numbers, setting this field would allow you to specify the caller ID that appears to the recipient. For voice calls, this can be any valid phone number; for SMS it needs to be a number assigned to your account. For IM, there's no need to set a specific value for `from` - it will always need to match the IM account associated with your application, which is what Tropo uses by default anyways.
headers	Data Type: Object	Default: "" (undefined)	Optional
	This contains the Session Initiation Protocol (SIP) Headers for the current session. This is advanced network information.
name	Data Type: String	Default: "" (undefined)	Optional
	This is the key used to identify the result of an operation, so you can differentiate between multiple results. As an example, if you asked the user for their favorite color, you could set the name value as 'color' while the returned value might be 'blue'. Not particularly useful if there's only one result returned, but if there are multiple results it helps to determine which result belonged to which operation.
network	Data Type: String	Default: "" (undefined)	Optional
	The name of the network being used for this session. For voice, this can be 'PSTN", "SIP", "SKYPE" or "INUM". For text, this can be "AIM", "GTALK", "JABBER", "MSN", "SMS", "TWITTER" or "YAHOO". Note that SKYPE is not a valid value for outbound calls, it will only display if you're recording the network for an inbound call. Network is used mainly by the text channels; for IM network, you must have an IM account linked in your app. For example, if you try to send to AIM when you don't have an AIM username included in your app, your app will fail. TWITTER is a valid network, but as Twitter is currently only supported for inbound applications, it would not be used here.
recording	Data Type: Array or Object	Default:	Optional
	This is a shortcut to allow you to start call recording as soon as the call is answered. This parameter is only useful on voice calls and is ignored on text channels. Review the included example below: {"tropo":[ { "call":{ "to":"+14075551212", "recording":{"url":"http://example.com/recording.php"} } }, { "ask":{ "say":{"value":"Please say your account number"}, "choices":{"value":"[5 DIGITS]"} } } ] } See startRecording for a complete list of properties.
required	Data Type: Boolean	Default: true	Optional
	This determines whether Tropo should move on to the next verb; if required is set to 'true', Tropo will only move on to the next verb if the current operation completely successfully.
timeout	Data Type: Float	Default: 30.0	Optional
	The amount of time, in seconds, to wait for an answer before returning to the application. The maximum value for this parameter is 2 hours and it's recommended for outbound voice calls that this be set somewhere between 50-90 seconds. This ensures if one carrier cannot connect the call for whatever reason, there is time to try it on another carrier.

code samples

Example making a phone call to an array of numbers

{"tropo":[
      {"call":{
            "to":[
               "+14155551212",
               "+15105551212"
            ]}
      },
      {"say":[
            {"value":"Hello, you were the first to answer."}
      ]}
]}

Example sending an SMS

{"tropo":[
      {"call":{
         "to":"+14075550100",
         "network":"SMS"
          }
      },
      {"say":{"value":"Tag, you're it!"}}
]}

additional links

none

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page