Plum Outbound HTTP API Reference

Plum DEV v. 3.0

© 2013 Plum Group, Inc. All rights reserved.

Contents

1. Features
2. Overview 3. Data Flow and Control Flow
4. Interface Specifications
5. Programming Notes

1. Features

2. Overview

2.1 Outbound Applications

Most IVR (interactive voice response) telephony applications start with an inbound call from the user. In other cases, we need a mechanism for initiating an outbound call to the user.

Outbound application examples:

The Plum Outbound system provides a platform independent HTTP interface for initiating and managing such calls.

2.2 Interfaces

Three interfaces must be implemented by the client application:

1. queuecall.php or queuecalls.php:

Your application server posts to Plum server: method="post", enctype="multipart/form-data" for queuecalls.php
Post a request to the Plum Outbound server for a new call or calls to be placed.

2. start_url:

Plum server fetches from application server: method="get"
Callback should return the initial application VoiceXML.

3. result_url:

Plum server posts to application server: method="post"
Callback should log and act on the final call result.

First 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 parameters to 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 for the VoiceXML script that should be fetched to start the application when the call is connected. The result_url indicates the client side interface which will gather call results at the conclusion of the call or after the call has failed for the last time.

NOTE: Before your outbound calls go out, the outbound platform sends a GET request to confirm that the start_url and result_url URLs return an HTTP 200 OK response. If these URLs don't return this response, the queuecall operation fails.

3. Data Flow and Control Flow

3.1 Control Sequence

Outbound process for a successful call:

1. Your code performs an HTTP POST to queuecall.php which includes a phone number, start_url and result_url.
2. The Plum outbound system places the call into a queue of possible calls to dial.
3. When an outbound channel on the VoiceXML systems becomes available and your call is at the top of the queue, the call is placed.
4. The call is connected successfully and the callee type detection begins (if enabled).
5. The result of the callee type detection as well as all the parameters defined in the Outbound API (i.e. phone_number, message_reference, call_parameters) are posted to your start_url.
6. A standard VoiceXML session continues from here.
7. The call completes, all VXML execution is completed.
8. The VoiceXML system notifies the outbound system that the call is complete.
9. The outbound system posts a request to result_url including all the parameters defined in the Outbound API.

Outbound process for an unsuccessful call:

1. Your code performs an HTTP POST to queuecall.php which includes a phone number, start_url and result_url.
2. The plum outbound system places the call into a queue of possible calls to dial.
3. When an outbound channel on the VoiceXML systems becomes available and your call is at the top of the queue, the call is placed.
4. The call fails.
5. The VoiceXML system notifies the outbound system that the call has failed.
6. If the call has reached the maximum number of retries or has expired, the outbound system posts a request to result_url including all the parameters defined in the Outbound API (i.e. phone_number, message_reference, call_id). Otherwise, the call is placed back on the queue to be redialed.

queuecalls.php operates similarly except a list of phone numbers to be dialed is uploaded to the Plum outbound web service.

NOTE: If an outbound campaign has too many calls to place and these calls don't all go out, steps 3-5 for "Outbound process for an unsuccessful call" do not occur. However, result_url does get called since the outbound platform clears the expired calls and performs the callback. In this case, the posted callee_type that gets returned to result_url is an empty string.

4. Interface Specifications

4.1 Call Initiation

Queueing a Single Call with queuecall.php

queuecall.php allows you to initiate a call to a phone number that you specify. When you initiate an outbound call in this manner, the call instance will be placed into the default calling campaign for your account. This default campaign and the calls within it are viewed and controlled from your campaign management interface after you login with your login name and PIN. When using the default campaign, make sure that you activate it by clicking the Start button under "Status" in the Outbound Configuration Page. This will allow you to receive calls.

To queue a single call, the client application posts an HTTP request to the server outbound API URL.

For Plum DEV, that URL is:

URL: http://outbound.plumvoice.com/webservice/queuecall.php

For Plum DEV in the UK, that URL is:

URL: http://outbound-uk.plumvoice.com/webservice/queuecall.php

For Plum i.o.n. systems, that URL is:

URL: http://your-server-IP/outbound/webservice/queuecall.php

Required Parameters:

