Tropo is part of CiscoLearn More

on

This determines the events to be handled. For most actions, the possible events are: "continue", "error", "incomplete" and "hangup". For Transfers, the possible events are "ring", "connect". For all actions, if a signal is used to interrupt your application flow, Tropo will fire an event that matches the name of the triggered signal, if this event is defined in your code.

An event has a name and an action. The name is the event you're watching for: error, hangup, etc. The action is either a "say" object or a "next" URL string for most events. If say is used, Tropo will use text to speech or play an audio file, using the same behavior as the say object. If next is used, Tropo will send a result object to that URL and stop processing the current document. If both are used, the text-to-speech or audio will play, then the result object will be sent to the next URL.

On Transfer, if "ring" is the event, Tropo will play the text to speech or audio file (just like the say object) and repeat it until the two parties are connected or the transfer fails or times out. If "connect" is used, any single Tropo command can be used as the action. If that command is "ask" Tropo will only connect the call if the ask completes with a successful choice. In a "connect" event, "post" is also a valid action, and is described below. The step by step behavior of the connect event is detailed in another document.

Events that occur on the call cause the Tropo "on" event to be triggered. For example, if an error event is defined and Tropo encounters an error on the call, then the error event's say or next action will be performed.

A document can define multiple events. When an event that has been defined in the document occurs on the call, Tropo will trigger the event's action. If the action is not next, Tropo will execute that action and then move on to the "continue" event, if defined.

The continue event is a catch-all event. If no other events are triggered, or if the Tropo event that occurs is not defined in the document, then continue is triggered. As an example, if no error event is defined by your JSON, if Tropo encounters an error, then the continue event will be triggered.

A document can also define multiple copies of the same event. Tropo will process them all in order, until a "next" action is reached. For example, an "incomplete" event could be defined three times. The first two have a "say" with two different text to speech strings, and the third has "next" with a URL. When an incomplete action occurs, Tropo will play both text to speech strings in order, then send a result document to the URL defined in "next".

Events are in scope only for the current document. When Tropo sends the result object to your server and gets another JSON document, any events from previously in the call are no longer defined. If you have a generic handler that you wish to use throughout the call, you must define the error events each time.

Fields

event

String
(Required)
Default: 
undefined

This defines which event the on action handles. The possible values for all activities other than transfer are "continue", "incomplete", "error" and "hangup".Continue will fire if the resource's actions were successful (such as a valid choice) or if no other events are defined. Incomplete fires when the resource's actions were unsuccessful, such as a timeout or call failure. Error will fire if something went wrong at the server level, and hangup will fire when the user disconnects the call.

For a transfer, the event can be 'ring' or 'connect'. Ring will play the text to speech or audio file from a "say" object to the first leg of the call until the second leg answers. Connect will execute a Tropo command or send a webhook to a URL. If the Tropo command is 'ask', Tropo will only connect the transfer if the 'ask' result is a successful choice.

If used with a signal, the event will be the name of an assigned signal.

next

String
Default: 
undefined

When an associated event occurs, Tropo will post to the URL defined here. If an event has no handler, then the "continue" event is fired. If an event has a handler but that handler does not have a URL specified (for example, it has a 'say' verb instead), then that handler is processed and then the "continue" event is fired.

If the continue event handler is not present or if it is present but has no URL, then the call is hung up and the "hangup" event is fired.

say

Object
(Required)
Default: 
undefined

This determines what is played or sent to the caller. This can be a single object or an array of objects.

post

String

This parameter is only available in the 'connect' event of transfer. Because a transfer is a blocking function, your 'continue' event won't fire until the transfer is completed and so your web application doesn't know if the transfer succeeded or not. When given a URL, the 'post' action will send a simplified Result object as an HTTP POST to this URL. Like all other actions that are sent during the connect event, this happens while the first caller is hearing the 'ring' event, and before the two parties are connected. Any response by your web application to this HTTP post is ignored. It is simply a webhook that fires to alert your web application that the call has been connected.

Examples

Example showing triggers for each event

{
   "tropo":[
      {
         "on":{
            "event":"continue",
            "next":"/continue.json"
         }
      },
      {
         "on":{
            "event":"error",
            "next":"/error.json"
         }
      },
      {
         "on":{
            "event":"hangup",
            "next":"/hangup.json"
         }
      },
      {
         "on":{
            "event":"incomplete",
            "next":"/incomplete.json"
         }
      },
      {
         "ask":{
            "say":[
               {
                  "value":"Welcome to Tropo.  What's your birth year?"
               }
            ],
            "name":"year",
            "required":true,
            "choices":{
               "value":"[4 DIGITS]"
            }
         }
      }
   ]
}

Example showing use of "on" with a signal

{
   "tropo":[
      {
         "on":{
            "event":"exit",
            "next":"exit-say.json"
         }
      },
      {
         "say":{
            "value":"http://phono.com/audio/holdmusic.mp3",
            "allowSignals":"exit"
         }
      }
   ]
}
{
   "tropo":[
      {
         "on":{
            "event":"continue",
            "next":"continue.json",
            "say":[
               {
                  "value":"Nice answer!",
                  "voice":"Victor"
               }
            ]
         },
         "ask":{
            "say":[
               {
                  "value":"Welcome to Tropo.  What's your birth year?"
               }
            ],
            "voice":"Victor",
            "name":"year",
            "required":true,
            "choices":{
               "value":"[4 DIGITS]"
            }
         }
      }
   ]
}
{  
   "tropo":[  
      {  
         "transfer":{  
            "to":"+14155551212",
            "timeout":5,
            "on":{  
               "event":"ring",
               "next":"http://example.com/ringback.mp3"
            }
         },
         "on":[  
            {  
               "event":"incomplete",
               "say":[{"value":"no answer"}]
            },
            {  
               "event":"continue",
               "next":"/transfer-over"
            }
         ]
      }
   ]
}