{"transfer":} object

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 '"to" parameter. This method only applies to voice calls.

When this method is called, the following occurs:

  • The audio file specified in the "on ring" event 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 ringRepeat.
  • 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 was applied through the use of from, the receiving party will see 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 audio file in the ring event.
  • If the call is not answered prior to the timeout, the incomplete 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.
  • In the event that the call fails for a reason other than a timeout, a incomplete event will also be fired.

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: "+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.

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 if the call was answered, busy, or failed, see the "disposition" field on the result object. To determine how long a transferred call was ringing and connected, see the duration and connectedDuration properties of action on the result object.

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

Fields

to
Data Type: 
String or Array
Default: (none) 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 #). 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: "+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.

You can also list multiple phone numbers or SIP addresses (or both!) as an array; whichever destination picks up first, wins.

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.

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

choices
Data Type: 
Object
Default: (none) Optional

When used with a transfer, choices allows you to define a terminator. The terminator is the touch-tone key (also known as "DTMF digit") that will allow the caller to cancel the transfer after it connects. A common terminator would be the pound key (#).

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 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
Data Type: 
Object
Default: (none) Optional

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

interdigitTimeout
Data Type: 
Integer
Default: (none) Optional

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.

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.

on
Data Type: 
Object
Default: (none) Optional

Adds an event callback so that your application may be notified when a particular event occurs. For transfer, the event can be:

ring - this allows you to play an audio file or "say" something while the outbound call is ringing

of

connect - 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 the "ring" event will continue playing while the code in the connect event runs.

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.

ringRepeat
Data Type: 
Integer
Default: 
1
Optional

This specifies the number of times the audio file specified in the ring event will repeat itself.

timeout
Data Type: 
Float
Default: 
30.0
Optional

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.

Examples

Example showing transfer to a new SIP destination

{
   "tropo":[
      {
         "say":[
            {
               "value":"Hello, about to transfer you"
            }
         ]
      },
      {
         "transfer":{
            "to":"sip:9991427589@example.com"
         }
      }
   ]
}

Example showing transfer with an audio file playing during transfer

{
   "tropo":[
      {
         "transfer":{
            "to":"8005551212",
            "ringRepeat":2,
            "on":{
               "event":"ring",
               "say":{
                  "value":"http://www.phono.com/audio/holdmusic.mp3"
               }
            }
         }
      }
   ]
}

Example showing whisper on transfer

{
  "tropo": [
    {
      "say": {
        "value": "you are now being transfered"
      }
    },
    {
      "transfer": {
        "to": "14075550100",
        "ringRepeat": 2,
        "on": [
          {
            "event": "ring",
            "say": {
              "value": "http://www.phono.com/audio/holdmusic.mp3"
            }
          },
          {
            "event": "connect",
            "ask": {
              "attempts": 3,
              "say": [
                {
                  "value": "Sorry. Please enter you 5 digit account number again.",
                  "event": "nomatch"
                },
                {
                  "value": "Sorry, I did not hear anything.",
                  "event": "timeout"
                },
                {
                  "value": "Please enter 5 digit account number"
                }
              ],
              "required": true,
              "bargein": true,
              "timeout": 10,
              "name": "foo",
              "choices": {
                "value": "[5 DIGITS]",
                "mode": "dtmf"
              }
            }
          }
        ]
      }
    }
  ]
}