Once authenticated, users can send and receive messages, which are tied to a specific Conversation object.

Creating a conversation

Conversation objects are created by calling layerClient.newConversation(). This method takes one or more Identity objects. A Conversation can be created with user IDs by calling layerClient.newConversationWithUserIds(). By default, new conversations are distinct (see below).

Conversation conversation;
try {
   // Try creating a new distinct conversation with the given user
   Identity participant = ...;
   conversation = layerClient.newConversation(participant);
} catch (LayerConversationException e) {
   // If a distinct conversation with the given user already exists, use that one instead
   conversation = e.getConversation();


Conversations are not synced with the server until the first message is sent. This means that other participants will not see a newly created conversation, and you cannot query for a newly created conversation, until the first message is sent. If you want to create an empty conversation, you can do so via the Server API. The new conversation will automatically get synced to each participant’s device.


You don’t have to include the current user in the set of participants. The current user is automatically added to all conversations they create.

Distinct Conversations

If multiple users independently create Distinct Conversations with the same set of users, the server will automatically merge the conversations. This means that some properties of the conversation may change after it is created and synced with the server. Our SDKs will handle these changes for you.

Once a Distinct Conversation has been created between User A and User B, any further attempts by either of these users to create a new Distinct Conversation with these participants will get resolved to the existing Conversation.

Conversations default to being Distinct.

We’re still working on this section for android; see your platform specific file in conversations/android-0.23.19

Adding or removing participants

Participants in a conversation can be added or removed at any time. Layer does not keep track of a conversation admin/owner, so any participant in the Conversation can add or remove participants from the conversation. However, it is possible to prevent users from modifying participants within your application’s logic.

// Adds a participant by Identity object to a given conversation

// Adds a participant by user ID (example ID 948374848) to a given conversation

// Gets participants for a given conversation as Identity objects
Set<Identity> participants = conversation.getParticipants();

// Removes a participant from a given conversation

Adding or removing participants from a distinct conversation (see below) makes it non-distinct. For example, if you have the following conversations:

  • Conversation A is distinct and has Users 1 and 2
  • Conversation B is distinct and has Users 1, 2, and 3

Adding User 3 to Conversation A will result in the following:

  • Conversation A is non-distinct and has Users 1, 2, and 3
  • Conversation B is distinct and has Users 1, 2, and 3
Identities Channels