Outbound Parameters

Advanced Outbound Call Features

Fuse provides additional parameters that impact how a call behaves. You can take advantage of these features by sending the appropriate parameter when sending the request to queue an outbound call.

For information on how to call the outbound API, please refer to the API section. For information on how to manually queue outbound calls, please refer to the Outbound section.

Phone Destination

Field name

  • API: phone_number

  • CSV Upload: destination

This dictates the destination phone number for the outbound call.

Setting Caller ID

Outbound calls placed from Fuse do not have a default caller ID value. You can use a parameter to control the specific caller ID that your customers see when their phone rings. To do this, you make use of telephony URLs, which allow you to set an Automatic Number Identification (ANI) value.

For example, if you wanted to place a call to the phone number 212-555-1234 and have the caller ID display 800-995-7586, then you would send a phone_number POST parameter of:

tel:+12125551234;ani=8009957586

Note: Setting an invalid caller ID value can cause your calls to be rejected.

It is always best to use a phone number that you control so that if callers attempt to call you back you can route the callers to the correct resource.

Values

There are multiple ways to format phone numbers. They can include the '​tel:'​ prefix and/or the ANI and postd suffixes, e.g. ani=8009957586 and/or postd=2 (postd allows a simulation of pressing a DTMF value).

Examples of valid numbers include

6175551234
tel:​+16175551234
16175551234;​ani=8009957586
16175551234;​postd=2

It is also possible to combine all of these options:

tel:​+16175551234;​ani=8009957586;​postd=2

Call Scheduling

Field name

  • API: start_timestamp and end_timestamp

  • CSV Upload: the start / end times can be specified in the call range field in the interface

If you have one or more calls queued for outbound calling and would like to schedule those calls to be placed within a fixed timeframe, Fuse provides two POST parameters to enable this.

By default, the system does not have any limitations for when calls can be placed. Unless otherwise scheduled, queued calls will be placed as soon as possible and continue until all calls in the queue are complete.

The start_timestamp and end_timestamp parameters set start and end times, respectively, for the window when your application places the calls in the outbound call queue.

Note: Simply because a call is scheduled for a specific timestamp does not guarantee that it will be dialed. The system honors First-In, First-Out (FIFO) rules and is limited by the amount of available idle outbound capacity at any given time.

Queuing a large block of calls with a very small dialing window runs the risk of not having enough idle outbound capacity to work through the call queue. Any calls that are not dialed when they reach the end_timestamp will be updated to canceled status. The start and end parameters are not dependent; you can set either one or both.

Re-attempting Calls

By default, Fuse outbound call queues make one attempt to dial a number in the call queue. If that call is unsuccessful after one attempt, the app marks the call as failed. However, you have the ability to increase the number of call attempted and to specify the interval for subsequent attempts.

Two POST parameters control re-attempt rules in Fuse.

  • The max_attempts parameter sets the total number of attempts the app makes for each call in the queue.

  • The reattempt_wait parameter sets the amount of time to wait (in seconds) between each call attempt.

These parameters are mutually dependent: If you set max_attemzpts you must also set reattempt_wait. Failure to do so will result in an error when queuing.

Additional Outbound Call States

Simply placing a call does not guarantee that the call will connect. Calls that go unanswered can trigger additional states in Fuse outbound call queues.

  • busy - the call was unable to connect because the far end was unavailable

  • noanswer - the call was not answered within 45 seconds

  • informationtone - the number dialed was invalid

When the application exhausts the maximum number of attempts without the call moving into the connected state, the system flags the call as failed and sends a request to the original result_url parameter if one was set.

Result Callbacks

Fuse can notify you when your outbound call queue completes using a callback URL. This allows you to update your records for each individual call and take any other, necessary actions.

The POST parameter result_url allows you to define an API endpoint on your web servers that will receive a POST request from Fuse after the call status updates to either completed, failed or canceled.

The callback URL receives a JSON POST string that contains all the details about the call, including any events that occurred.

Here is a sample JSON POST string:

{
"max_attempts": "1",
"attempts": "1",
"events": [
{"event": "queued","timestamp": 1475095892},
{"event": "dialing","timestamp": 1475095893},
{"event": "connected","timestamp": 1475095925},
{"event": "disconnected","timestamp": 1475095928}
],
"phone_number": "'6173720293'",
"status": "completed",
"queued_timestamp": "1475095892",
"start_timestamp": "1475095925",
"end_timestamp": "1475095928",
"reattempt_wait": "300",
"duration": 3
}

Metadata

When placing outbound calls you may want to provide specific, dynamic information to your recipient that can be referenced by your Fuse application. For example, you may want to state the call recipient’s name in the initial prompt. Rather than forcing your Fuse application to use a web service to lookup call specific details at the start of the call, you can push variables directly into your application using the POST parameter metadata.

The metadata parameter should be sent as a JSON object that contains key / value pairs. Your Fuse application automatically imports any keys you set in the metadata into your application.

For example if you post the following JSON for your metadata:

{
"name":"John Doe",
"appointment":"Monday September 24th at 10am"
}

Fuse automatically creates two variables, name and appointment, that you can reference inside a Fuse module to create a dynamic prompt.

Security and the Metadata parameter

When it comes to the transmission and storage of sensitive data, Plum is a pass-through organization. This means Plum doesn’t store any information input during a call. Input data stays in temporary memory during the call and is purged when the call ends; no HIPAA or PCI level information is ever stored.

When queuing calls, you send information to Plum’s servers that needs to be stored for a given amount of time. Call queue data is not stored in a PCI-/HIPAA-secured database, and as a result, is not covered by Plum’s security certificates/policies. This includes information set in the metadata parameter.

Incorporating PCI/HIPAA information into a call-flow requires a two-step process.

  1. Queue a call using at least two pieces of information: a phone number and a unique, non-PCI/non-HIPAA identifier. (It is up to the customer to determine the identifier and ensure that it corresponds to the correct record in their database.)

  2. When the call connects, make a webservice request to your company’s database to fetch the information covered by PCI or HIPAA.

This process ensures that no sensitive data gets stored on non-PCI/HIPAA certified servers.

In addition to a unique ID number, you can set non-PCI/HIPAA data to a queued call. This enables you to present non-sensitive, personalized data, like customer name, before fetching sensitive data from your company database(s).

It is the customer’s responsibility to secure their data and to ensure that applications running on the Plum Fuse platform do not pass unsecured data, including any data set in the metadata parameter.

Bulk Call Queuing

You can queue calls individually or in bulk, depending on your outbound dialing needs. Each application deployment supports two different API endpoints. To this point, we have discussed the single call queue API endpoint.

A bulk_queue endpoint that supports an HTTP upload parameter csv also exists. This parameter allows you to upload a CSV file with a list of phone numbers to dial as well as specifying any additional metadata parameters that need to be set.

All other POST parameters for this service match those provided in the queue API

Fair Queuing

Each application deployment in Fuse automatically creates a first-in, first-out (FIFO) outbound queue. Fuse weights all your application deployments equally to ensure no single application starves out the rest.

For example, if you were to queue 10,000 phone calls with one application and then, a few minutes later, queue 100 phone calls into a second application, then the calls from both applications would be fairly distributed until the smaller queue completes. At that time, the remaining calls from the larger queue continue to be dialed until they were complete.