Rate this page:

Working with Conversations

A Conversation is a distinct omni-channel messaging thread (i.e. a place where users from multiple channels can exchange messages), in which Participants from any channel Conversations supports (e.g. SDK, SMS, WhatsApp) can communicate with each other.

You can create and manage new Conversations using either the Conversations REST API or the client-side Conversations SDK (what we’re covering here). Let’s start to dive in!

Create your first Conversation

You’ll create a new Conversation using the Conversation creation (JS, iOS) or Conversation Builder methods on your new initialized Client object. Optionally, you can pass in the following parameters:attributes, friendlyName, and uniqueName.


        Join or Leave a Conversation

        After creating the Conversation, you’ll need to join it to participate. Joining will create a Participant object in the Conversation that is associated with your User. This also subscribes you to events from the Conversation.

        If you’d like to stop receiving events from this Conversation and remove your Participant, you can call the appropriate method to leave the Conversation.


              Add a Participant

              There are two types of Participants:

              • Chat (SDK-based) Participants, or
              • Non-chat (e.g. SMS, WhatsApp) Participant

              SDK-based (chat) Participant objects have a many-to-1 relationship with User objects. In other words, a User represents a human using the SDK and has a unique Participant object in each Conversation they are participating in. Non-chat Participants (i.e. SMS, WhatsApp, etc.) are not linked by a User object even when they are the same human participating in multiple Conversations.

              Users are uniquely identified by the identity property in the Access Token they initialized their Client with. You can create a Chat Participant belonging to that User in the Conversation by specifying their User’s identity in the corresponding creation method.

              To add a non-chat Participant to the Conversation, you’ll have to pass the proxyAddress and address parameters to the specific creation method on the Conversation object. Make sure to replace the proxyAddress parameter with a Twilio address (i.e. phone number, WhatsApp sender) and the address parameter with the real-world phone number or address that the Participant is using.


                    List all Participants

                    You can get the list of all Participants within the Conversation by invoking the corresponding method on the Conversation object.


                          List new Messages

                          To list the latest messages of a Conversation, call the appropriate method on the Conversation object and optionally specify the index of a specific Message to start from.

                          There are a few options, you can review the auto-generated documentation to familiarize yourself with the parameters you can use to modify this behavior.


                                List all Conversations

                                Because all Conversations are private, listing Conversations will only return Conversations that you are participating in. Call the appropriate method to retrieve them.


                                      What's Next?

                                      Well done! You’ve just learned how to create your first Conversation, add a Participant and list your conversations. To learn more, check out these helpful links:

                                      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!