Plum Outbound Call Queuing Reference Implementations

Plum DEV v. 3.0

© 2013 Plum Group, Inc. All rights reserved.

Queue a Single Call with the queuecall web service

Authentication ?
Login
PIN
Required Settings
Phone Number
Start URL
Optional Callback Parameter Settings ?
Result URL
Message Reference String
Custom Call Parameters
Optional Call Control Settings ?
Maximum Retries Retry Interval
Scheduled Start Time Expiration Time

queuecall Web Service Help:

queuecall: 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.

For Plum DEV, the queuecall web service URL is: http://outbound.plumvoice.com/webservice/queuecall.php

For Plum DEV in the UK, the queuecall web service URL is: http://outbound-uk.plumvoice.com/webservice/queuecall.php

For Plum i.o.n. systems, the queuecall web service URL is: http://your-server-IP/outbound/webservice/queuecall.php

Required POST Variables
POST Variable Type Length Description
login string 128 sender login name
pin string 16 sender PIN code
phone_number string 128 phone number to be dialed -- be sure to include the 1 before the area code
start_url string 255 URL for the VoiceXML script to be used for the call

Optional POST Variables
POST Variable Type Length Description
result_url string 255 URL for post-call processing
message_reference string 255 The message_reference string is POSTed to the URL specified by start_url
call_parameters string 255 The call_parameters string is POSTed to the URL specified by start_url
max_retries integer n/a an integer from 0 to 10 for the number of failed call attempts before giving up
retry_interval integer n/a an integer from 60 to 172800 indicating the number of seconds between retries
scheduled_timestamp integer n/a 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)
expiration_timestamp integer n/a 0 to never expire or a UNIX-time integer indicating when the outbound system should give up attempting to complete an uncompleted call (expiration_time can be used instead -- see below for details)

queuecall Authentication Notes:

If you own a Plum i.o.n. system, 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.

queuecall Callback Settings Notes:

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. When queuecall receives a post, the start_url will be fetched once by either your server or will be fetched once by the outbound server. You will need to enable access from these IP Addresses or the POST to queuecall will timeout.

queuecall Call Control Settings Notes:

Instead of using UNIX time 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 POST variables to take advantage of this capability. These two POST variables are strings of no more than 80 characters.

Create a Call Campaign with the queuecalls web service

Authentication ?
Login
PIN
Required Settings ?
Campaign Name
Phone Number List
Start URL
Optional Callback Parameter Settings
Result URL
Custom Campaign Parameters
Optional Call Control Settings ?
Maximum Retries Retry Interval
Scheduled Start Time Expiration Time

queuecall Web Service Help:

queuecalls: 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.

The form above performs an HTTP POST to the queuecalls web service.

For Plum DEV within the US, the queuecalls web service URL is: http://outbound.plumvoice.com/webservice/queuecalls.php

For Plum DEV within the UK, the queuecalls web service URL is: http://outbound-uk.plumvoice.com/webservice/queuecalls.php

For Plum i.o.n. systems, the queuecalls web service URL is: http://your-server-IP/outbound/webservice/queuecalls.php

You must POST with multipart/form-data encoding in order for the uploaded file to be properly received and processed by the queuecalls web service.

All settings are applied to all calls in the campaign. However, message_reference and call_parameters (see here for details on those two variables) are set on a per-call basis and are specified in the uploaded text file with each phone number.

Required POST Variables
POST Variable Type Length Description
login string 128 sender login name
pin string 16 sender PIN code
campaign_name string 64 unique name for the new calling campaign
phone_list file n/a phone number list
start_url string 255 URL for the VoiceXML script to be used for the call

Optional POST Variables
POST Variable Type Length Description
result_url string 255 URL for post-call processing
message_reference string 255 The message_reference string is POSTed to the URL specified by start_url
call_parameters string 255 The call_parameters string is POSTed to the URL specified by start_url
max_retries integer n/a an integer from 0 to 10 for the number of failed call attempts before giving up
retry_interval integer n/a an integer from 60 to 172800 indicating the number of seconds between retries
scheduled_timestamp integer n/a 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)
expiration_timestamp integer n/a 0 to never expire or a UNIX-time integer indicating when the outbound system should give up attempting to complete an uncompleted call (expiration_time can be used instead -- see below for details)

queuecalls Authentication Notes:

If you own a Plum i.o.n. system, 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.

queuecalls Callback Settings Notes:

When queuecalls receives a post, the start_url will be fetched once by either your server or will be fetched once by the outbound server. You will need to enable access from these IP Addresses or the POST to queuecalls will timeout.

queuecalls Required Settings Notes:

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 as described here. The second and third fields are optional.

queuecalls Call Control Settings Notes:

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 POST variables to take advantage of this capability. These two POST variables are strings of no more than 80 characters.