{"on":} object

This determines the events to be handled. Possible events are: "continue", "error", "incomplete" and "hangup", except when used with a transfer, in which case the possible event is 'ring', or when used with a signal, in which case the event can be the name of an assigned signal.

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 (or "ring" on transfer). 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.

A document can define multiple events. If the event occurs on the call, Tropo will trigger the event's action. If the action is say, Tropo will play the audio or text to speech, then send execute the "continue" event, if defined.

Events on the call cause 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 say or next action will be performed.

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.

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 core values are "continue", "incomplete", "error" and "hangup", except when used within a transfer, in which case the possible event is 'ring'. 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.

If used with a signal, in which case the event can 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.

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"
         }
      }
   ]
}

Example showing the inclusion of voice for the on continue event

{
   "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]"
            }
         }
      }
   ]
}

Example of using the ring event on transfer along side other events. In this example, the call will be transferred to 1-415-555-1212. While waiting for the person at that number to answer, the caller will hear http://example.com/ringback.mp3. If the transferred call is not answered, the incomplete event will be triggered. Once the transfer has completed, the continue event is triggered.

{  
   "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"
            }
         ]
      }
   ]
}