Conversations

Conversation management

EndpointsCopy Anchor Link

• POST Archive a conversation — Archives one conversation by setting its archivedAt timestamp. Archiving does not change status, so the conversation keeps its open or closed state.
• POST Assign operator to conversation — Assigns one conversation to a specific operator in the current organization. The conversation and operator must both belong to that organization.
• POST Bulk assign conversations to an operator — Assigns up to 100 conversations to one operator. Admin access is required, and both the conversations and the target operator must belong to the current…
• POST Bulk close conversations — Closes up to 100 conversations in one request. Admin access is required, and every conversation ID must belong to the current organization.
• POST Bulk delete conversations — Soft-deletes up to 100 conversations and marks their messages as deleted.
• DELETE Clear a follow-up reminder on a conversation — Removes the stored follow-up reminder fields from the conversation metadata and keeps all other metadata keys unchanged.
• POST Close a conversation — Closes one conversation in the current organization. The request body is optional; a bare POST also closes the conversation.
• POST Create a conversation — Starts a new conversation for an existing visitor in the current organization.
• DELETE Delete a conversation — Soft-deletes one conversation in the current organization. Admin access is required.
• GET Export conversation transcript as CSV or PDF — Exports one conversation transcript from the authenticated organization. format defaults to csv, which returns the file immediately.
• GET Get conversation by ID — Returns one conversation from the current organization, including the joined visitor record and computed dashboard fields such as unreadCount, tags,…
• GET Get the assignment history timeline for a conversation — Returns assignment-related audit events for one conversation in chronological order.
• GET Get unified activity timeline for a conversation — Returns a merged chronological feed of messages, internal notes, tag changes, transfers, CSAT responses, and audit log entries for a conversation.
• POST Link this conversation to another (soft cross-reference) — Adds another conversation ID to metadata.linkedConversationIds for the source conversation.
• GET List conversations — Returns paginated conversations for the current organization. Use the query to filter by status, priority, assignment, channel, visitor, or tags.
• GET List the canonical conversation timeline — Returns messages, visitor page views, internal notes, tag changes, transfers, CSAT responses, and audit entries in one deterministic newest-first…
• POST Merge two conversations — Merges two conversations from the same visitor into a single thread.
• PATCH Override a conversation visitor language — Sets a manual visitor-language override for one conversation. Send null to return to the widget/browser language fallback.
• GET Poll the status of an async conversation PDF export — Checks the state of a PDF export job that was created by GET /api/conversations/{id}/export?format=pdf.
• DELETE Remove a conversation link — Removes a related conversation ID from metadata.linkedConversationIds for the source conversation.
• POST Reopen a closed conversation — Reopens a closed conversation in the current organization. The request body is optional; a bare POST also reopens the conversation.
• POST Schedule a follow-up reminder on a conversation — Stores a follow-up reminder in the conversation metadata so operators can revisit the conversation later. The remindAt value must be a future ISO timestamp.
• GET Search conversations by message content — Searches conversation messages by content and falls back to a case-insensitive match when no ranked results are found.
• POST Send conversation transcript via email — Emails the transcript of one conversation to the requested address. The export skips internal notes and includes up to 5000 messages.
• PATCH Set the visitor-facing conversation locale — Sets a stable locale for future visitor-facing messages in one conversation. The locale must be enabled for the organization.
• POST Snooze a conversation — Snoozes one conversation until a future ISO timestamp. The until value must be in the future, and reason is optional.
• DELETE Unarchive a conversation — Clears the archivedAt timestamp and returns the conversation to the default list tabs. The request has no body.
• POST Unassign the operator from a conversation — Clears the operator assignment for one conversation in the current organization. The conversation must belong to that organization.
• DELETE Unsnooze a conversation — Clears the snoozedUntil timestamp and makes the conversation active again. The request has no body.
• PATCH Update a conversation — Updates mutable conversation fields such as status, priority, assigned operator, and metadata. Operator access is required.