Tropo WebAPI Development Guide Home  |  Frameset Home

  Playing Audio Files  |  TOC  |  Sending Text Messages  

Handling Call Failures


There will be times when an outbound call fails or times out - a timeout occurs when the call rings but never answers (note the default timeout is 30 seconds), while a failure occurs if the call never rings at all - maybe the number is disconnected or you're accidentally trying to call the letter Q instead of a phone number (note that phone numbers in the US need to be in the format +14075550100; international numbers would be something like +31105550100, depending on the destination country).

With WebAPI, the on event handles what to do if the call is successful or if it fail/timeouts. Here's the same basic app that we used in the Making a Call Quickstart, except this one includes event handling; if you're using PHP, note that the following example uses the framework Limonade, so you would need to define the end of the start URL in Tropo to include the resource name, like http://www.example.com/test.php?uri=start:

require 'tropo-webapi-ruby'
require 'sinatra'

post '/index.json' do
  
  t = Tropo::Generator.new
  
  t.call(:to => "Q")
  t.say(:value => "Tag, you're it!")
  
  t.on :event => 'incomplete', :next => '/incomplete.json'
  t.on :event => 'hangup', :next => '/hangup.json'
  t.on :event => 'error', :next => '/error.json'

  t.response
  
end

post '/incomplete.json' do
  puts "The call did not complete."
end

post '/hangup.json' do
  puts "The user hungup or the call went to voicemail."
end

post '/error.json' do
  puts "A server error has occurred."
end
var sys = require('sys');
var express = require('express');
var app = express.createServer();
var tropo_webapi = require('tropo-webapi');

app.post('/', function(req, res){
	
	var tropo = new TropoWebAPI();
	
	tropo.call("Q");
	tropo.say("Tag, you're it!!");

	tropo.on("incomplete", null, "/incomplete", true);
	tropo.on("hangup", null, "/hangup", true);
	tropo.on("error", null, "/error", true);
	
	res.send(TropoJSON(tropo));
});
	
app.post('/incomplete', function(req, res){
	console.log("The call did not complete.");
});	

app.post('/hangup', function(req, res){
	console.log("The user hungup or the call went to voicemail.");
});

app.post('/error', function(req, res){
	console.log("A server error has occurred.");
});

app.listen(8000);
console.log('Server running on port :8000');
<?php
 
require 'tropo.class.php';
require 'lib/limonade.php';

dispatch_post('/start', 'app_start');
function app_start() {
	     
	$tropo = new Tropo();
     
	$tropo->call("Q"); 
	$tropo->say("Tag, you're it!");
 
	$tropo->on(array("event" => "incomplete", "next" => "hello_world.php?uri=incomplete"));
	$tropo->on(array("event" => "hangup", "next" => "hello_world.php?uri=hangup"));
	$tropo->on(array("event" => "error", "next" => "hello_world.php?uri=error"));

	return $tropo->RenderJson();

}

dispatch_post('/incomplete', 'app_incomplete');
function app_incomplete() {
	error_log("The call did not complete.");
}

dispatch_post('/hangup', 'app_hangup');
function app_hangup() {
	error_log("The user hungup or the call went to voicemail.");
}

dispatch_post('/error', 'app_error');
function app_error() {
	error_log("A server error has occurred.");
}

run();

?>
from itty import *
from tropo import Tropo

@post('/index.json')
def index(request):

	t = Tropo()

	t.call("Q")
	t.say("Tag, you're it!")
	
	t.on(event = "hangup", next = "/hangup.json")
	t.on(event = "incomplete", next ="/incomplete.json")
	t.on(event = "error", next ="/incomplete.json")
	
	return t.RenderJson()

@post("/hangup.json")
def index(request):
	
	print "The user hungup or the call went to voicemail."
	
@post("/incomplete.json")
def index(request):
	
	print "The call did not complete."
	
@post("/error.json")
def index(request):
	
	print "A server error has occurred."

run_itty(server='wsgiref', host='0.0.0.0', port=8888)

{
   "tropo":[
      {
         "on":{
            "event":"error",
            "next":"/error.json"
         }
      },
     {
         "on":{
            "event":"hangup",
            "next":"/hangup.json"
         }
      },
      {
         "on":{
            "event":"incomplete",
            "next":"/incomplete.json"
         }
      },
      {"call":
            {"to":"Q"}
      },
      {"say":[
            {"value":"Tag, you're it!"}
      ]}
]}

incomplete fires when the call was unsuccessful - such as a timeout or call failure (someone rejecting the call will usually trigger this event); hangup fires if the call was answered and then disconnected (reaching voicemail will usually trigger hangup); error will fire if something went wrong at the server level (i.e., the call never went out at all). For more information about using "on", check out THIS doc page and the API reference for "on".

Note that with JSON, this app will actually need four separate files, the starting file containing the code on the JSON tab above, then error.json, hangup.json and incomplete.json, which would contain the next set of instructions for each of those events. Using the libraries, however, you can have all of the instructions contained in one file, as long as you use a framework (like Sinatra for Ruby, express for Node.js, Limonade for PHP and so on).

That covers the basics of phone calls; on to text messages!

Next Step: Sending Text Messages


  ANNOTATIONS: EXISTING POSTS
0 posts - click the button below to add a note to this page

login
  Playing Audio Files  |  TOC  |  Sending Text Messages  

© 2012 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site