Conversations

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 client.createConversation(), passing in a hash with array of User IDs to be included in the conversation:

var conversation = client.createConversation({
  participants: ['layer:///identities/UserA', 'layer:///identities/UserB'],
  distinct: false
});

Note

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 until the first message is sent. You can force the empty conversation to be synced by calling conversation.send() on your Conversation instance.

Note

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.

It is possible to create multiple conversations with the same set of users, if they are not distinct. However, it may also be convenient at some times to get back existing Conversations so that users may continue their Conversation.

var topic1 = client.createConversation({
  participants: ['UserA', 'UserB'],
  distinct: true
});

var topic2 = client.createConversation({
  participants: ['UserA', 'UserB'],
  distinct: true
});

var topic3 = client.createConversation({
  participants: ['UserA', 'UserB'],
  distinct: false
});

In the above example

  • topic1 and topic2 return the same Distinct Conversation
  • topic1 and topic3 are both newly created Conversations

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 to an existing conversation
conversation.addParticipants(['UserC']);

// Removes a participant from an existing conversation
conversation.removeParticipants(['UserB']);

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