Tropo is part of CiscoLearn More

message

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, only the first number in the array will actually receive the text message. In order to send an SMS message, you must have an SMS-enabled phone number attached to the application.

Note
To 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

Object
(Required)
Default: 
undefined

This determines what is played or sent to the caller. This can be a single object or an array of objects.

to

String or Array
(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 (+14075551212). 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: "+611300975708;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. For SMS, only the first destination phone number will actually receive the text message.

answerOnMedia

Boolean
Default: 
false

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

String
Default: 
VOICE

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

String

The callerID passed to the call recipient. Phone numbers with formatting (for example +1 415-555-1212) will have formatting removed by Tropo prior to dialing. For incoming calls that you transfer, if you do not specifically define anything for 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. For SMS, it must be a number assigned to your account. See Tips for Setting Valid Caller ID for detailed rules about Caller ID.

name

String
(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

String

The name of the network being used for this session. For voice, this can be 'PSTN" or "SIP". 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

Boolean
Default: 
true

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

Float
Default: 
30.0

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

String
Default: 
allison

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).

promptLogSecurity

String
Default: 
none

Controls whether Tropo logs the text to speech string used by the method. Possible values are "none" (the default) and "suppress", which disables output logging for this method. See Log Suppression for complete details and examples.

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