Parameter Type Description
login string sender login name1
pin string sender PIN code
phone_number string phone number to be dialed -- be sure to include the 1 before the area code2
start_url string URL for the VoiceXML script to be used for the call3

Optional Parameters:

Parameter Type Description
result_url string URL for post-call processing4
message_reference string The message_reference string is POSTed to the URL specified
by start_url 2,5
call_parameters string The call_parameters string is POSTed to the URL specified by start_url 2,5 (up to 255 characters)
max_retries int an integer from 0 to 10 for the number of failed call attempts before giving up
retry_interval int an integer from 60 to 172800 indicating the number of seconds between retries
scheduled_timestamp int 0 to start immediately or a UNIX-time integer indicating when to start attempting the call (scheduled_time can be used instead -- see below for details) 6
expiration_timestamp int 0 to never expire or a UNIX-time integer indicating when the system should give up attempting to complete an uncompleted call (expiration_time can be used instead -- see below for details) 6

Notes:

1. If you own your Plum IVR server and have outbound, you can assign new sender login names and PINs from the outbound administration interface by logging in as admin. If you are a Plum DEV customer, a PIN code will be assigned to you.
2. These parameters are stored and passed back to the application start_url as POST variables. To dial an extension number, the format is: "tel:+16177123000;postd=1234". However, if you do outbound dialing to an extension, you would want to use a <record> tag to account for the hold music that is played while you are being transferred to the extension and to ensure that your prompts are played at the correct time.
To specify the caller ID on a per call basis, you'll have to change your phone_number parameter to also include the caller ID you want the call recipient to see. The format is: phone_number=tel:+10123456789;ani=1234567890 (This would make an outbound call to 012-345-6789 and display a caller ID of 123-456-7890). The 'ani' must be a 10 digit number, without the preceding '1'. If it is not, the call will either be declined completely or it will go through with Plum's default caller ID (depending on which carrier(s) the call is routed through). The 'tel' is a telephone URL as defined here: http://www.ietf.org/rfc/rfc2806.txt. You must include the '+' and then the country code before the number (so the above example would apply to all calls made within the US, where country code is '1').
3. The start_url should return valid VoiceXML 2.0. When queuecall.php receives a POST the start_url will be fetched once by either your server or the server hosting outbound.plumvoice.com. You will need to enable access from these IP Addresses or the POST to queuecall.php will timeout.
4. Outbound system posts result either after all retry attempts have been made or after the call successfully completes.
5. Typically the message_reference POST var is used to pass a single call identifying string that can be used by the start URL to customize the call session. The call_parameters POST var is used for arbitrary data with possibly several different parameters sent in a single string. It is up to you to format and parse the data within the call_parameters string.
6. Instead of using UNIXtime to indicate the scheduled start and expiration timestamps, it may be easier to use simple natural language time expressions like "now", "oct 14th, 2003 11:05PM EST", or "+3 days". Use the scheduled_time and expiration_time parameters to take advantage of this capability.

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

queuecalls.php allows you to initiate calls to any number of callers listed in a text file that you upload. When you initiate a group of outbound calls in this manner, you will have created a calling campaign. This campaign, and the unique name you've given it, is controlled from your campaign management interface after you login with your login name and PIN.

You must POST with multipart/form-data encoding in order for the uploaded file to be properly received and processed by 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.

To create a call campaign and queue multiple calls, the client application posts an HTTP request with a phone number list to the server outbound API URL.

For Plum DEV, that URL is:

URL: http://outbound.plumvoice.com/webservice/queuecalls.php

For Plum DEV in the UK, that URL is:

URL: http://outbound-uk.plumvoice.com/webservice/queuecalls.php

For Plum i.o.n. systems, that URL is:

URL: http://your-server-IP/outbound/webservice/queuecalls.php

Required Parameters:

Parameter Type Description
login string sender login name1
pin string sender PIN code
campaign_name string unique name for the new calling campaign
phone_list file phone number list2,3
start_url string URL for the VoiceXML script to be used for the call4

Optional Parameters:

