Overview

Retrieve and manage conversations that track the latest messages and unread counts for each user.

A Conversation represents an ongoing message exchange between a user and another user (1-on-1) or a group. Each conversation tracks the last message, unread count, and metadata — making it easy to build a “Recent Chats” list.

Key behaviors

• Conversations are automatically created when the first message is exchanged.
• For groups with more than 300 members, conversations and unread message counts are not updated.
• Conversations can have up to 25 tags, each up to 100 characters (UTF8mb4).
• The lastMessage property is not visible if the message has been deleted or if a new group has no messages yet.

How conversations connect to other resources

• Users — A 1-on-1 conversation is between two Users. The conversationWith field contains the other user’s details.
• Groups — A group conversation is tied to a Group. The conversationWith field contains the group’s details.
• Messages — The lastMessage field reflects the most recent Message in the conversation.

Available operations

Operation	Method	Endpoint	Description
List Conversations	GET	/conversations	Retrieve all conversations for a user
Get Conversation	GET	/conversations/{conversationId}	Retrieve a specific conversation (deprecated)
Delete Conversation	DELETE	/conversations/{conversationId}	Delete a conversation for a user (deprecated)
Get User Conversation	GET	/users/{uid}/conversation	Retrieve a 1-on-1 conversation with a specific user
Get Group Conversation	GET	/groups/{guid}/conversation	Retrieve a group conversation
Update User Conversation	PUT	/users/{uid}/conversation	Update tags on a 1-on-1 conversation
Update Group Conversation	PUT	/groups/{guid}/conversation	Update tags on a group conversation
Reset User Conversation	DELETE	/users/{uid}/conversation	Reset unread count for a 1-on-1 conversation
Reset Group Conversation	DELETE	/groups/{guid}/conversation	Reset unread count for a group conversation
Mark User Conversation as Read	POST	/users/{uid}/conversation/read	Mark all messages as read in a 1-on-1 conversation
Mark Group Conversation as Read	POST	/groups/{guid}/conversation/read	Mark all messages as read in a group conversation
Mark User Conversation as Delivered	POST	/users/{uid}/conversation/delivered	Mark all messages as delivered in a 1-on-1 conversation
Mark Group Conversation as Delivered	POST	/groups/{guid}/conversation/delivered	Mark all messages as delivered in a group conversation
Mark Conversation as Unread	DELETE	/users/{uid}/conversation/read	Mark a user conversation as unread
Mark Group Conversation as Unread	DELETE	/groups/{guid}/conversation/read	Mark a group conversation as unread

Conversation properties

Property	Type	Description
conversationId	string	Unique conversation identifier. Format: user_{uid} for 1-on-1 or group_{guid} for group conversations.
conversationType	string	Type of conversation: user or group.
unreadMessageCount	integer	Number of unread messages in this conversation.
lastMessage	object	Details of the most recent message in the conversation. Not present if the message was deleted or if a new group has no messages.
conversationWith	object	Details of the other user (for 1-on-1) or the group (for group conversations).
createdAt	integer	UNIX timestamp of when the conversation was created.
updatedAt	integer	UNIX timestamp of when the conversation was last updated.

Error handling

Error Code	Description
ERR_UID_NOT_FOUND	The specified user does not exist
ERR_CONVERSATION_NOT_FOUND	The specified conversation does not exist

For the complete list of error codes, see Error Guide.

For all system limits (unread counts, tag counts, group thresholds, etc.), see Properties and Constraints.