outbound

Outbound

The Outbound interface is tied to a specific deployment of an application. For details about deployments and how to navigate to this interface, see the Deployments page. This interface allows users to view completed and pending outbound call lists, to view call logs for completed outbound calls, and to queue outbound calls.


Outbound Overview Guide

Fuse+ makes it possible to automate outgoing calls with your digital voice channel. Behind the scenes outbound calling is a little bit different from handling inbound calls. This guide serves as a high-level primer for how outbound calling functions in Fuse+

There are several different components to understand when developing applications for outbound calling, including:

  • how the outbound call queuing platform works
  • how to use the outbound APIs to queue calls
  • how to use the API options to trigger different behaviors
  • how to get the results of your calls.

For a complete list of API endpoints and parameters see the Fuse+ APIs page.


Basic Outbound Call Process

Every Fuse+ application has its own outbound calling queue. Outbound calls in Fuse+ are queued on a per application deployment basis. Fuse+ uses the URL that you queue your calls to identify the specific application deployment to execute when the call is answered.

Here are the basic steps of the outbound call process:

  1. A call is queued by sending a phone_number POST variable to the application deployment’s queue API. This also returns a unique call_id.
  2. The call is inserted into the queue and put into the queued state while waiting for idle outbound capacity.
  3. When idle outbound capacity is available the call is taken off the queue, dialed, and put into into the dialing state.
  4. When the call is answered it is placed into the connected state and the associated application executes.
  5. When the call disconnects it is placed in the completed state.

?nolink&921x203


Advanced Outbound Call Features

The previous section described the most basic outbound call process. 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.


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.


Call Scheduling

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_attempts 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.


Queuing Outbound Calls


To queue outbound calls, click the button at the top of the page. This opens a pop-up window containing the following options:

1. Upload CSV: Use this option to upload a CSV file that contains a list of contacts to dial. The file must be formatted to match one of Fuse's expected numbering formats. See the CSV Formatting for more details.
2. Number of Attempts: This sets the number of outbound attempts to make for each number if the first attempt is unsuccessful. This option accepts numeric values from 0-10.
3. Time to Wait Between Attempts: This is an optional setting users may wish to utilize if they enabled multiple attempts. This value indicates how long, in seconds, the Fuse application must wait before attempting the next outbound call to a given number. The option accepts numeric values from X-XXX.


Advanced Options: The following fields are not required, but available, if desired:

4. Call Range: (optional) Allows users to identify a specific window of time to attempt the outbound calls.
Calls go out immediately if no time is specified.
5. Result URL: (optional) Result URL callback, which will be called at the completion of each outbound call.

After filling in the desired fields, click the button to schedule the outbound calls.


Contacts CSV Formatting

There are several different acceptable formats for CSV contacts.
The only format restriction is that the first column header must be 'destination'. Other than that, users may supply optional columns of information. Fuse set these data as variables within your outbound call.

The following list provides samples of different phone number formats for 5 different contacts. Observe that none of these numbers have call variables set:

"destination"
"1234567890"
"1112223456"
"tel:12223456547"
"tel:+16177123000;ani=5553336666"
"19998886666"


Note the various supported phone number formats. Users can add optional parameters for phone number strings, e.g. 'tel', 'ani', etc. Phone number formatting in Fuse functions the same way it does in native VoiceXML.

The following file includes the same list of phone numbers, but with the additional variables 'first_name' and 'last_name' for use within the application:

"destination","first_name","last_name"
"1234567890","Steve","Smith"
"1112223456","Klein","Reynolds"
"tel:12223456547","Sloane","Bergeron"
"tel:+16177123000;ani=5553336666","Plum","Voice"
"19998886666","Keith","Johnston"

Viewing Pending Outbound Calls

Outbound calls that are in progress or scheduled to go out in the future appear in the Pending tab of the Outbound interface.
Click the “Pending” tab on the table to view these pending outbound calls.


Users can view pending outbound calls, cancel outbound calls that have not been dialed yet, and queue calls in this interface.


Pending Calls Table

