Conversations

A conversation is a chat channel where messages can be sent. Users can participate in many conversations at once.

class ConversationRef

Method Overview

createIfNotExists	Creates this conversation if it does not already exist.
deleteFields	Deletes properties of this conversation.
get	Fetches a snapshot of the conversation.
markAsRead	Marks the conversation as read.
markAsTyping	Marks the current user as typing in this conversation for 10 seconds.
markAsUnread	Marks the conversation as unread.
message	Get a reference to a message in this conversation
participant	Get a reference to a participant in this conversation
send	Sends a message in the conversation
sendMessage	Sends a message in the conversation
set	Sets properties of this conversation and your participation in it.
subscribe	Subscribes to the conversation.
subscribeMessages	Subscribes to the messages in the conversation.
subscribeParticipants	Subscribes to the participants in the conversation.
subscribeTyping	Subscribes to the typing status of the conversation.

Properties

id

: String

The ID of the referenced conversation.

Immutable: if you want to reference a different conversation, get a new ConversationRef instead.

createIfNotExists

Future<void> conversationRef.createIfNotExists({subject, photoUrl, welcomeMessages, custom, access, notify})

Creates this conversation if it does not already exist.

Properties that are null will be set to the default

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. The promise rejects if you are not already a participant and client-side conversation syncing is disabled.

Parameters

subject (named)

: String?

The conversation subject to display in the chat header. Default = no subject, list participant names instead

photoUrl (named)

: String?

The URL for the conversation photo to display in the chat header. Default = no photo, show a placeholder image.

welcomeMessages (named)

: List<String>?

System messages which are sent at the beginning of a conversation. Default = no messages.

custom (named)

: Map<String, String>?

Custom metadata you have set on the conversation. Default = no custom metadata

access (named)

: ConversationAccess?

Your access to the conversation. Default = READ_WRITE access.

notify (named)

: NotificationSettings?

Your notification settings. Default = TRUE

Returns

Future<void>

deleteFields

Future<void> conversationRef.deleteFields(fields)

Deletes properties of this conversation.

To delete a field in the custom property, pass it as custom.FIELD_TO_DELETE.

Parameters

fields

: List<String>

The names of the properties to delete

Returns

Future<void>

get

Future<ConversationSnapshot?> conversationRef.get()

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.

Returns

Future<ConversationSnapshot?>

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)

markAsRead

Future<void> conversationRef.markAsRead()

Marks the conversation as read.

The promise rejects if you are not a participant in the conversation.

Returns

Future<void>

markAsTyping

Future<void> conversationRef.markAsTyping()

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.

Returns

Future<void>

markAsUnread

Future<void> conversationRef.markAsUnread()

Marks the conversation as unread.

The promise rejects if you are not a participant in the conversation.

Returns

Future<void>

message

Future<MessageRef> conversationRef.message(messageId)

Get a reference to a message in this conversation

Parameters

messageId

: String

Returns

Future<MessageRef>

A reference to the message with the given ID

participant

Future<ParticipantRef> conversationRef.participant(user)

Get a reference to a participant in this conversation

Parameters

user

: String

the user's ID

Returns

Future<ParticipantRef>

A reference to the given participant

send

Future<MessageRef> conversationRef.send(text, {custom, referencedMessage})

Sends a message in the conversation

Parameters

text

: String

The text to send in the message.

custom (named)

: Map<String, String>?

Custom metadata you have set on the user. Default = no custom metadata

referencedMessage (named)

: String?

The message that you are replying to. Default = not a reply

Returns

Future<MessageRef>

A reference to the newly created message. The promise rejects if you are not a participant with write access in this conversation.

sendMessage

Future<MessageRef> conversationRef.sendMessage(content, {custom, referencedMessage})

Sends a message in the conversation

Properties that are null will be set to the default.

This is the more advanced method for editing a message, giving full control over the message content. You can decide exactly how a text message should be formatted, edit an attachment, or even turn a text message into a location.

Parameters

content

: List<ContentBlock>

The most important part of the message, either some text, a file attachment, or a location.

custom (named)

: Map<String, String>?

Custom metadata you have set on the user. Default = no custom metadata

referencedMessage (named)

: String?

The message that you are replying to. Default = not a reply

Returns

Future<MessageRef>

A reference to the newly created message. The promise rejects if you are not a participant with write access in this conversation.

set

Future<void> conversationRef.set({subject, photoUrl, welcomeMessages, custom, access, notify})

Sets properties of this conversation and your participation in it.

Properties that are null will not be changed. To clear / reset a property to the default, call ConversationRef.deleteFields instead.

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. When client-side conversation syncing is disabled, you may only set your notify property, when you are already a participant. Everything else requires client-side conversation syncing to be enabled, and will cause the function to throw.

Parameters

subject (named)

: String?

The conversation subject to display in the chat header. Default = no subject, list participant names instead.

photoUrl (named)

: String?

