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.markAsTyping(): Promise<void>

Marks the current user as typing in this conversation for 10 seconds.

This means that other users will see a typing indicator in the UI, from the current user.

The user will automatically stop typing after 10 seconds. You cannot manually mark a user as "not typing". Users are also considered "not typing" when they send a message, even if that message was sent from a different tab or using the REST API.

To keep the typing indicator visible for longer, call this function again to reset the 10s timer.

1let lastMarkedAsTyping = 0;
2
3inputElement.addEventListener("change", event => {
4  const text = event.target.value;
5
6  // Deleting your draft never counts as typing
7  if (text.length === 0) {
8    return;
9  }
10
11  const now = Date.now();
12
13  // Don't mark as typing more than once every 5s
14  if (now - lastMarkedAsTyping > 5000) {
15    lastMarkedAsTyping = now;
16    convRef.markAsTyping();
17  }
18});
19
20// When you send a message, you are no longer considered typing
21// So we need to send markAsTyping as soon as you type something
22function onSendMessage() {
23  lastMarkedAsTyping = 0;
24}

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();

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

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)

conversationRef.subscribeTyping(onSnapshot): TypingSubscription

Subscribes to the typing status of the conversation.

Whenever Subscription.state.type is "active" and the typing status changes, onSnapshot will fire and Subscription.state.latestSnapshot will be updated. This includes changes to nested data, such as when a user who is typing changes their name.

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

Note that if there are "many" people typing and another person starts to type, onSnapshot will not be called. This is because your existing ManyTypingSnapshot is still valid and did not change when the new person started to type.

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.

typingSubscription.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.