List chat conversations
Lists brand-creator conversations with latest-message previews and unread counts. Rows with kind "group" are group chats (title = the internal name, publicTitle = the name creators see, memberCount; creator fields are null). An API key always reads its organization's inbox (scope "org").
Three modes:
- Default (no pageToken, limit or updatedSince): the 200 most recently active conversations, pinned ones first. There is no continuation (nextPageToken is null); pass limit to read a larger inbox.
- Paged (limit and/or pageToken): every conversation, newest first by creation, an order that stays put while conversations get new messages. Pass each nextPageToken back until it is null.
- Changed since (updatedSince): the conversations whose updatedAt is later (a message sent, edited or deleted, a group renamed or its members changed), oldest change first. Pass nextPageToken back with the same updatedSince. A conversation that changes during the scan comes back on a later page, and the server looks back 2 minutes before updatedSince because changes commit slightly out of order, so a thread can appear more than once: dedupe on chatId. Pass the newest updatedAt you received as the next updatedSince. Unread counts and the caller's own pin, archive and mute state are not changes.
search, filter and applicationStatus apply in every mode. The default mode leaves out the conversations the caller archived; the paged and changed-since modes include them (archived is true on the row), so an archive never hides a conversation from a sync. archived true lists only the archived conversations, combined with filter (filter "archived" alone is the same), and false only the others, in every mode. archivedCount counts the archived conversations matching search, filter and applicationStatus; relationshipStats and groupStats always describe the whole inbox. A page token only continues the mode that issued it: any other token is refused with 400.
Request
- Base URL: https://viral.app/api/v1
- URL: https://viral.app/api/v1/chat/threads
- Auth: API key in header x-api-key
Query parameters
true lists only the conversations you archived, false only the others, on top of filter (archived unread ones, archived groups, …). Left out, the default mode lists the others and the paged modes both. filter "archived" is the same as archived true.
Only the direct conversations whose creator has an application to your organization in this status (any of their applications), on top of filter: with filter "application", the applicants at that stage.
The previous page's nextPageToken. Pass it with the same updatedSince, search and filter.
Page size (default 200). Passing it pages through every conversation, newest first by creation.
Only conversations changed since this instant, oldest change first. Pass the newest updatedAt you received; the server looks back 2 minutes before it, so dedupe on chatId.
Response
OK
Changes
No recorded changes to this operation across all 1 revision of this API.