Tropo is part of CiscoLearn More

transfer

This will transfer an already answered call to another destination / phone number. The call can be transferred to either a phone number or SIP address, which is set through the '"destination" parameter. This method only applies to voice calls.

When this method is called, the following occurs:

  • The audio file specified in playvalue is played to the existing call. This could be "hold music", a ring-back sound, etc. The audio file is played up to the amount of times defined by playrepeat.
  • While audio is playing, a new call is placed to the specified destination.
  • If multiple phone numbers/SIP addresses are defined as an array, whichever destination picks up first, wins.
  • If callerID is applied, the receiving party sees this number as the calling number.
  • If answerOnMedia is true and the carrier plays a ring tone during transfer, this ring tone will be played instead of the specified playvalue.
  • If the call is not answered prior to the timeout, the timeout event will fire and the transfer will fail.
  • If the call is answered prior to the timeout, the two calls will be connected. This method will not return until one party hangs up or a signal is sent.
  • In the event that the call fails for a reason other than a timeout, a callFailure event will be thrown.

Additional dial options are:

  • 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: "+12125557777;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: "+12125557777;postd=ppppp1234pp56" 'ms' is also supported, so you could define 5000ms instead of 5s.

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

In addition, in order to improve audio quality during a transfer, Tropo will instruct the carriers to connect the audio directly between the caller and the recipient, effectively taking Tropo out of the media path. However, if call recording (either via startCallRecording or the recording option in the call method) is active, the audio will still route through Tropo.

Once the transfer is completed and control is returned back to your Tropo script, we will take the audio back and reconnect it to your Tropo application.

To determine how long a transferred call was ringing and connected, see the duration and connectedDuration properties of the event object.

Note
You will need to open an account ticket to verify your account prior to making outbound calls.

Parameters

destination

String or Array
(Required)

The new destination for the incoming call, specified as a URL in one of two forms:

  • tel: Phone Number - must be preceded by a + and the country code (+14155551212 for a US number, for example). 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.

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
  • p - Defines a one second pause

Example: "+14075551212;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: "+14075551212;postd=ppppp1234pp56" 'ms' is also supported, so you could define 5000ms instead of 5s.

As mentioned in the main description, you can also list multiple phone numbers or SIP addresses (or both!) as an array; whichever destination picks up first, wins.

Map Parameters

allowSignals