The URL for the conversation photo to display in the chat header. Default = no photo, show a placeholder image.

welcomeMessages (named)

: List<String>?

System messages which are sent at the beginning of a conversation. Default = no messages.

custom (named)

: Map<String, String?>?

Custom metadata you have set on the conversation. This value acts as a patch. Remove specific properties by calling ConversationRef.deleteFields Default = no custom metadata

access (named)

: ConversationAccess?

Your access to the conversation. Default = READ_WRITE access.

notify (named)

: NotificationSettings?

Your notification settings. Default = TRUE

Returns

Future<void>

ConversationSubscription conversationRef.subscribe(onSnapshot)

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 if 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)

Parameters

onSnapshot

: void Function(ConversationSnapshot? snapshot)

Returns

ConversationSubscription

subscribeMessages

MessageSubscription conversationRef.subscribeMessages(onSnapshot)

Subscribes to the messages in the conversation.

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

Whenever a message is edited, a new message is received, or you load more messages, onSnapshot will fire and Subscription.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)

Parameters

onSnapshot

: void Function(List<MessageSnapshot>? snapshot, bool loadedAll)

function called when the list of messages is updated

Returns

MessageSubscription

A subscription to messages.

subscribeParticipants

ParticipantSubscription conversationRef.subscribeParticipants(onSnapshot)

Subscribes to the participants in the conversation.

While the subscription is active, onSnapshot will be called whenever the participant snapshots change. This includes when someone joins or leaves, when their participant attributes are edited, and when you load more participants. It also includes when nested data changes, such as when snapshot[0].user.name changes. loadedAll is true when snapshot contains all the participants in the conversation, and false if you could load more.

The snapshot list is ordered chronologically with the participants who joined most recently at the start. When someone joins the conversation, they will be added to the start of the list.

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

Initially, you will be subscribed to the 10 participants who joined most recently, and any new participants. Call loadMore to load additional older participants. This will trigger onSnapshot.

Remember to call .unsubscribe on the subscription once you are done with it.

Parameters

onSnapshot

: void Function(List<ParticipantSnapshot>? snapshot, bool loadedAll)

Returns

ParticipantSubscription

subscribeTyping

TypingSubscription conversationRef.subscribeTyping(onSnapshot)

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 is still valid and did not change when the new person started to type.

Parameters

onSnapshot

: void Function(TypingSnapshot? snapshot)

Returns

TypingSubscription

class ConversationSnapshot

A snapshot of a conversation and the current user's participation in it.

A snapshot is a frozen view of the conversation's attributes at the time it was fetched. If the conversation is updated after the snapshot is taken, the snapshot will not automatically update.

Method Overview

constructor
toJson

Properties

access

: ConversationAccess

The current user's permission level in this conversation.

createdAt

: int

The date that the conversation was created, as a unix timestamp in milliseconds.

custom

: Map<String, String>

Custom metadata you have set on the conversation

everyoneReadUntil

: int

Everyone in the conversation has read any messages sent on or before this date.

This is the minimum of all the participants' readUntil values. Any messages sent on or before this timestamp should show a "read" indicator in the UI.

This value will rarely change in very large conversations. If just one person stops checking their messages, everyoneReadUntil will never update.

id

: String

The ID of the conversation

isUnread

: bool

Whether the conversation should be considered unread.

This can be true even when unreadMessageCount is zero, if the user has manually marked the conversation as unread.

joinedAt

: int

The date that the current user joined the conversation, as a unix timestamp in milliseconds.

lastMessage (optional)

: MessageSnapshot?

The last message sent in this conversation, or null if not messages have been sent.

notify

: NotificationSettings

The current user's notification settings for this conversation.

FALSE means no notifications, TRUE means notifications for all messages, and MENTIONS_ONLY means that the user will only be notified when they are mentioned with an @.

photoUrl (optional)

: String?

Contains the URL of a photo to represent the topic of the conversation or null if the conversation does not have a photo specified.

readUntil

: int

The most recent date that the current user read the conversation.

This value is updated whenever you read a message in a chat UI, open an email notification, or mark the conversation as read using an API like ConversationRef.markAsRead.

Any messages sent after this timestamp are unread messages.

subject (optional)

: String?

Contains the conversation subject, or null if the conversation does not have a subject specified.

unreadMessageCount

: int

The number of messages in this conversation that the current user hasn't read.

welcomeMessages

: List<String>

One or more welcome messages that will be rendered at the start of this conversation as system messages.

Welcome messages are rendered in the UI as messages, but they are not real messages. This means they do not appear when you list messages using the REST API or JS/Kotlin Data API, and you cannot reply or react to them.

constructor

ConversationSnapshot(json)

Parameters

json

: Map<String, dynamic>

toJson

Map<String, dynamic> conversationSnapshot.toJson()

Returns

Map<String, dynamic>

class ConversationSubscription

A subscription to a specific conversation.

Get a ConversationSubscription by calling ConversationRef.subscribe

Method Overview