When an application has one or more pending outbound calls, those numbers appear in the outbound calls table.
This table contains the following fields:

  1. Phone Number: The destination number for the outbound call.
  2. Queued Timestamp: The date/time that the outbound call was queued.
  3. Number of Attempts: The total number of attempts made for that number.
  4. Last Event: The last call event, including the date/time the event occurred. Possible values for this field include: queued, dialing, and connected.

Click the button in the top left of the Pending calls table to refresh the list of pending outbound calls,


Searching Pending Outbound Calls

To locate a specific destination number in the list of outbound calls, enter that phone number in the “Search” text box.


Canceling Pending Outbound Calls

To cancel pending outbound calls, click the button in the top right of the table. This opens a pop-up window that asks users to confirm the request to cancel pending outbound calls. Click to confirm canceling these calls.


Viewing Completed Outbound Calls

To view completed outbound calls, click the “Completed” tab on the Outbound Calls table.
This interface gives users the option to export completed outbound call data, clear all completed outbound call data, view a list of all completed outbound calls, and search the completed call logs.


Completed Calls Table

Applications that have one or more completed outbound calls display information about those calls in the outbound calls table. This table contains the following fields:

  1. Phone Number: The destination number for the outbound call.
  2. Status: The outcome of the outbound call. Possible values for this field include: “failed” and “completed”.
  3. Start Timestamp: The ate/time that the outbound call connected.
  4. Duration: The elapsed time of the outbound call.


Filtering Options

Users have several options for filtering the data displayed in the Outbound Calls table. To view calls made during a specific window of time, set the desired date(s)/time(s) with the Calling Window. Only calls made during the chosen time interval will display in the table. As mentioned above, use the “Search” box to locate a specific phone number. These two filter options can also be used in tandem.


Exporting Completed Call Data

To export all completed call data, click the button at the top right of the table. A CSV file containing the outbound call record will download automatically.


Clearing Completed Call Data

To clear the existing data from the Completed Call table, click the button in the top right section of the table. This opens a pop-up window asking users to confirm the data deletion. Click to clear the current data.


Callee Type Detection

When placing outbound calls, it is often necessary to alter the call flow based on the type of callee you have reached. For example you may wish to play a specific message in the case of an answering machine or proceed with the interactive call flow when you reach a person.

Fuse+ includes support for callee type detection through the global variable “session.connection.callee_type”.

The platform automatically updates this variable over the course of the first 4 seconds of the call. 
Initially the variable will contain the value “processing” and after 4 seconds it will be updated to be one of the following values:

  1. voice
  2. answeringmachine
  3. fax
  4. unknown

The recommended approach for using this variable is to play an initial prompt that is at least 4 seconds long and then use the 'Compare Variable' ( ) module to branch on the different values that “session.connection.callee_type”.

Here is an example of a module branching on the “session.connection.callee_type” value:


Detecting Voicemail Call Flow Example

While it is highly accurate, session.connection.callee_type is attempting to analyze potentially non-standard voicemail and answering machine behaviors, therefore, its performance is not guaranteed. It can and will have issues with certain types of voicemail or ring back behaviors that will lead to false positives / false negatives.

The best practice is for the initial prompt request the callee to press a button to accept the call, which guarantees that the call was connected to a person rather than a machine.


Consider the following example:


Person answers with DTMF Person answers by voice Answering Machine
Call scenario Callee presses any key Callee answers by voice (such as hi, hello) but not by touch tone key The call is directed to the answering machine
welcome The record module is used to see if the callee respond to the welcome prompt, Any touch tone input on the will then end the record module and continue onto the next module The record module is terminated by the final silence setting in the record module The record module is terminated by the final silence setting in the record module
check_response The welcome$.termchar value in the module will indicate that the recording is indeed terminated by a touch tone Since the recording ended by silence, welcome$.termchar is false and the application will branch to the right Since the recording ended by silence, welcome$.termchar is false and the application will branch to the right
check_callee_type Because there was a response from the caller within the first 4 seconds of the call, the platform will evaluate session.connection.callee_type as “voice” and therefore direct the application back to the left If the answering message is continuous throughout the first 4 seconds, the platform will evaluate session.connection.callee_type as “answeringmachine”
Resulting Module welcome_call_flow welcome_call_flow leave_voicemail
outbound.txt · Last modified: 2018/11/02 12:41 by admin