Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Inbound Message Handling & Autocreation

Twilio Conversations is built for two-way messaging, so handling inbound messages is critical for your end-user experience. This guide describes the rules that determine where an inbound message goes, as well as how you can use the Conversations API to change that outcome.

Key Principle: the To/From number pair

key-principle-the-tofrom-number-pair page anchor

In all supported messaging channels (SMS, MMS, WhatsApp), a Participant in a Conversation is defined by their number pair. This is essentially the To/From pair on the Message:

  • the sender, or From number, corresponds to a MessagingBinding.Address (a consumer's number)
  • the receiver, or To number, corresponds to a ProxyAddress (a Twilio number)

You can think of a ProxyAddress as a Participant's window into a given Conversation, which may include another SMS or chat Participant. The sender sends Messages from their mobile number to the Twilio number in order to participate in the Conversation. Notably, the SMS Participant receives all of the messages through that one proxy address number, and they don't know how many people it represents.

Please note: Only one Conversation — that is, one Participant in an Active Conversation — can bind a number pair together. In other words, a Participant's to/from number pair can only be in one active Conversation at the same time.

Because that number pair is unique, it determines the Conversation where an inbound SMS or WhatsApp Message goes. And this constraint applies to the entire pair, meaning:

  • The same consumer can be in contact with multiple Twilio numbers (different Participants, and different Conversations). For example, a consumer can be part of different Conversations by binding their personal mobile number to different ProxyAddresses (one ProxyAddress for each Conversation).
  • The same Twilio number can be in contact with any number of consumers. For example, a single Twilio Proxy number can represent multiple customer service agents, each chatting with different end users in separate Conversations.

Once a Participant is created, that number-pair is bound together until one of the following happens:

  • that Participant is removed,
  • the Conversation is deleted, or
  • the Conversation State is set to closed .

Conversations vs. Programmable Messaging Inbound

conversations-vs-programmable-messaging-inbound page anchor

If you're already familiar with Twilio Programmable Messaging(link takes you to an external page), Conversations also uses webhooks to trigger actions. You can use Conversations webhooks to do things like add chatbots, add automatic replies, and implement spam filtering. However, Conversations has one significant difference: it does not send incoming SMS webhooks like Programmable Messaging does. Those webhooks fire independently.

There are two things determining how Conversations handles inbound messages. The first is the "to/from number pair" principle described above.

The second key factor is a rule: If the Message belongs in a Conversation, the Conversation captures it first.

Specifically, if the number-pair matches a Participant in an active Conversation, that Message is delivered to the Conversation. This triggers Conversations Webhooks and commits that Message to the Conversation Messages list. The message will also appear in the Programmable Messaging logs and will be processed as a normal SMS.

Inbound Auto-creation Flow for Conversations.

A Console redesign is planned to allow selecting both the Programmable Messaging webhook and the Conversations Autocreation feature as per the flowchart above. Currently, you can select only one or the other.

If the Message does not belong to a Conversation, one of two things could happen. Either:

  1. The ordinary Programmable Messaging webhooks are invoked (with the Incoming Message Webhook ) or
  2. Conversation Autocreation is invoked

For the second option, you can use the Address Configuration API to enable the Conversation Autocreation feature, or you can set the configuration in your Messaging Service. The latter takes effect for any Message to any numbers in that Messaging Service. For that reason, there's a separate opt-in switch in the Conversations console that you need to "unlock" first.

If the phone number's own webhook is set, it will always fire regardless of whether the number is tied to any Conversation.

Settings for enabling Autocreation in Conversations

settings-for-enabling-autocreation-in-conversations page anchor

You can enable Autocreation through either the Address Configuration API or the Twilio Console.

Enabling Autocreation through the Address Configuration API

enabling-autocreation-through-the-address-configuration-api page anchor

You can now use the Address Configuration API to specify which unique address (i.e. WhatsApp or SMS phone number) should enable the Conversations Autocreation feature upon receiving an inbound message, independent of the usage of the Messaging Service. With this API, you can enable and configure inbound messaging for individual addresses to support your use case.

Enabling Autocreation through the Twilio Console

enabling-autocreation-through-the-twilio-console page anchor

You can also configure Autocreation for your Messaging Service in the Twilio Console so that any Message that does not already belong to a Conversation (as identified by the number-pair) will automatically have one created.

First, in the Messaging Service, the Handle Inbound Messages with Conversations option should be toggled to Unlocked.

'Handle Inbound Messages with Conversations' toggle switched to UNLOCKED.

Second, in the Integration Section of Programmable Messaging in the Console, the Autocreate a Conversation option should be selected. (You can select Autocreate a Conversation only if the Handle Inbound Messages with Conversations toggle is set to Unlocked.)

'Autocreate new Conversation' option selected under 'Integration' of Messaging Service.

Make sure to click Save to implement your changes!



After enabling or disabling Autocreation in the Twilio Console, your changes may take up to 60 seconds to take effect. During these 60 seconds, the previous setting will be in effect.

Webhooks on Autocreation

webhooks-on-autocreation page anchor

Autocreation creates several resources in rapid succession, all of which produce webhooks:

  • onConversationAdd (pre-action webhook) will fire, containing the Message body and the complete number pair. You can either accept this Conversation (triggering the remaining webhooks) or reject this request to prevent Conversation autocreation. If you reject this, the Message will be dropped, as specified for this webhook.
output for eventType onConversationAdd Webhook.

If your server code responds with 200 OK:

  • onConversationAdded will fire, indicating the successful creation of a new Conversation.
  • onParticipantAdded will fire, describing the number pair above.
  • onMessageAdded will fire, describing the Message body.

Please note that onParticipantAdd and onMessageAdddo not fire during autocreation. The only opportunity to reject this Message is upon the creation of the Conversation itself. In other words, with Autocreation enabled, you can only reject a Conversation Message by stopping the entire creation of the Conversation.



Webhooks will not fire if you disable them globally or at the service level. If a webhook is not firing as expected, check your Webhook Filtering settings in the Twilio Console at the global level or Conversation Service level to make sure that the relevant webhooks are enabled.

Example: How Webhooks and Conversation Participants interact

example-how-webhooks-and-conversation-participants-interact page anchor

Let's say that you have already purchased a Twilio Phone Number and have set up the incoming SMS URL to point to your web application, as described in the SMS documentation. At this point, when you receive incoming SMS Messages on your Twilio Phone Number, Twilio will send a request to the webhook URL that you specified.

Next, suppose you create a Conversation Participant (with a to/from number pair, as described above) that binds a mobile number A to your Twilio Phone Number. That particular to/from number pair (and only that pair) is now bound to Conversations, but Messages from any other mobile numbers (B, C, D) remain unbound and continue to trigger webhooks to the SMS URL that you set above.

Effectively, you've moved a single relationship (mobile number A to your Twilio Phone Number) onto Conversations, but the rest of your customers (mobile numbers B, C, and D) remain on the pre-established setup.

As soon as you delete that Conversation Participant (mobile number A and Twilio Phone number), you start getting incoming SMS webhooks again, rather than having the Messages routed to Conversations.

Guidance for migrating to Conversations with Autocreate

guidance-for-migrating-to-conversations-with-autocreate page anchor

With Twilio Conversations, you can automatically create new Conversations for inbound messages. If you are already using Programmable Messaging to process inbound messages, we recommend that your switch to Conversations follow the following pattern.

1. Create Conversations explicitly via REST

1-create-conversations-explicitly-via-rest page anchor

Initially, you should leave Autocreate disabled and migrate one Conversation at a time, creating those Conversations using the Conversations REST API. The rules described above work in your favor here: Your existing Programmable Messaging logic (i.e., your incoming SMS webhook) will hold for all inbound Messages except those for which you create a Conversation Participant that binds to that number pair.
By doing this, you can test your logic on individual Conversations, which likely means one consumer-agent relationship at a time. Those migrated Conversations immediately receive full support from the browser and mobile SDKs, and Conversations webhooks fire specifically for those Conversations. This keeps risk low while you explore and develop.

2. Start with an empty Messaging Service, then enable Autocreation

2-start-with-an-empty-messaging-service-then-enable-autocreation page anchor

Usually, to handle inbound Messages in customer service use-cases (where consumers reach out unsolicited), you'll want to enable Autocreation. In order to mitigate risk while migrating from Programmable Messaging, we recommend starting from an empty Messaging Service, i.e. remove all Senders from the Conversations Messaging Service. After doing so, it will be safe to enable Autocreation for Conversations.
With an empty Messaging Service sender pool attached to a Conversation, you can enable Autocreate without affecting your existing SMS applications and Phone Number webhook logic.

3. Migrate one Phone Number at a Time

3-migrate-one-phone-number-at-a-time page anchor

At this point, your logic is in place, so you can begin moving over Phone Numbers to your Conversations Messaging Service slowly, ensuring that the logic is correct.
One at a time, add your Twilio Phone Numbers to the Conversations Messaging Service. Autocreate will immediately take hold for those numbers that you add to the sender pool — and only those numbers. We recommend observing and spot-testing between the first migrations, looking for any incidental errors.

4. Use the REST API to complete the migration

4-use-the-rest-api-to-complete-the-migration page anchor

Once it's clear that no bugs are emerging, you can accelerate your migration by using the Messaging Service REST API to add phone numbers to your Messaging Service from a script. Once all the numbers are on the Messaging Service, Autocreation applies immediately to the full set of numbers in the Service's Sender Pool.

How Group MMS handles inbound messages

how-group-mms-handles-inbound-messages page anchor

If you're using our public-beta Group MMS support (from the US or Canada) the same rules apply as above: if the Message is destined for a Conversation, the Conversations API will deliver it to the correct Conversation, as well as fire the appropriate webhooks.

Otherwise, as above, either inbound Autocreation or ordinary (non-Conversations) Programmable Messaging webhooks take hold. (Note that Twilio Programmable Messaging does not support Group MMS). The switch to enable Autocreation for Group MMS is exactly the same.

Autocreation in Group MMS

autocreation-in-group-mms page anchor

However, there are a few differences in inbound handling and Autocreation for Group MMS.

The "Number Pair" becomes the "Number Group"

the-number-pair-becomes-the-number-group page anchor

When managing 1:1 Conversations, it generally makes sense to use Address+ProxyAddress number pairs, with both numbers (the Twilio Phone Number and the personal mobile number) assigned to the SMS Participant in question. This is what we saw above.

In Group MMS Conversations, Participants look different:

  • Participants on SMS only have Address ( no ProxyAddress ).
  • Application-side Participants ("chat" Participants) will have a ProjectedAddress .
  • You may have up to twenty (20) total Addresses and ProjectedAddresses in a Group MMS Conversation.

Therefore, for Group MMS, the "number pair" principle described above no longer applies. Instead, the inbound target of a Group MMS Message is the "number group." To arrive at a Conversation, the sorted set of all senders (From=) and receivers (To=) on the Message must match the sorted set of Addresses and ProjectedAddresses on some existing Conversation.

Autocreation Webhooks for Group Texts

autocreation-webhooks-for-group-texts page anchor

When autocreating a Group MMS Conversation, the order of webhooks has two important nuances:

First, onConversationAdd contains a complete list of all Participants across MessagingBinding.Address (the receivers) and MessagingBinding.AuthorAddress (the sender).

Second, the state of the Conversation remains at initializing — meaning that the Conversation cannot be changed except to accept or reject changes — until the onConversationStateUpdated webhook indicates that all the resources have been created.

With inbound message handling and autocreation, you can create seamless conversational messaging for your end users. Check out some of our other resources to continue building with Twilio Conversations:

Rate this page: