Outbound API Parameter Notes

Definitions

Message Reference

message_reference is a unique identifier you can set that allows you to differentiate your outbound calls from one another. This same parameter can be used by the start_url to customize the call session.

Call Parameters

call_parameters allows you to send arbitrary data with possibly several different parameters sent in a single string.

Max Retries

max_retries allows you to set a maximum number of retries for attempting an outbound call before giving up. This number of retries can only be set to an integer between 0 and 10.

Retry Interval

retry_interval allows you to set the number of seconds in between retrying an outbound call. This number of seconds can be set to an integer between 60 and 172800.

Scheduled Timestamp

scheduled_timestamp allows you to set a UNIX-time integer indicating when to start attempting your outbound call. If you do not wish to use UNIX time, you can use the POST variable, scheduled_time, to use simple natural time expressions like “now”, “oct 14th, 2011 11:05PM EST”, or “+3 days”.

Expiration Timestamp

expiration_timestamp allows you to set a UNIX-time integer indicating when to give up attempting your outbound call. If you do not wish to use UNIX time, you can use the POST variable, expiration_time, to use simple natural time expressions like “now”, “oct 14th, 2011 11:05PM EST”, or “+3 days”.

Single Outbound Call

Notes on queuecall.php form data parameters.

Parameter(s)	Notes
phone_number message_reference call_parameters	These parameters are stored and passed back to the application start_url as POST variables.
phone_number	To dial an extension number, the format is: tel:[phone];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:[phone];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').
start_url	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.
result_url	Outbound system posts result either after all retry attempts have been made or after the call successfully completes.
message_reference call_parameters	Typically, the message_reference POST variable passes a single call identifying string that the start URL uses to customize the call session. The call_parameters POST variable is used for arbitrary data with possibly several different parameters sent in a single string. It is up to the user to format and parse the data within the call_parameters string.
scheduled_timestamp expiration_timestamp	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.

Multiple Outbound Calls

Notes on queuecalls.php form data parameters.

Parameter(s)	Notes
phone_list campaign_parameters	These parameters are stored and passed back to the application start_url as POST variables.
phone_list	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.
start_url	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.
result_url	Outbound system posts result either after all retry attempts have been made or after the call successfully completes.
campaign_parameters	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.
scheduled_timestamp expiration_timestamp	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.