# Outgoing Conversations

## Starting Outgoing Conversations

So far we have seen ways to programmatically create a new conversation by either processing an incoming message or doing a direct API call, but how can an app user do that? Twilio Frontline has a dedicated **Outgoing Conversation callback** for that. Whenever a user initiates a new conversation from the Customer Details screen, the app will make an API request to the configured callback URL to facilitate the process.

When a user initiates a new conversation, the app does the following:

1. Creates a new conversation
2. Calls an outgoing callback with **GetProxyAddress** location. In order to add a customer to conversation the app needs to know how they're in contact with — i.e. what phone number or WA number they reach out to at — your business.
3. Adds a customer to the new conversation.
4. Adds a worker to the new conversation.
5. Navigates a user to the new conversation.

![Twilio Frontline integration with Conversations API and customer via outgoing callback URL and Twilio number.](https://docs-resources.prod.twilio.com/c50259bcbb6e80a13ae238cf841dd9515213686f8bc8d7cb7b985b0ef5c532be.jpg)

To configure it, [open Frontline console](https://www.twilio.com/console/frontline) and set the **Outgoing Conversation Callback URL** configuration option to a URL that will respond back with a proxy phone number.

![Outgoing Conversation Callback URL.](https://docs-resources.prod.twilio.com/110e0d261553425f3f3c993147511cab3e51c0fdb624e9d5d169fb0b667b5eba.png)

## Responding to Outgoing Conversation Callback

When the Frontline application makes a `POST` HTTP request to your server, it includes information about the action that triggered the callback to your web application. Each action has its own `Location` type. The Location will be sent with the rest of the parameters in the request body in `application/x-www-urlencoded` format.

In addition to the location-specific parameters, each request also contains the following parameters and information:

| **Parameter name** | **Type** | **Description**                                                                                                                   |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Location           | string   | A single callback URL might be used for different purposes. This parameter is meant to help to determine how to process a request |
| Worker             | string   | The app user identity                                                                                                             |

> \[!NOTE]
>
> Frontline will send a request with **`Content-Type`** header of `application/x-www-urlencoded` and will expect a response with **`Content-Type`** header of `application/json` and a body based on the `Location` parameter.

## GetProxyAddress

The application needs to know a proxy address in order to add a customer as a participant to an outgoing conversation. See an example in `src/routes/callbacks/outgoing-conversation.js` file.

**Request parameters:**

| **Parameter name** | **Type** | **Description**                                                     |
| ------------------ | -------- | ------------------------------------------------------------------- |
| CustomerId         | string   | Customer ID provided by the server                                  |
| ChannelType        | string   | The channel type. It can be `sms`, `whatsapp`, `chat`               |
| ChannelValue       | string   | The channel address. Example: `+123456789` or `whatsapp:+123456789` |

**Response format:**

| **Parameter name** | **Type** | **Description**                                           |
| ------------------ | -------- | --------------------------------------------------------- |
| proxy\_address     | string   | A Twilio proxy number to be used in outgoing conversation |

**JSON response example:**

```json
{
  "proxy_address": "+123456789"
}
```