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

Creating a conversation

LYRConversation objects are created by calling newConversationWithParticipants:options:error: on LYRClient. The fields are as follows:

  • participants (Required, NSSet): A set of user IDs (the same ones you included in your identity token)
  • options (Optional, LYRConversationOptions): An instance of LYRConversationOptions containing options to apply to the conversation.
  • error (Optional, pointer to NSError): An optional pointer to an error object whose value will be set if an error occurs


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.

// Creates and returns a distinct conversation object with the given user
NSError *error = nil;
NSSet *participants = [NSSet setWithObjects:@"USER_ID", nil];
LYRConversation *conversation = [layerClient newConversationWithParticipants:participants options:nil error:&error];


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:

NSError *error = nil;
NSSet *participants = [NSSet setWithObject:@"USER_ID"];
LYRConversationOptions *conversationOptions = [LYRConversationOptions new];
conversationOptions.distinctByParticipants = NO;

LYRConversation *topicA = [layerClient newConversationWithParticipants:participants options:conversationOptions error:&error];
LYRConversation *topicB = [layerClient newConversationWithParticipants:participants options:conversationOptions error:&error];

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
// New participants will gain access to all previous messages in a conversation.
NSError *error = nil;
BOOL success = [conversation addParticipants:@[ @"USER_ID" ] error:&error];

// Removes a participant from an existing conversation
// Removed participants will only lose access to future content. They will retain access
// to the conversation and all preceding content.
NSError *error = nil;
BOOL success = [conversation removeParticipants:@[ @"USER_ID" ] error:&error];

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 Messages