Tropo WebAPI Development Guide

{"message":} object

Creates a call, says something and then hangs up, all in one step. This is particularly useful for sending out a quick SMS or IM.

Make sure you have a US phone number attached to your application if you want to send SMS, and/or supply the appropriate network so Tropo knows how to route this message, such as AIM, YAHOO or GTALK.

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

{ "message": {
    "say": Object,
    "to": String or Array,
    "answerOnMedia": Boolean,
    "channel": string,
    "from": String,
    "name": String,
    "network": String,
    "required": Boolean,
    "timeout": Float,
    "voice": String } }

fields

say	Data Type: Object	Default: "" (undefined)	Required
	This determines what is played or sent to the caller. This can be a single object or an array of objects.
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.
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.
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.
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
	This defines, in seconds, how long Tropo should wait for the other party to answer the call. If the timeout is reached and the call has not been answered, the URL specified in your incomplete event handler will be called. The maximum value for this parameter is 2 hours. 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.
voice	Data Type: String	Default: allison	Optional
	Specifies the default voice to be used when speaking text back to a user. A full list of all voices can be found here (there's many, many options).

code samples

Example

{
    "tropo": [
        {
            "message": {
                "say": {
                    "value": "This is an announcement"
                },
                "to": "+13055551212",
                "network": "SMS"
            }
        }
    ]
}

Example

{
    "tropo": [
        {
            "message": {
                "say": {
                    "value": "Remember, you have a meeting at 2 PM"
                },
                "to": "305551212",
                "from": "3055551000",
                "voice": "dave",
                "timeout": 10,
                "answerOnMedia": false,
                "headers": {
                    "foo": "bar",
                    "bling": "baz"
                }
            }
        }
    ]
}

additional links

none

ANNOTATIONS: EXISTING POSTS

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