Parameter Type Description
result_url string URL for post-call processing5
campaign_parameters string The call_parameters string is POSTed to the URL specified by start_url 2,6 (up to 255 characters)
max_retries int an integer from 1 to 10 for the number of failed call attempts before giving up
retry_interval int an integer from 60 to 172800 indicating the number of seconds between retries
scheduled_timestamp int 0 to start immediately or a UNIX-time integer indicating when to start attempting the call (scheduled_time can be used instead -- see below for details) 7
expiration_timestamp int 0 to never expire or a UNIX-time integer indicating when the system should give up attempting to complete an uncompleted call (expiration_time can be used instead -- see below for details) 7

Notes:

1. If you own your Plum IVR server, you can assign new sender login names and PINs from the outbound administration interface by logging in as admin. If you are a Plum DEV customer, a PIN code will be assigned to you.
2. These parameters are stored and passed back to the application start_url as POST variables.
3. Calls are listed in the phone number list file on comma-delimited lines where the first field is the phone number and the second and third fields are a message_reference string and call_parameters string for the call. The second and third fields are optional.
4. The start_url should return valid VoiceXML 2.0. When queuecalls.php receives a post, the start_url will be fetched once by either your server or the server hosting outbound.plumvoice.com. You will need to enable access from these IP Addresses or the POST to queuecalls.php will timeout.
5. Outbound system posts result either after all retry attempts have been made or after the call successfully completes.
6. The campaign_parameters POST var is used for arbitrary data with possibly several different parameters sent in a single string. It is up to you to format and parse the data within the call_parameters string.
7. Instead of using UNIXtime to indicate the scheduled start and expiration timestamps, it may be easier to use simple natural language time expressions like "now", "oct 14th, 2003 11:05PM EST", or "+3 days". Use the scheduled_time and expiration_time parameters to take advantage of this capability.

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.

4.2 start_url Callback

URL:

The start_url is set by the client application in the queuecall(s).php request.

Parameters:

Parameter Type Description
phone_number int dialed phone number
callee_type string on success: voice|answeringmachine
call_id int plum outbound assigned call identifier
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

Return:
The start_url should return valid VoiceXML 2.0 scripts.

4.3 result_url Callback

URL:
The result_url is set by the client application in the queuecall(s).php request.

Parameters:

Parameter Type Description
phone_number string dialed phone number
message_reference string client assigned call identifier
call_id int plum outbound assigned call identifier
result string completed|failed
callee_type string on completed: voice|answeringmachine
on failed: fax|busy|noanswer|operator
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

Return:
The result_url should return acknowledgment of the receipt of the call result, by returning the text "completed".

NOTE: If an outbound campaign has too many calls to place and these calls don't all go out, steps 3-5 for "Outbound process for an unsuccessful call" do not occur. However, result_url does get called since the outbound platform clears the expired calls and performs the callback. In this case, the posted callee_type that gets returned to result_url is an empty string.

5. Programming Notes

5.1 Application Dynamics and Personalization

The start_url is called by the Plum Outbound system with parameters which allow dynamic personalization of the application script. The phone number dialed, the callee type, and the Plum platform assigned call ID are returned to the client application server start_url as HTTP POST variables.

Personalization

The Plum Outbound system and VoiceXML scripting enables the creation of personalized call scripts based on the identity of the callee. To that end, several identifiers are accepted by the Plum Outbound system which are passed back to the client application server once the call is connected at HTTP GET variables:

1. Phone number: phone_number
For many applications, the phone number will be enough to uniquely identify the call. Based on the phone number, the client application server can retrieve information such as the callee's name.
2. Message reference: message_reference
Where the phone number does not uniquely identify the call, the client application can send a message reference along with the queuecall(s).php request.
3. Call ID: call_id
Each call is also assigned a unique identifier at queue time by the Plum Outbound System. This call ID is returned by the queuecall(s).php request. This identifier is unique to the Plum Outbound System Server. (However, if the client application is being served by multiple Plum Outbound servers, then this call_id may not be unique. The client application should assign and refer to the message_reference instead.)
4. Message parameters: campaign_parameters call_parameters
Use the message parameters to pass call personalization information directly to the call script. For example, for an appointment reminder application, the message parameters could be used for the callee name and the appointment date and time. The VoiceXML script could then be constructed with a personalized greeting and reminder without looking up the callee's record in a database at call time.

Callee type detection

Before handing off the callee to the application VoiceXML script, the Plum Outbound system attempts to detect the callee type. Note that connections to fax machines are considered failed calls and do not trigger a callback to the application start_url page.