Conversations

conversationRef.createIfNotExists(params): Promise<void>

Creates this conversation if it does not already exist. Adds you as a participant in this conversation, if you are not already a participant.

If the conversation already exists or you are already a participant, this operation is still considered successful and the promise will still resolve.

A promise that resolves when the operation completes. The promise rejects if you are not already a participant and client-side conversation syncing is disabled.

conversationRef.get(): Promise<ConversationSnapshot | null>

Fetches a snapshot of the conversation.

This contains all of the information related to the conversation and the current user's participation in the conversation.

A snapshot of the current user's view of the conversation, or null if the current user is not a participant (including if the conversation doesn't exist).

conversationRef.markAsRead(): Promise<void>

Marks the conversation as read.

A promise that resolves when the operation completes. The promise rejects if you are not a participant in the conversation.

conversationRef.markAsUnread(): Promise<void>

Marks the conversation as unread.

A promise that resolves when the operation completes. The promise rejects if you are not a participant in the conversation.

conversationRef.message(id): MessageRef

Get a reference to a message in this conversation

Use this if you need to fetch, delete, or edit a specific message in this conversation, and you know its message ID. To fetch the most recent messages in this conversation, use subscribeMessages instead.

A for the user with that ID

conversationRef.participant(user): ParticipantRef

Get a reference to a participant in this conversation

Note that Participant is not the same as User. A Participant represents a user's settings related to a specific conversation.

Calling ConversationRef.createIfNotExists or ConversationRef.set will automatically add the current user as a participant.

A for that user's participation in this conversation

1session.conversation("Cats").participant("Alice").createIfNotExists();

The user "Alice" must exist before you do this.

1session.conversation("Cats").participant("Alice").delete();

The user "Alice" will still exist after you do this. This deletes the participant, not the user.

conversationRef.send(params): Promise<MessageRef>

Sends a message in the conversation

A promise that resolves with a reference to the newly created message. The promise will reject if you do not have permission to send the message.

1conversationRef.send("*Hello*");

1conversationRef.send({
2  text: "Agreed",
3  referencedMessageId: "...",
4  custom: { priority: "HIGH" }
5});

1conversationRef.send({
2  content: [{
3    type: "text",
4    children: [{
5      type: "bold",
6      children: ["Hello"]
7    }]
8  }]
9});

1// `file` is a File object from `<input type="file">`
2const fileToken = await session.uploadImage(
3  file, { filename: file.name, width: 640, height: 480 }
4);
5
6conversationRef.send({
7  content: [{ type: "file", fileToken }]
8});

1// You can get the user's location with the browser's geolocation API
2const [latitude, longitude] = [42.43, -83.99];
3conversationRef.send({
4  content: [{ type: "location", latitude, longitude }]
5});

conversationRef.set(params): Promise<void>

Sets properties of this conversation and your participation in it.

The conversation is created if a conversation with this ID doesn't already exist. You are added as a participant if you are not already a participant in the conversation.

A promise that resolves when the operation completes. When client-side conversation syncing is disabled, you must already be a participant and you cannot set anything except the notify property. Everything else requires client-side conversation syncing to be enabled, and will cause the promise to reject.

conversationRef.subscribe(onSnapshot): ConversationSubscription

Subscribes to the conversation.

Whenever Subscription.state.type is "active" and something about the conversation changes, onSnapshot will fire and Subscription.state.latestSnapshot will be updated. This includes changes to nested data. As an extreme example, onSnapshot would be called when snapshot.lastMessage.referencedMessage.sender.name changes.

The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)

conversationRef.subscribeMessages(onSnapshot): MessageSubscription

Subscribes to the messages in the conversation.

Initially, you will be subscribed to the 30 most recent messages and any new messages. Call loadMore to load additional older messages.

Whenever Subscription.state.type is "active" and a message is sent, edited, deleted, or you load more messages, onSnapshot will fire and Subscription.state.latestSnapshot will be updated. loadedAll is true when the snapshot contains all the messages in the conversation.

The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)

conversationSubscription.unsubscribe()

Unsubscribe from this resource and stop receiving updates.

If the subscription is already in the "unsubscribed" or "error" state, this is a no-op.

messageSubscription.loadMore(count): Promise<void>

Expand the window to include older messages

Calling loadMore multiple times in parallel will still only load one page of messages.

A promise that resolves once the additional messages have loaded

messageSubscription.unsubscribe()

Unsubscribe from this resource and stop receiving updates.

If the subscription is already in the "unsubscribed" or "error" state, this is a no-op.