unsubscribe

Unsubscribe from this resource and stop receiving updates.

Properties

connected

: Future<void>

Resolves when the subscription starts receiving updates from the server.

terminated

: Future<void>

Resolves when the subscription permanently stops receiving updates from the server.

This is either because you unsubscribed or because the subscription encountered an unrecoverable error.

unsubscribe

Future<void> conversationSubscription.unsubscribe()

Unsubscribe from this resource and stop receiving updates.

If the subscription is already in the or , this is a no-op.

Returns

Future<void>

class ConversationListSubscription

A subscription to your most recently active conversations.

Get a ConversationListSubscription by calling TalkSession.subscribeConversations.

The subscription is 'windowed'. Initially, this window contains the 20 most recent conversations. Conversations are ordered by last activity. The last activity of a conversation is either joinedAt or lastMessage.createdAt, whichever is higher.

The window will automatically expand to include any conversations you join, and any old conversations that receive new messages after subscribing.

You can expand this window by calling ConversationListSubscription.loadMore, which extends the window further into the past.

Remember to .unsubscribe the subscription once you are done with it.

Method Overview

loadMore	Expand the window to include older conversations
unsubscribe	Unsubscribe from this resource and stop receiving updates.

Properties

connected

: Future<void>

Resolves when the subscription starts receiving updates from the server.

Wait for this promise if you want to perform some action as soon as the subscription is active.

The promise rejects if the subscription is terminated before it connects.

terminated

: Future<void>

Resolves when the subscription permanently stops receiving updates from the server.

This is either because you unsubscribed or because the subscription encountered an unrecoverable error.

loadMore

Future<void> conversationListSubscription.loadMore([count])

Expand the window to include older conversations

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

Avoid calling .loadMore in a loop until you have loaded all conversations. This is usually unnecessary: any time a conversation receives a message, it appears at the start of the list of conversations. If you do need to call loadMore in a loop, make sure you set a small upper bound (e.g. 100) on the number of conversations, where the loop will exit.

Parameters

count (optional)

: int?

The number of additional conversations to load. Must be between 1 and 30. Default 20.

Returns

Future<void>

unsubscribe

Future<void> conversationListSubscription.unsubscribe()

Unsubscribe from this resource and stop receiving updates.

If the subscription is already in the or , this is a no-op.

Returns

Future<void>

class TypingSnapshot

A snapshot of the typing indicators in a conversation at a given moment in time.

Currently when there are 5 or less people typing in the conversation, many will be false and users will contain the users who are currently typing in this conversation. When more than 5 people are typing, many will be true and users will be null. This limit may change in the future, which will not be considered a breaking change.

Example

Converting a TypingSnapshot to text


1String formatTyping(TypingSnapshot snapshot) {
2  if (snapshot.many) {
3    return 'Several people are typing';
4  }
5
6  final names = snapshot.users!.map((user) => user.name).toList();
7
8  if (names.isEmpty) {
9    return '';
10  }
11
12  if (names.length == 1) {
13    return '${names[0]} is typing';
14  }
15
16  if (names.length == 2) {
17    return '${names.join(' and ')} are typing';
18  }
19
20  // Prefix last name with "and "
21  names.add('and ${names.removeLast()}');
22  return '${names.join(', ')} are typing';
23}

Method Overview

constructor
toJson

Properties

many

: bool

Check this to differentiate between few people are typing (false) and many people are typing (true).

When false, you can see the list of users who are typing in the users property.

users (optional)

: List<UserSnapshot>?

The users who are currently typing in this conversation.

The list is in chronological order, starting with the users who have been typing the longest. The current user is never contained in the list, only other users. When the many property is true, this property is null.

constructor

TypingSnapshot(json)

Parameters

json

: Map<String, dynamic>

toJson

Map<String, dynamic> typingSnapshot.toJson()

Returns

Map<String, dynamic>

class TypingSubscription

A subscription to the typing status in a specific conversation

Get a TypingSubscription by calling ConversationRef.subscribeTyping.

When there are "many" people typing, the next update you receive will be once enough people stop typing. Until then, your TypingSnapshot is still valid and does not need to changed, so onSnapshot will not be called.

Method Overview

unsubscribe

Unsubscribe from this resource and stop receiving updates.

Properties

connected

: Future<void>

Resolves when the subscription starts receiving updates from the server.

Wait for this promise if you want to perform some action as soon as the subscription is active.

The promise rejects if the subscription is terminated before it connects.

terminated

: Future<void>

Resolves when the subscription permanently stops receiving updates from the server.

This is either because you unsubscribed or because the subscription encountered an unrecoverable error.

unsubscribe

Future<void> typingSubscription.unsubscribe()

Unsubscribe from this resource and stop receiving updates.

If the subscription is already in the or , this is a no-op.

Returns

Future<void>

enum ConversationAccess

Values:

Read
ReadWrite

enum NotificationSettings

Values:

yes
no
mentionsOnly