call() method

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.

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 specified "destination"
  • If it's a voice call and multiple phone numbers/SIP addresses are defined as an array, whichever destination picks up first, wins
  • If callerId is specified then it will be used 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 onAnswer event will fire and an "answer" event will be returned.
  • If the call fails before the timeout, onCallFailure will fire and a callFailure event will be returned.
  • If the call fails due to the timeout elapsing, onTimeout will fire and a timeout event will be returned.

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 conversations, the destination 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 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.

Check out the examples for Making an Outgoing Call and Sending Text Messages for more information. If you want to pass parameters as global variables when a call is launched, you can also check out this example or this one.

Parameters

destination
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.
  • tel:+14155551212 - The telephone number with a tel: prefix
  • sip:username@domain.com - The SIP URI to dial

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

As mentioned in the main description, 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.

Named Parameters

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 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). If using Python, make sure to use True and False instead of true and false. Note that since the call is considered "answered", the onTimeout event will never fire and the onAnswer event will fire on first ring. Also, answerOnMedia will trigger the start of billing, so you may encounter a charge even if the call never connects.

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

channel
Data Type: 
String
Default: (none) Optional

Channel tells Tropo whether the call is "voice" or "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.

headers
Data Type: 
Object
Default: (none) Optional

This is a hash containing the SIP headers used when making the call; this parameter only applies when making SIP calls.

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'. It can be accessed through event.value.userType ($event->value->userType if using PHP).

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.

onAnswer
Data Type: 
Function
Default: (none) Optional

This registers an event handler that fires when the call is answered.

onBusy
Data Type: 
Function
Default: 
undefined
Optional

Fires if the called address returns busy (busy signal for phone calls or a 480, 486, or 600 response for SIP).

onCallFailure
Data Type: 
Function
Default: (none) Optional

This event fires when an outbound call or a transfer fails, often due to an incorrect or disconnected destination phone number.

onError
Data Type: 
Function
Default: (none) Optional

This registers an event handler that fires when a system error (a non-user error) occurs during audio playback.

onSignal
Data Type: 
Function
Default: (none) Optional

This specifies a callback function to run if the function is interrupted by a signal. Review documentation on sending interrupts here.

onTimeout
Data Type: 
Function
Default: (none) Optional

This event fires when the call is not answered within a specified period of time.

recordFormat
Data Type: 
String
Default: 
audio/wav
Optional

The audio format used for the recording; values can be 'audio/wav', 'audio/mp3' or 'audio/au'.

recordMethod
Data Type: 
String
Default: 
POST
Optional

When submitting recordings via HTTP, this parameter determines the method used. This can be 'POST' (which is the default) or 'PUT' . When sending via POST, the name of the form field is "filename".

recordURI
Data Type: 
String
Default: (none) Optional

The FTP or HTTP URL to send the recorded audio file. When sending via POST, the name of the form field is "filename".

Please note this needs to be a fully realized URL, i.e. "http://website.com/folder/subfolder" vs "/folder/subfolder". If you don't have a complete URL, the file won't send at all or at the very least won't send correctly (0 byte file and similar unusable content).

timeout
Data Type: 
Float
Default: 
30.0
Optional

Timeout only applies to the voice channel and determines the amount of time Tropo will wait - in seconds - for the call to be answered before giving up. 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.

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

  call(['+14155550100','+13865550100'], {
   timeout:120,
   callerID:'14075550100',
      onAnswer: function() {
       say("Tag, you're it!");
       log("Obnoxious call complete");
   },
   onTimeout: function() {
       log("Call timed out");
   },
   onCallFailure: function() {
       log("Call could not be completed as dialed");
   }
});  
call ['+14155550100','+13865550100'], {
   :timeout => 120,
   :callerID => '14075550100',
   :onAnswer => lambda {
       say "Tag, you're it!"
       log "Obnoxious call complete"},
   :onTimeout => lambda {
       say "Call timed out" },
   :onCallFailure => lambda {
       log "Call could not be complete as dialed" }
}
<?php
call(array("+14155550100","+13865550100"), array(
   "timeout" => 120,
   "callerID" => '14075550100',
   "onAnswer" => "answerFCN",
   "onTimeout" => "timeoutFCN",
   "onCallFailure" => "callFailureFCN"
   )
);
function answerFCN($event) {
   say("Tag, you're it!");
   _log("Obnoxious call complete");
}
function timeoutFCN($event) {
   _log("Call timed out");
}
function callFailureFCN($event) {
   _log("Call could not be completed as dialed");
}
?>
call(['+14155550100','+13865550100'], {
   "timeout":120,
   "callerID":'14075550100',
   "onAnswer": lambda event : say("Tag, you're it!") and log("Obnoxious call complete"),
   "onTimeout": lambda event : log("Call timed out"),
   "onCallFailure": lambda event : log("Call could not be completed as dialed")
})
call(['+14155550100','+13865550100'], [
   timeout: 120,
   callerID: '14075550100',
   onAnswer: {
       say("Tag, you're it!")
       log("Obnoxious call complete") },
   onTimeout: {
       log("Call timed out") },
   onCallFailure: {
       log("Call could not be complete as dialed") }
])