{"message":} object

This is a shortcut function to create a call or text message, say something, then disconnect - all in one step. This is especially useful when you are on a voice call and want to send a quick text message out.

If message makes a voice call, you can also define multiple phone numbers/SIP addresses for the destination as an array; whichever destination picks up first, wins. While you can define multiple SMS destinations as well, it won't break the application, only the first number in the array 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@tropo.com.

Since Tropo is synchronous, message is a blocking method. This means no other method can run until message is complete.

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

Defines the destination for a call or an SMS. For voice calls, destinations are specified using a URL format. Supported formats include:

  • tel: Phone Number - must be preceded by a + and the country code (+14155551212 for a US #). Phone numbers with formatting (for example +1 415-555-1212) will have formatting removed by Tropo prior to dialing.
  • sip: SIP protocol address, such as sip:123456789@sip.provider.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. 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.

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). answerOnMedia will trigger the start of billing, so you may encounter a charge even if the call never connects.

channel
Data Type: 
String
Default: 
VOICE
Optional

This defines the channel used to place new calls. For phone calls it's "VOICE", for SMS it's "TEXT". This is not a required field and is actually often unnecessary - in most cases, Tropo is able to determine the channel based on the network. Channel is primarily used to split an inbound oriented application into different sets of instructions - one set for any input that comes in via text and a different set for input that comes in over voice.

from
Data Type: 
String
Default: (none) Optional

The callerID passed to the call recipient. For example, if the number 14155551212 called 14075551000, the *1212 number would be the callerID. Phone numbers with formatting (for example +1 415-555-1212) will have formatting removed by Tropo prior to dialing. If you do not specifically define anything for the this field, the callerID of the incoming call will be used.

The callerID can be manually set to a specific number - for voice calls, this can be any valid phone number; including alpha characters is likely to cause the callerID to be rejected or passed through as "Unknown". For SMS, it must be a number assigned to your account.

name
Data Type: 
String
Default: (none) Required

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: (none) Optional

The name of the network being used for this session. For voice, this can be 'PSTN", "SIP", or "INUM". For text, this can be "SMS". This is primarily used to define an SMS application from a voice application, since both call out to phone numbers.

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.

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 are many, many options).

Examples

Example showing an SMS

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

Example with multiple voice oriented options

{
    "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"
                }
            }
        }
    ]
}