Plum DEV Documentation
plumdevguide:outboundsenderreference

This is an old revision of the document!


Queue a Single Call with the queuecall web service

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 VariableTypeLength Description
loginstring 128sender login name
pinstring16sender PIN code
phone_numberstring128phone number to be dialed – be sure to include the 1 before the area code
start_urlstring255URL for the VoiceXML script to be used for the call

Optional POST Variables

POST VariablesTypeLengthDescription
result_urlstring255URL for post-call processing
message_referencestring255The message_reference string is POSTed to the URL specified by start_url
call_parametersstring255The call_parameters string is POSTed to the URL specified by start_url
max_retriesintegern/aan integer from 0 to 10 for the number of failed call attempts before giving up
retry_intervalintegern/aan integer from 60 to 172800 indicating the number of seconds between retries
scheduled_timestampintegern/a0 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_timestampintegern/a0 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 Nottes:

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

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 VariableTypeLengthDescription
loginstring128sender login name
pinstring16sender PIN code
campaign_namestring64unique name for the new calling campaign
phone_listfilen/aphone number list
start_urlstring255URL for the VoiceXML script to be used for the call

Optional POST Variables

POST VariableTypeLengthDescription
result_urlstring255URL for post-call processing
message_refrencestring255The message_referene string is POSTed to the URL specified by the start_url
call_parametersstring255The call_parameters string is POSTed to the URL specified by start_url
max_retriesintegern/aan integer from 0 to 10 for the number of failed call attempts before giving up
retry_intervalintegern/aan integer from 60 to 172800 indicating the number of seconds between retries
scheduled_timestampintegern/a0 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_timestampintegern/a0 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.