# Handle Incoming Conversations

We can simplify the process of managing inbound conversations by letting Twilio Conversations create new conversations for you automatically. This means that every time Twilio Conversations receives a new message from a number that is not yet participating in an existing conversation, it will create a new conversation with the message's sender as a participant.

With the ["Autocreate a Conversation" feature enabled](/docs/conversations/inbound-autocreation#settings-for-enabling-autocreation-in-conversations), an incoming message from an unknown number (that is not a participant of any conversation) will create a new conversation with a participant automatically.

## Create a new conversation

To test the "Autocreate a Conversation" feature, let's send a text message to a Twilio number and see if a conversation is created.

1. Make sure that the number you send a message **from** is not in a conversation already. You can do so by listing all active conversations:

   ```bash
   twilio api:conversations:v1:conversations:list
   ```

   And then list the participants in each conversation:

   ```bash
   twilio api:conversations:v1:conversations:participants:list --conversation-sid=CHXXX
   ```

   If you see your number as a participant, [remove it from the conversation](/docs/conversations/api/conversation-participant-resource#delete-a-conversationparticipant-resource) (alternatively, you can [delete the conversation](/docs/conversations/api/conversation-resource#delete-a-conversation-resource)):

   ```bash
   twilio api:conversations:v1:conversations:participants:remove --conversation-sid=CHXXX --sid=MBXXX
   ```
2. Now send a new text message **to** a Twilio number that is configured for Twilio Conversations.

Finally, check if a new conversation was created:

```bash
twilio api:conversations:v1:conversations:list
```

> \[!WARNING]
>
> If the above steps fail to create a new conversation even after you've enabled the ["Autocreate a Conversation" feature](/docs/conversations/inbound-autocreation#settings-for-enabling-autocreation-in-conversations), make sure that you do not have any relevant [pre-action webhooks](/docs/conversations/conversations-webhooks#webhook-action-triggers), like `onConversationAdd`, enabled either globally or at the service level. If these are enabled, Twilio will wait for an `HTTP 200 OK` response before creating the conversation.

What we're missing from our newly created conversation is a Twilio Frontline user. That's you! You can add a Frontline user to the conversation with **routing**.

## Inbound Routing

> \[!NOTE]
>
> The routing method can be configured in the [Twilio Frontline Console](https://www.twilio.com/console/frontline/routing).

![Flowchart of Frontline inbound routing for incoming text messages with conversation and participant handling.](https://docs-resources.prod.twilio.com/a6d13b6c98294821027e3b6b327866a90cbf5c2a3aa0f5e96e13e7dca32d6d01.jpg)

The diagram above shows the inbound routing process for Conversations. A customer creates a conversation by sending a message to a Twilio phone number. If the **onConversationAdd** webhook is enabled (e.g. in [global webhooks](/docs/frontline/conversations-webhooks#configure-webhook-urls-and-filters) for Conversations), it will be called before the next step.

There are three options to handle the routing of incoming conversations: **Do not route**, **Custom routing** and **Pool routing**. With **Do not route** routing, a Conversation will be created but it won't be routed.\
The **onConversationRoute** webhook will be called after a conversation is created for routing. The **onParticipantAdded** webhook will be called when a participant has been added to the conversation.

### 1. Do Not Route

Incoming conversations won't be routed to workers (Frontline users), but they will be visible within conversation logs.

### 2. Custom Routing

You can use Custom Routing to specify which customers should be routed to which Frontline users, rather than having it handled automatically.

If Custom Routing is enabled, the **Custom Routing Callback URL** will be called when an inbound conversation is created. You can configure the Custom Routing Callback URL in the [Twilio Frontline Console](https://www.twilio.com/console/frontline/routing).

Before routing, there are two [Conversations webhooks](/docs/conversations/conversations-webhooks) that we will make use of for updating the conversation with customer information:

* [onConversationAdd](/docs/conversations/conversations-webhooks#onconversationadd) — This webhook will be called before a conversation is created. We can use this to set a friendly name and an avatar for the conversation.
* [onParticipantAdded](/docs/conversations/conversations-webhooks#onparticipantadded) — This webhook will be called when a participant has been added to the conversation. You must add a `customer_id` to the participant and, optionally, a `display_name` and `avatar`. You can find all the details of these properties in the [My Customers documentation](/docs/frontline/my-customers).

For routing, we will use the Frontline custom routing callback:

* [onConversationRoute](#onconversationroute) — This webhook will be called after conversation is created for routing.

Now let's configure a project for custom routing.

#### Configuring custom routing

> \[!NOTE]
>
> Throughout the following, we'll refer to files in the [Node.js Frontline Integration Service](/docs/frontline/frontline-integration-service). You can clone the [Github repository](https://github.com/twilio/frontline-demo-service) and view/edit the files locally. To complete the steps, you'll need to have your Frontline mobile app downloaded and configured according to the [Node.js Quickstart](/docs/frontline/nodejs-demo-quickstart#configure-single-sign-on).

1. Set the two webhooks in the [Twilio Conversations Console](https://www.twilio.com/console/conversations/configuration/webhooks). First, set the **Pre-Event URL** and **Post-Event URL** to target your webhook URL. Now select the **onConversationAdd** and **onParticipantAdded** options under **Webhook Filtering**:

   ![Conversations API webhook configuration with pre-event and post-event URL settings and webhook filtering options.](https://docs-resources.prod.twilio.com/10a2e86a080a52dd0f177f934a082812e9b51c41c2a198f04750be48ce334073.png)

   Click on **Save**.
   Twilio will now call our integration service's `/callbacks/conversations` endpoint for **onConversationAdd** and **onParticipantAdded** events. It will provide event information in the call's body, and we can use it to set the conversation and participant information. In the Node.js Frontline Integration Service, you can view the file `src/routes/callbacks/twilio-conversations.js` to see how it is done.
2. Let's enable custom routing using the [Twilio Frontline Console.](https://www.twilio.com/console/frontline/routing) First, select **Custom routing,** set the **Custom routing callback URL** (we'll use the `/callbacks/routing` endpoint of the Frontline Integration Service) and click **Save**.

   ![Inbound routing settings with options for do not route, custom routing, and pool routing with a default pool.](https://docs-resources.prod.twilio.com/4067e213d95cf4d8d98cf7d2f77525f0310efc629baea1831cfe65cf44f4ae4c.png)
3. Now whenever a conversation is created, Twilio will call your integration service's `/callbacks/routing` endpoint. It will include [event information](/docs/conversations/conversations-webhooks#onconversationadded) in the request body. Using that information, we will decide which Twilio Frontline user to add to the new conversation. In the Node.js Frontline Integration Service, open the file `src/routes/callbacks/routing.js` to view the event handler code.
4. For configuring the phone number - worker relation, let's take a closer look at the `findWorkerForCustomer()` function in `src/providers/customers.js`. This function is responsible for finding an appropriate user for the incoming conversation. In our integration service, we do this by mapping a user identity to a phone number, like so:

   ```javascript
   {
     'whatsapp:+12345678': 'john@twilio.com'
   }
   ```

   Here, `whatsapp:+12345678` is your customer's phone number (an incoming conversation phone number) and `john@twilio.com` is the email address (user identity) used to identify a chat user (the Twilio Frontline user).

   To make `findWorkerForCustomer()` work, open `src/providers/customers.js` in the Frontline Integration Service and set the variable `customersToWorkersMap` to the mapping between your conversations-enabled Twilio number and your Twilio Frontline user identity.
5. Restart the Frontline Integration Service and create a new conversation by following [the steps above](#create-a-new-conversation). Open the app again, and you should see your new conversation!

### 3. Pool Routing

If **Pool Routing** is enabled, incoming conversations will be distributed to available Twilio Frontline Users automatically.

There are two [Conversations webhooks](/docs/conversations/conversations-webhooks) that we will make use of:

* [onConversationAdd](/docs/conversations/conversations-webhooks#onconversationadd) — This webhook will be called before a conversation is created. We can use this to set a friendly name and an avatar for the conversation.
* [onParticipantAdded](/docs/conversations/conversations-webhooks#onparticipantadded) — This webhook will be called when a participant has been added to the conversation. You must add a `customer_id` to the participant and, optionally, a `display_name` and `avatar`. You can find all the details of these properties in the [My Customers documentation](/docs/frontline/my-customers).

Now let's configure a project for automatic routing.

1. Set the two webhooks in the [Twilio Conversations Console](https://www.twilio.com/console/conversations/configuration/webhooks). First, set the **Pre-Event URL** and **Post-Event URL** to target your webhook URL. Now select the **onConversationAdd** and **onParticipantAdded** options under **Webhook Filtering**:

   ![Conversations API webhook configuration with pre-event and post-event URL settings and webhook filtering options.](https://docs-resources.prod.twilio.com/10a2e86a080a52dd0f177f934a082812e9b51c41c2a198f04750be48ce334073.png)

   Click on **Save**.
   Twilio will now call our integration service's `/callback/conversations` endpoint for **onConversationAdd** and **onParticipantAdded** events. It will provide event information in the call's body, and we can use it to set the conversation and participant information. Open the Frontline Integration Service file `src/routes/callbacks/twilio-conversations.js` to see how it is done.
2. Let's enable user pools using the [Twilio Frontline Console.](https://www.twilio.com/console/frontline/routing) First, select **Pool routing** and click **Save**. Next, click **Default Pool** to view the pool's details:

   ![Frontline Pool Routing.](https://docs-resources.prod.twilio.com/01f11d3d55bac07f8e9005bd956a77ab534feca60e58f04c0e317b010918f8e6.png)
3. By default, new users will be added to the default pool automatically. You can remove users from the pool if you don't want them to join new conversations. If users temporarily don't want to join new conversations, they can use the Frontline app to set their status to **Unavailable**. If there are no available users in the pool, new conversations will be queued until a Twilio Frontline User becomes available.

   ![Default pool worker list with email, ID, status unavailable, and remove option.](https://docs-resources.prod.twilio.com/db0b8fd5b5195aedb2667adc3051ab4e95f19d102d074352f5555bbfd308bad1.png)
4. Now try creating a new conversation by texting to a Twilio phone number.

### Custom Routing Callback request parameters

#### onConversationRoute

| **parameter name**                | **type**             | **description**                                                                                                                     |
| --------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| EventType                         | string               | Always `onConversationRoute`                                                                                                        |
| ConversationSid                   | string, SID          | Conversation Sid identifier                                                                                                         |
| DateCreated                       | string, ISO8601 time | The date of creation of the conversation                                                                                            |
| DateUpdated                       | string, ISO8601 time | The last modification date of the conversation                                                                                      |
| FriendlyName                      | string, optional     | The friendly name of the conversation, if set                                                                                       |
| UniqueName                        | string               | The unique name of the conversation                                                                                                 |
| Attributes                        | string               | Conversation metadata as set by the customer, represented as stringified JSON                                                       |
| ConversationServiceSid            | string, SID          | Conversation Service SID                                                                                                            |
| MessagingBinding.ProxyAddress     | string               | Twilio phone number used by channel creator                                                                                         |
| MessagingBinding.Address          | string               | Originating phone number of the channel creator                                                                                     |
| MessagingBinding.ProjectedAddress | string               | The address of the Twilio phone number that is used in Group MMS. Communication mask for the Conversation participant with Identity |
| MessagingBinding.AuthorAddress    | string               | Number of the message author when auto-creating Group MMS                                                                           |
| State                             | string               | Enumerated type representing the state of the conversation                                                                          |