Outbound Calling Guide

Overview

Outbound Applications

IVR applications commonly start with an inbound call from an end-user. However, businesses may also want to initiate proactive, outbound communications with end-users.

The Plum Outbound system provides a platform-independent HTTP interface for initiating and managing use cases for outbound calling.

Features

The Plum Outbound service provides:

• An HTTP-based interface for queuing outbound calls.

• Flexible scheduling and redial rules.

  • Schedule calls in advance and set parameters for when call attempts expire.

  • Automate retries on busy or no-answer calls.

• Dynamic call scripts.

  • Full VoiceXML 2.0 scripting support.

  • Callee-type detection: Alter call-flows based on the detected callee-type.

  • Personalize messaging in outbound calls using specific parameters.

• Web-user interface for server administration and management.

  • Call queue review and management

  • Globally suspend/resume calls for all client applications

Interfaces

Client applications must implement three interfaces in order to successfully utilize outbound calling: the Outbound APIs, the start_url, and the result_url.

The client application server posts a queuecall.php or queuecalls.php request to the Plum Outbound service. This request includes the number(s) to be dialed and the parameters that specify redialing and scheduling rules.

As detailed below, this request includes two callback URL's specified by the client application.

• The start_url indicates the page the VoiceXML script fetches to start the application when the call connects.

• The result_url indicates the client-side interface that gathers call results at the conclusion of the call or after the call fails for the last time.

Before outbound calls go out, the outbound service sends a GET request to confirm that the start_url and result_url each return an HTTP 200 OK response. If these URLs don't return this response, the queuecall(s) operation fails.

1. DEV Outbound APIs

This consists of one of two php scripts - queuecall.php or queuecalls.php.

If the desired outbound campaign was previously stopped, activate the campaign by clicking the Start button in the “Campaign Status” column located on the Outbound Configuration page in DEV's web UI. This enables sending outbound calls.

Call Initiation

• Queueing a Single Call with queuecall.php

  • Activate the default campaign, as indicated above.

  • Return

    • The queuecall.php script returns an XML-formatted document which lists the Plum outbound assigned call_id or an error message if the call could not be queued.

• Creating a Call Campaign with queuecalls.php

  • All settings are applied to all calls in the campaign. However, message_reference and call_parameters are set on a per-call basis and are specified in the uploaded text file with each phone number.

  • Return

    • The queuecalls.php script returns an XML-formatted document which lists the Plum outbound assigned call_id or an error message if the call could not be queued.

2. Start URL

1. Plum's server fetches the start_url from the application server using a GET method.

2. start_url callback returns the initial application VoiceXML.

start_url Callback

The client application sets the start_url in the queuecall(s).php request. The start_url should return valid VoiceXML 2.0 scripts.

Return values: When Plum's outbound system requests the start_url, it sends a POST request with the following data:

Parameter	Type	Description
phone_number	int	Dialed phone number
call_id	int	Call identifier assigned by Plum outbound service
message_reference	string	Client-assigned call identifier
campaign_parameters	string	Client-specified campaign-specific parameters string
call_parameters	string	Client-specified call-specific parameters string

3. Result URL (optional)

1. Plum's server posts the result_url data to the application server using a POST method.

2. result_url callback logs and acts on the final call result.

result_url Callback

The client application sets the result_url in either the queuecall.php or queuecalls.php request. The result_url acknowledges receipt of the call result by returning the text “completed”.

Returned values include:

Parameter	Type	Description
phone_number	string	Dialed phone number
message_reference	string	Client-assigned call identifier
call_id	int	Call identifier assigned by Plum outbound service
result	string	Completed, Failed
callee_type	string	voice, answeringmachine, faxmachine, busy, noanswer, informationtone, linefailure, noattempt, unknown (see more about callee types)
attempts	int	Number of attempts made
last_attempt_timestamp	time	Last call attempt start time (Mon, 19 Jul 2004 13:46:03 -0400)
duration	int	The duration of the outbound session, in seconds

Data Flow and Control Flow

Outbound process for a successful call

Phase 1: Initiation

• The outbound process begins when the customer application performs an HTTP POST to the Plum Outbound API (either queuecall.php or queuecalls.php). The POST includes a phone number and a start URL. Customers can choose to include a result URL, too.

• Plum’s outbound API places the call(s) indicated in the customer application into the outbound calling queue on the Plum Voice Platform.

Phase 2: Calling

• Plum’s outbound queue is optimized for sending calls, so whenever an open VoiceXML channel is available on the Plum platform and the customer’s call is at the top of the Plum Outbound Queue, the call is placed.

• If the call connects successfully, the callee-type detection begins (if that option is enabled). At the same time, the parameters defined by the customer application (e.g., phone_number, message_reference, call_parameters) are posted to the customer’s start_url.

• At this point, the connected call progresses in accordance with the VoiceXML code for that call.

Phase 3: Call Completion & Post-Call Processing

• When the call completes, so too does the execution of all VoiceXML code for the call.

• The Plum Outbound Queue then moves to the next number in the queue and the process repeats phases 2 and 3 until the PV Platform works through all the calls in the queue.

• Post-Call Processing is a separate, but related process. It does not necessarily occur immediately upon the completion of a call or a call campaign. Once the platform processes the logs, the Outbound API posts a request to the result_url for the completed call that includes all established parameters, if the customer included a result URL.

Outbound process for an unsuccessful call

The process is the same as outlined above. However instead of connecting in Phase 2, the call fails.

• The Plum Voice Platform updates the status to ‘Failed’.

• Any phone number with a status other than ‘Completed’ gets placed back in the call queue to be redialed.

• This process continues until the phone numbers reaches the maximum number of retries.

• If the phone number expires (i.e., maxes out retry attempts) the Plum Voice Platform posts a request to result_url including all the parameters defined in the Outbound API (i.e. phone_number, message_reference, call_id).

The process is identical for the Multiple Outbound Calls API (queuecalls.php) except the client uploads a list of phone numbers for the outbound web service to dial instead of a single number.

If an outbound campaign does not complete all calls in the queue before the session ends (the scheduled_timestamp and expiration_timestamp control the session window, see Outbound APIs), the incomplete calls automatically expire and get cleared from the Outbound Queue. The Platform posts the details of the incomplete calls to the result_url and performs the result_url callback.

Understanding Callee Types and Outbound Statuses

The callee is the recipient of an outbound call. Plum's platform attempts to determine the type of callee (also referred as callee type), whether human, answering machine, etc. This information can be useful for determining an appropriate greeting or knowing whether a call was answered.

An outbound call is considered 'completed' when callee types are:

1. voice: the call was answered by a person

2. answeringmachine: the call went to voicemail

3. faxmachine: the call detected a fax machine tone

For best user experience it is best to add callee type detection to your application.

An outbound call is considered 'failed' when callee types are:

1. busy: the line is in use

2. noanswer: the call was not picked up and did not go to voicemail

3. informationtone: the call detected an information tone; causes may include all circuits busy, number was disconnected, etc.

4. linefailure: similar to information tone, the call detected a failure when calling the number

In rare cases, an outbound call may produce miscellaneous callee types:

1. noattempt: this can cause an 'uncalled' or 'failed' status and may occur when campaign windows are too short for the amount of calls or cancelling the queue

2. unknown: this can cause a 'completed' or 'failed' status and occurs when our platform cannot determine the proper callee type