Menu

Expand
Rate this page:

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, an incoming message from an unknown number (that is not a participant of any conversation) will create a new conversation with a participant automatically.

To test it out, 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:

    twilio api:conversations:v1:conversations:list​
    And then list the participants in each conversation:

    twilio api:conversations:v1:conversations:participants:list --conversation-sid=CHXXX​
    If you see your number as a participant, remove it from the conversation — or just delete the entire conversation:

    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.
  3. Finally, check if a new conversation was created:

    twilio api:conversations:v1:conversations:list​

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

Inbound Routing

The routing method can be configured in the Twilio Frontline Console.

The following diagram shows the inbound routing process for Conversations. A Conversation is created by a customer when sending a message to a Twilio Phone number. The onConversationAdd webhook will be called before creating a conversation. 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.

Frontline Inbound Routing.jpg

1. Do Not Route

Incoming conversations won’t be routed to workers, but they will be visible within conversation logs.

2. Custom Routing

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.

Before routing, there are two Conversations webhooks that we will make use of for updating conversation with customer information:

  • 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 — 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, display_name and avatar. You can find all the details of these properties in the My Customers documentation.

For routing, we will use Frontline custom routing callback:

  • onConversationRoute — This webhook will be called after conversation is created for routing.

Now let’s configure a project for custom routing.

  1. Set the two webhooks in the Twilio Conversations Console. First, set the Pre-Event URL and Post-Event URL to target your ngrok URL. Now select the onConversationAdd and onParticipantAdded options under Webhook Filtering:
    Frontline conversations webhooks for pools.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. Open the Frontline Integration Service file src/routes/callbacks/twilio-conversations.js to see how it is done

  2. Let’s enable custom routing using the Twilio Frontline Console. First, select Custom routing, set Custom routing callback URL and click Save.
    Frontline Custom Routing
  3. Now whenever a conversation is created, Twilio will call your integration service’s /callbacks/routing endpoint. It will include event information in the request body. Using that information, we will decide which Twilio Frontline user to add to the new conversation. Open the Frontline Integration Service file src/routes/callbacks/routing.js to view the event handler code.

  4. For configuring 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:

    {
      '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 used to identify a chat user (the Twilio Frontline user).

    To make findWorkerForCustomer() work, set the variable customersToWorkersMap to the mapping between your conversations-enabled Twilio number and your Twilio Frontline user identity. Restart the integration service and create a new conversation by following the steps above. 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 that we will make use of:

  • 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 — 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, display_name and avatar. You can find all the details of these properties in the My Customers documentation.

Now let’s configure a project for automatic routing.

  1. Set the two webhooks in the Twilio Conversations Console. First, set the Pre-Event URL and Post-Event URL to target your ngrok URL. Now select the onConversationAdd and onParticipantAdded options under Webhook Filtering:
    Frontline conversations webhooks for pools.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 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. First, select Pool routing and click Save. Next, click Default Pool to view the pool’s details:

    Frontline Pool Routing

  3. By default, new users will be added to the default pool automatically. You can remove users from pool if you don’t want them to join new conversations. If users don’t want to join new conversations temporarily, they can use the Frontline app to set their status to Unavailable. If there are not users in the pool, new conversations will be queued until a Twilio Frontline User becomes available.

    Frontline Pool Detail

  4. Now try creating a new conversation by texting to 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 Brand 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 state of the conversation

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more