# Outbound Calling Guide
## Overview
### Outbound Applications
IVR applications commonly start with an inbound call from an end-user. However, businesses may also want to initiate proactive, outbound communications with end-users.
The Plum Outbound system provides a platform-independent HTTP interface for initiating and managing use cases for outbound calling.
### Features
The Plum Outbound service provides:
* An HTTP-based interface for queuing outbound calls.
* Flexible scheduling and redial rules.
* Schedule calls in advance and set parameters for when call attempts expire.
* Automate retries on busy or no-answer calls.
* Dynamic call scripts.
* Full VoiceXML 2.0 scripting support.
* Callee-type detection: Alter call-flows based on the detected callee-type.
* Personalize messaging in outbound calls using specific parameters.
* Web-user interface for server administration and management.
* Call queue review and management
* Globally suspend/resume calls for all client applications
## Interfaces
Client applications must implement three interfaces in order to successfully utilize outbound calling: the Outbound APIs, the **`start_url`**, and the **`result_url`**.
The client application server posts a `queuecall.php` or `queuecalls.php` request to the Plum Outbound service. This request includes the number(s) to be dialed and the parameters that specify redialing and scheduling rules.
As detailed below, this request includes two callback URL's specified by the client application.
* The **`start_url`** indicates the page the VoiceXML script fetches to start the application when the call connects.
* The **`result_url`** indicates the client-side interface that gathers call results at the conclusion of the call or after the call fails for the last time.
{% hint style="success" %}
Before outbound calls go out, the outbound service sends a GET request to confirm that the **`start_url`** and **`result_url`** each return an HTTP 200 OK response. If these URLs don't return this response, the queuecall(s) operation fails.
{% endhint %}
### *1.* [*DEV Outbound APIs*](/dev/plum-dev-apis/dev-outbound-apis.md)
This consists of one of two php scripts - `queuecall.php` or `queuecalls.php`**.**
{% hint style="info" %}
If the desired outbound campaign was previously stopped, activate the campaign by clicking the Start button in the “Campaign Status” column located on the [Outbound Configuration page](/dev/plum-dev-guide/outbound-calling-guide/using-the-outbound-tools.md) in DEV's web UI. This enables sending outbound calls.
{% endhint %}
#### Call Initiation
* **Queueing a Single Call with** `queuecall.php`
* Activate the default campaign, as indicated above.
* **Return**
* The `queuecall.php` script returns an XML-formatted document which lists the Plum outbound assigned **`call_id`** or an error message if the call could not be queued.
* **Creating a Call Campaign with** `queuecalls.php`
* All settings are applied to all calls in the campaign. However, **`message_reference`** and **`call_parameters`** are set on a per-call basis and are specified in the uploaded text file with each phone number.
* **Return**
* The `queuecalls.php` script returns an XML-formatted document which lists the Plum outbound assigned **`call_id`** or an error message if the call could not be queued.
### **2.** *Start URL*
1. Plum's server fetches the **`start_url`** from the application server using a GET method.
2. **`start_url`** callback returns the initial application VoiceXML.
#### start\_url Callback
The client application sets the **`start_url`** in the `queuecall(s).php` request. The **`start_url`** should return valid VoiceXML 2.0 scripts.
Return values: When Plum's outbound system requests the **`start_url`**, it sends a POST request with the following data:
| Parameter | Type | Description |
| -------------------- | ------ | ---------------------------------------------------- |
| phone\_number | int | Dialed phone number |
| call\_id | int | Call identifier assigned by Plum outbound service |
| message\_reference | string | Client-assigned call identifier |
| campaign\_parameters | string | Client-specified campaign-specific parameters string |
| call\_parameters | string | Client-specified call-specific parameters string |
### *3. Result URL (optional)*
1. Plum's server posts the **`result_url`** data to the application server using a POST method.
2. **`result_url`** callback logs and acts on the final call result.
#### result\_url Callback
The client application sets the **`result_url`** in either the `queuecall.php` or `queuecalls.php` request. The **`result_url`** acknowledges receipt of the call result by returning the text “completed”.
Returned values include:
| Parameter | Type | Description |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| phone\_number | string | Dialed phone number |
| message\_reference | string | Client-assigned call identifier |
| call\_id | int | Call identifier assigned by Plum outbound service |
| result | string | Completed, Failed |
| callee\_type | string | voice, answeringmachine, faxmachine, busy, noanswer, informationtone, linefailure, noattempt, unknown ([see more about callee types](/dev/plum-dev-guide/outbound-calling-guide.md#understanding-callee-types-and-outbound-statuses)) |
| attempts | int | Number of attempts made |
| last\_attempt\_timestamp | time | Last call attempt start time (Mon, 19 Jul 2004 13:46:03 -0400) |
| duration | int | The duration of the outbound session, in seconds |
## Data Flow and Control Flow
#### Outbound process for a successful call
### Phase 1: Initiation
* The outbound process begins when the customer application performs an HTTP POST to the Plum Outbound API (either `queuecall.php` or `queuecalls.php`). The POST includes a [phone number ](/dev/plum-dev-apis/dev-outbound-apis/contacts-csv-formatting.md)and a start URL. Customers can choose to include a result URL, too.
* Plum’s outbound API places the call(s) indicated in the customer application into the outbound calling queue on the Plum Voice Platform. \
### Phase 2: Calling
* Plum’s outbound queue is optimized for sending calls, so whenever an open VoiceXML channel is available on the Plum platform and the customer’s call is at the top of the Plum Outbound Queue, the call is placed.
* If the call connects successfully, the callee-type detection begins (if that option is enabled). At the same time, the parameters defined by the customer application (e.g., phone\_number, message\_reference, call\_parameters) are posted to the customer’s start\_url.
* At this point, the connected call progresses in accordance with the VoiceXML code for that call.\
### Phase 3: Call Completion & Post-Call Processing
* When the call completes, so too does the execution of all VoiceXML code for the call.
* The Plum Outbound Queue then moves to the next number in the queue and the process repeats phases 2 and 3 until the PV Platform works through all the calls in the queue.
* Post-Call Processing is a separate, but related process. It does not necessarily occur immediately upon the completion of a call or a call campaign. Once the platform processes the logs, the Outbound API posts a request to the result\_url for the completed call that includes all established parameters, if the customer included a result URL.
#### Outbound process for an unsuccessful call
The process is the same as outlined above. However instead of connecting in Phase 2, the call fails.
* The Plum Voice Platform updates the status to ‘Failed’.
* Any phone number with a status other than ‘Completed’ gets placed back in the call queue to be redialed.
* This process continues until the phone numbers reaches the maximum number of retries.
* If the phone number expires (i.e., maxes out retry attempts) the Plum Voice Platform posts a request to result\_url including all the parameters defined in the Outbound API (i.e. phone\_number, message\_reference, call\_id).
The process is identical for the Multiple Outbound Calls API **(`queuecalls.php`)** except the client uploads a [list of phone numbers](/dev/plum-dev-apis/dev-outbound-apis/contacts-csv-formatting.md) for the outbound web service to dial instead of a single number.
{% hint style="warning" %}
If an outbound campaign does not complete all calls in the queue before the session ends (the `scheduled_timestamp` and `expiration_timestamp` control the session window, see [Outbound APIs](/dev/plum-dev-apis/dev-outbound-apis.md)), the incomplete calls automatically expire and get cleared from the Outbound Queue. The Platform posts the details of the incomplete calls to the `result_url` and performs the `result_url` callback.
{% endhint %}
## Understanding Callee Types and Outbound Statuses
The callee is the recipient of an outbound call. Plum's platform attempts to determine the type of callee (also referred as callee type), whether human, answering machine, etc. This information can be useful for determining an appropriate greeting or knowing whether a call was answered.
#### An outbound call is considered 'completed' when callee types are:
1. **voice**: the call was answered by a person
2. **answeringmachine**: the call went to voicemail
3. **faxmachine**: the call detected a fax machine tone
For best user experience it is best to add [callee type detection](/dev/plum-dev-guide/outbound-calling-guide/dev-outbound-programming-notes.md#callee-type-detection) to your application.
#### An outbound call is considered 'failed' when callee types are:
1. **busy**: the line is in use
2. **noanswer**: the call was not picked up and did not go to voicemail
3. **informationtone**: the call detected an information tone; causes may include all circuits busy, number was disconnected, etc.
4. **linefailure**: similar to information tone, the call detected a failure when calling the number
#### In rare cases, an outbound call may produce miscellaneous callee types:
1. **noattempt**: this can cause an 'uncalled' or 'failed' status and may occur when campaign windows are too short for the amount of calls or cancelling the queue
2. **unknown**: this can cause a 'completed' or 'failed' status and occurs when our platform cannot determine the proper callee type
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.plumvoice.com/dev/plum-dev-guide/outbound-calling-guide.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.