Tropo WebAPI Development Guide

{"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 by the "to" parameter. This verb only applies to voice calls.

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.

usage

{ "transfer": {
    "to": String or Array,
    "allowSignals": String or Array,
    "answerOnMedia": Boolean,
    "choices": Object,
    "from": String,
    "headers": Object,
    "interdigitTimeout": Integer,
    "name": String,
    "on": Object,
    "required": Boolean,
    "ringRepeat": Integer,
    "timeout": Float } }

fields

to	Data Type: String or Array	Default: (none)	Required
	The new destination for the incoming call as a URL, in one of two forms: * Telephone number: tel:+14155551212 (requires + and the country code) * SIP Address: sip:9991436228@sip.tropo.com 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).
choices	Data Type: Object	Default: "" (undefined)	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 before it connects. A common terminator would be the pound key (#).
from	Data Type: String	Default: (none)	Optional
	If multiple contact methods for a given network are attached to an application, this field allows you to specify which one it comes from. For example, if you have two phone numbers, setting this field would allow you to specify the caller ID that appears to the recipient. For voice calls, this can be any valid phone number; for SMS it needs to be a number assigned to your account. For IM, there's no need to set a specific value for `from` - it will always need to match the IM account associated with your application, which is what Tropo uses by default anyways.
headers	Data Type: Object	Default: "" (undefined)	Optional
	This contains the Session Initiation Protocol (SIP) Headers for the current session. This is advanced network information.
interdigitTimeout	Data Type: Integer	Default: "" (undefined)	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: "" (undefined)	Optional
	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: "" (undefined)	Optional
	Adds an event callback so that your application may be notified when a particular event occurs. For transfer, the only possible event is "ring"; this allows you to play an audio file or "say" something while the outbound call is ringing.
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. 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.

code samples

Example showing transfer to a new SIP address/application.

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

Example showing transfer that plays an audio file to the caller during the transfer

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

additional links

none

ANNOTATIONS: EXISTING POSTS

callhome

2/16/2012 8:02 PM (EST)

Can I use postd with sip address?

VoxeoGarret

2/16/2012 8:44 PM (EST)

Hello,

This should not be an issue and the syntax should still be the same. Go ahead and test it out and let me know if you have any other issues.

Regards,
Garrett King

Customer Support Engineer
Voxeo Corporation