String or Array
Default: 
* (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.

answerOnMedia

Boolean
Default: 
false

If set to true, the transfer will be considered "answered" as soon as audio occurs on the call and this the caller on first leg of the transfer will hear the ringing and other audio while the second leg is connected. This means the onConnect event will not run, as by the time the second leg joins, the call is already connected. This also means that timeout and other call events will not run.

callerID

String
Default: 
(none)

The callerID passed to the call recipient. For example, if the number +16505553030 called +611300975708, then +16505553030 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 this field, the callerID of the incoming call will be used.

The callerID can be manually set to any valid phone number; including alpha characters is likely to cause the callerID to be rejected or passed through as "Unknown".

headers

Object

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

interdigitTimeout

Integer

For conference, record and transfer, interdigitTimeout defines how long the user needs to wait - in seconds - before Tropo will recognize another key press. Essentially, this means if a user presses the wrong key to terminate the session (say * instead of #), how long do you want Tropo to wait before letting them try again.

machineDetection

Boolean or Hash
Default: 
False

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

onBusy

Function
Default: 
undefined

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

onRinging

Function

Note
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

onCallFailure

Function

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

onConnect

Function
Default: 
none

This event fires when the destination leg of the transfer answers, but before the two legs are connected to each other. Common use is for "whispers" in a transfer, where you play audio to the recipient before connecting the call (to ask if they want to accept the call, for example). When the function finishes running, the two legs will be connected. You can also hangup() on the second leg to end the transfer without connecting the two legs, something that can be especially useful in call screening. The audio file specified by playvalue will continue playing while the onConnect function runs.

onError

Function

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

onSignal

Function

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

onSuccess

Function

This registers an event handler that fires when a call is successfully completed. This runs after the two parties disconnect, and will only run if the transfer connected, both parties joined, and then then disconnected normally (i.e. not as a result of your code error or a Tropo system failure). For an event handler that runs as soon as the transfer successfully connects to the second party, see onConnect.

onTimeout

Function

This event fires when the person at the other end of the transfer doesn't answer within a specified period of time.

playrepeat

Integer

This defines the total amount of times the audio file specified by playvalue will repeat itself.

playTones

Boolean
Default: 
true

Controls whether or not each party can hear the tone generated when a key on the phone is pressed by the other party.

playvalue

String

The audio file specified by this parameter will be played to the existing call. This could be "hold music", a ring-back sound, etc. Note that this file needs to be an absolute reference as opposed to a relative reference - i.e. if you host a file on our servers, it would need to be http://hosting.tropo.com/12345/www/audio/hold_music.mp3, not just hold_music.mp3. For more information, check out Hosting Audio Files.

terminator

String
Default: 
#

This is the touch-tone key (also know as "DTMF digit") that cancels the transfer. The terminator is only active when the call is connected, it won't do anything while the call is ringing.

timeout

Float
Default: 
30.0

How long Tropo will wait - in seconds - for an answer, busy signal, or other event to occur. The maximum value for this parameter is 2 hours. 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

String
Default: 
allison

Specifies the voice to be used when speaking text back to a user.

A full list of possible voices can be found here (there's many, many options).

callbackUrl

String

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.

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.

label

String

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.

Examples

  say("Please wait while we transfer your call. Press star to cancel the transfer.");
transfer(["+14075550100","sip:12345678912@221.122.54.86"], {
    playvalue: "http://www.phono.com/audio/holdmusic.mp3",
    terminator: "*",
    onTimeout: function(event) {
        say("Sorry, but nobody answered");
    }
});

-------------------------------------------

//Whisper on Transfer Example

transfer("sip:alice@example.com", {
    playvalue: "http://www.phono.com/audio/holdmusic.mp3",
    onConnect: function(event){
        ask("Press 1 to accept the call, press any other key to reject.", {
             choices:"1",
             mode: "dtmf",
             onChoice: function(event) {
               say("Connecting you now.");
             },
             onBadChoice: function(event) {
               say("Rejecting the call. Goodbye.");
               hangup();
             }
          }
        );
    }
});  
say "Please wait while we transfer your call. Press star to cancel the transfer."
transfer ["+14075550100","sip:12345678912@221.122.54.86"], {
    :playvalue => "http://www.phono.com/audio/holdmusic.mp3",
    :terminator => "*",
    :onTimeout => lambda { |event|
        say "Sorry, but nobody answered"}
}

-------------------------------------------

#Whisper on Transfer Example

transfer "sip:alice@example.com", {
    :playvalue => "http://www.phono.com/audio/holdmusic.mp3",
    :onConnect => lambda { |event|
        ask "Press 1 to accept the call, press any other key to reject.", {
            :choices => "1",
            :mode => "dtmf",
            :onChoice => lambda { |event|
                say "Connecting you now"
            },
            :onBadChoice => lambda { |event|
                say "Rejecting the call. Goodbye."
                hangup
            }
        }
    }
}
<?php
say("Please wait while we transfer your call. Press star to cancel the transfer.");
transfer(array("+14075550100","sip:12345678912@221.122.54.86"), array(
    "playvalue" => "http://www.phono.com/audio/holdmusic.mp3",
    "terminator" => "*",
    "onTimeout" => "timeoutFCN"
    )
);
function timeoutFCN($event) {
    say("Sorry, but nobody answered.");
    }
?>

-------------------------------------------

Whisper on Transfer Example

<?php
// Using onConnect
transfer("sip:alice@example.com", array(
    "playvalue" => "http://www.phono.com/audio/holdmusic.mp3",
    "onConnect" => "screen"
));
 
function screen($event) {
    $result = ask("Press 1 to accept the call, press any other key to reject.", array(
        "choices" => "1",
        "mode" => "dtmf"
    ));
    if ($result->name == "choice") {
        say("Connecting you now.");
    } else {
        say("Rejecting the call. Goodbye.");
        hangup();
    }
}
?>
say("Please wait while we transfer your call. Press star to cancel the transfer.")
transfer(["+14075550100","sip:12345678912@221.122.54.86"], {
    "playvalue":"http://www.phono.com/audio/holdmusic.mp3", 
    "terminator": "*",
    "onTimeout": lambda event : say("Sorry, but nobody answered.")})

-------------------------------------------

#Whisper on Transfer Example

transfer("+14075550100", {
  "playvalue":"http://www.phono.com/audio/holdmusic.mp3", 
  "terminator": "*",
  "onTimeout": lambda event : say("Sorry, but nobody answered."),
  "onConnect": lambda event : connect()
})
 
def connect():
  result = ask("Press 1 to accept the call, press any other key to reject." ,{
    "choices":"1",
    "mode":"dtmf"
  })
 
  if result.name == "choice":
    say("Connecting you now.")
  else:
    say("Rejecting the call. Goodbye.")
    hangup()
say("Please wait while we transfer your call. Press star to cancel the transfer.")
transfer(["+14075550100","sip:12345678912@221.122.54.86"], [
    playvalue: "http://www.phono.com/audio/holdmusic.mp3",
    terminator: "*",
    onTimeout: { event->
        say "Sorry, but nobody answered" }
])

-------------------------------------------

//Whisper on Transfer Example

transfer("+14075550909", [
    playvalue: "http://www.phono.com/audio/holdmusic.mp3",
    callerID: "4071234321",
    terminator: "*",
    onConnect: { event->
        result = ask("Press 1 to accept the call, press any other key to reject.", [
            choices: "1",
            mode: "dtmf"
        ])
         
        if(result.name == "choice"){
             say("Connecting you now.")
        }else{
            say("Rejecting the call. Goodbye.")
            hangup();
        }
    },
    onTimeout: { event->
        say "Sorry, but nobody answered" }
])