Tropo is part of CiscoLearn More


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 (tel:+14155551212 for a US number). Phone numbers with formatting (for example +1 415-555-1212) will have formatting removed by Tropo prior to dialing. The tel: prefix is the default protocol and may be left off.
  • sip: SIP protocol address, such as

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: "+443069990432;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: "+443069990432;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, only the first destination phone number 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.



String or Array

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

Map Parameters


String or Array
* (any signal)

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 an empty string (""), 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.



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.



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



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


Boolean or Hash

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.

For the most accurate results, the "introduction" should be long enough to give Tropo time to detect a human or machine. The longer the introduction, the more time we have to determine how the call was answered. If the introduction is long enough to play until the voicemail "beep" plays, Tropo will have the most accurate detection. It takes a minimum of four seconds to determine if a call was answered by a human or machine, so introductions four seconds or shorter will always return HUMAN.

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



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.



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



This event does not exist in PHP.

The onRinging event is triggered when the far end is ringing. Calls that do not enter a ringing state (for example, a failed call) will not trigger this event. The entire event will execute before other events execute, so for example, a onRinginng that takes a long time to complete may block other events from occurring. As example, if your onRinging event connects to a database and takes several seconds to return, your onAnswer event will not run until onRinging completes and the Call or Transfer function will block until onRinging completes.

For the best user experience, your onRinging event should be very brief, as until it completes, the person will hear silence when they answer the phone. It's possible, if the onRinging event takes a very long time to complete, that the call will have ended during onRinging and subsequent events like onAnswer will throw errors if you attempt to work with a specific call state in these events



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



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



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



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



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



The audio format used for the recording; values can be 'audio/wav', 'audio/mp3' or 'audio/au'. The default is 'audio/wav', but if the recordURI parameter includes a file extension, Tropo will set the appropriate audio type.



For HTTP or S3 recording upload, this parameter determines the method used. To upload to an Amazon S3 bucket, use "s3". For HTTP, this can be 'POST' (which is the default) or 'PUT'. When sending via POST, the file is sent as if you uploaded in a web form with a form field name of "filename".



The S3 Bucket or HTTP URL to send the recorded audio file. When sending via POST, the file arrives as if you had uploaded with an HTML form using a file field named "filename". Accepts SSL URLs as well.

The file will take a few moments to upload to your server. The exact amount of time depends on many factors, including the network connection of your server. If your application needs to play back the audio immediately after recording is completed, the object returned by the record method has a "value" property that contains a url of a temporary local copy of the file. This temporary copy will be deleted as soon as the call ends.

Please note this needs to be a fully qualified URL, i.e. "" 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).

For S3 destinations, include the full URl including the file name, i.e. "". The S3 URL must include the bucket name in the path, rather than as a subdomain, and your URL must match the AWS region your bucket is provisioned in. See Using a S3 bucket for recording uploads for examples.



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


"" (undefined)

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



Configures a URL for a webhook for CDRs to be sent at the completion of the call. This overrides any URLs you have set in your application configuration.



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.



Set by you, an arbitrary label for this call or message. The label you set will appear in your CDR, allowing you to track a CDR by a string you define. See Labeling your CDRs for examples.


  call(['+14155550100','+13865550100'], {
      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" }
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'], {
   "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") }