{"call":} object

Initiates an outbound call or a text conversation. The channel and network parameters determine the type of conversation to initiate. Note that the maximum session time with Tropo is 4 hours, so the maximum time a call can be connected is also 4 hours, and that this verb is only valid when there is no active WebAPI call..

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 this method is called:

  • A new call is initiated to the destination specified by the "to" parameter.
  • 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.

To determine if the call was answered, busy, or failed, see the "disposition" field on the result object.

For SMS , the "to" represents the SMS enabled phone number. 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 addition, in order to send an SMS message you must have a U.S. or Canadian phone number attached to the application.

Please note, you will need to open an account ticket to verify your account prior to making outbound calls or sending outbound messages.

Fields

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.

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

headers
Data Type: 
Object
Default: (none) Optional

This contains the Session Initiation Protocol (SIP) Headers for the current session. This is advanced network information.

machineDetection
Data Type: 
Boolean or Hash
Default: 
false
Optional

If set to false, no machineDetection will be attempted and the field will be Boolean.

If set to true, two parameters are available -- introduction and voice, and the field will be a Hash.

If introduction is set, Tropo plays the TTS string using voice or plays the audio file if a URL is defined (same behavior as say) during this wait. Tropo will not return until introduction is done playing, even if it has determined a human voice or machine response before the introduction is complete.

If you do not include an introduction and machineDetection is true, then Tropo will return as soon as it is confident the answering endpoint is a user or machine. However, this results in silence while Tropo makes the determination. Silence ranges from 1 to 10 seconds.

When the function returns, the returned object will have userType property, which returns 'HUMAN', 'MACHINE' or 'FAX'.

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

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.

voice
Data Type: 
String
Default: 
"" (undefined)
Optional

This sets the voice in a call; all prompt action within the call will inherit the same voice defined here.

Examples

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