Rate this page:

Twilio Conversations Overview

Twilio Conversations is an omni-channel messaging product. You can use it to build engaging experiences on any channel we support.

With Twilio Conversations, you can, for example:

  • Connect customers with support agents via chat using our SDK
  • Bridge previously siloed channels with each other, like SMS and WhatsApp
  • Support customers on the channel they prefer from inside your existing tools
  • Reduce friction by handling simple requests using bots
  • Proxy messages between two SMS numbers

Any channel we support can be connected together. Conversations also supports common chat features like typing indicators and read horizon to enable pure chat applications.

Use of the Conversations API is limited to interactions involving at least one human participant. For application to application communication, please see

Let's dive into a few of the key concepts you'll need to know while working with Conversations. Let's get started!

What is a Conversation?

The Conversation object is a core component of Twilio Conversations. A Conversation is a distinct message thread that contains Participant objects, which represent humans or bots who are participating in the Conversation. A Participant sends a Message, which is relayed to every other Participant in the Conversation.

A Conversation

Messages are routed to a real-world endpoint, like an application that uses the Conversations SDK, a mobile phone’s SMS application, or a user’s inbox on Facebook Messenger.

Users connected via the Conversations SDK will be uniquely identified by their identity. This value is set in the Access Token you’ll generate and provide to your application.

For external channels like SMS, WhatsApp, and Messenger, the external address is mapped to a Twilio-controlled proxy address, like a Twilio phone number, a Twilio WhatsApp sender, or a Facebook page you connected to Twilio. This pair of addresses (external and Twilio-controlled) uniquely identifies a non-chat Participant in Conversations, and the proxy address acts as the external user’s "window" into the Conversation.

What is a Message?

Messages in a Conversation can contain text, media, or both. You can attach up to ten Media objects to a single Message. Because different channels support different file types and file sizes, resizing and delivery of media is the best effort, and you should ensure that media conforms to the limits of the channels involved in your Conversations.

What is a Message

You can learn more about Media Messaging in the SDK and in the REST API.

How do I connect Conversations to my application?

Twilio provides SDKs for JavaScript, iOS, and Android so that you can easily integrate Conversations into your client-side applications. Our SDK connects your application to Conversations via a WebSocket, which allows you to receive events and objects that are relevant to your application’s user in real time.

Connect Conversations with your app

To connect, you’ll generate a time-sensitive user-specific Access Token on your server and return it to your client-side application. The identity that you set in the Access Token will determine which User the SDK connects as.

Never store your Twilio account credentials in your client-side application

Once you’ve initialized it, you’ll be able to use the SDK to retrieve, create, modify, and delete Conversations, Messages, and other objects. We’ll also send you real-time events when changes happen, like when a new message is added to a Conversation or when your user is added to a new Conversation. You can use this information to build your user interface.

What are Users?

Your client-side application connects to Conversations as a specific User. Users can only access Conversations they have been added to. To add someone, you’ll need to create a new Participant in the Conversation. A User controls a unique Participant in each Conversation they’re a member of.


How do I join a Conversation?

When joining a Conversation from an external channel, you will be mapped to the Conversation via a channel-appropriate address controlled by Twilio. Examples of these include phone numbers you’ve purchased from Twilio, WhatsApp senders you’ve applied for on the Twilio’s platform, and Facebook pages you linked via the Twilio Console. These addresses are known as Proxy Addresses.

The Proxy Address acts as the person’s "window" into the Conversation. In other words, they’ll be exchanging messages natively with that address. For example, if someone using SMS was added to a Conversation, they’d receive Conversation Messages as SMS originating from the Proxy Address. To reply, they’d send an SMS back to the Proxy Address.


How does Twilio handle incoming messages?

When Twilio receives a message from an external channel, we check the to and the from addresses. If this pair matches an existing mapping to a Conversation, we’ll insert it into the Conversation as a Message from the Participant that uses that mapping. This mapping is known as a Messaging Binding.

If an incoming message doesn’t match an existing mapping, we’ll check to see if you’ve used the Address Configuration API or a Messaging Service to enable autocreation for that Proxy Address. If you did, we’ll automatically create a Conversation, add a Participant to it with that Messaging Binding, and insert the Message into the Conversation.

Handle Incoming Messages

What is a Service?

A Service is a unique instance of Twilio Conversations. If you have multiple Services, you’ll notice that Conversations, Users, and other objects in one Service can’t interact with objects from another Service - it’s an opaque partition. Generally, use cases call for one Service. If you’re an ISV or have another use case that you believe requires multiple instances, Subaccounts are usually a better option.

What is a Service

What's next?

Now that you know the basics of Conversations, you might want to check out these resources:

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.

Loading Code Sample...

        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!