Skip to main content
Conversations

Update a conversation

Updates a conversation's properties. Supports partial updates - only provided fields will be updated.

PATCH
/v2/conversations/{id}

Path Parameters

  • id - The conversation ID (short ID)

Request Body

All fields are optional. Only provided fields will be updated.

FieldTypeDescription
actingAdminIdstringAdmin ID performing the action (for attribution). If not provided, uses bot service user. Must be a member of the organization.
statestringConversation state: "open", "closed", or "snoozed"
snoozedUntilstringISO datetime when to unsnooze (required when state is "snoozed")
adminAssigneeIdstring/nullAdmin ID to assign, or null to unassign
teamAssigneeIdstring/nullTeam ID to assign, or null to unassign
titlestringConversation title
customAttributesobjectCustom attributes to set on the conversation, keyed by conversation custom attribute ID
markAsReadobjectMark conversation as read for specific users

markAsRead Object

FieldTypeDescription
allAdminsbooleanIf true, marks all admins with existing readReceipts as read
adminIdsstring[]Array of specific admin IDs to mark as read
allContactsbooleanIf true, marks all contacts with existing readReceipts as read
contactIdsstring[]Array of specific contact IDs to mark as read

Note: Only users with existing read receipts will be updated. Use allAdmins/allContacts OR adminIds/contactIds - the "all" flags take precedence.

Response

Returns the updated conversation object.

Example: Close a Conversation (with attribution)

{
  "actingAdminId": "507f1f77bcf86cd799439011",
  "state": "closed"
}

Example: Close a Conversation (bot user)

{
  "state": "closed"
}

Example: Snooze a Conversation

{
  "state": "snoozed",
  "snoozedUntil": "2025-01-20T10:00:00.000Z"
}

Example: Assign to an Admin

{
  "adminAssigneeId": "507f1f77bcf86cd799439011"
}

Example: Update Title and Custom Attributes

{
  "title": "Billing Issue - Priority",
  "customAttributes": {
    "507f1f77bcf86cd799439011": 10,
    "507f1f77bcf86cd799439012": true
  }
}

Example: Mark as Read (All Admins)

{
  "markAsRead": {
    "allAdmins": true
  }
}

Example: Mark as Read (All Contacts)

{
  "markAsRead": {
    "allContacts": true
  }
}

Example: Mark as Read (Specific IDs)

{
  "markAsRead": {
    "adminIds": ["507f1f77bcf86cd799439011"],
    "contactIds": ["676f0f6765bdaa7d7d760f88"]
  }
}

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

idstringrequired

Conversation ID (short ID)

Required string length: 1 - 16
Pattern: ^[a-zA-Z0-9]+$
Example: 12345

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-08-19.orbit

Body

application/json
actingAdminIdstring

The admin ID performing this action. Changes will be attributed to this admin. If not provided, changes are attributed to the system bot user. The admin must be a member of the organization.

Example: 507f1f77bcf86cd799439011
adminAssigneeIdstring | null

The admin ID to assign the conversation to, or null to unassign.

Example: 507f1f77bcf86cd799439011
customAttributesobject

Custom attributes to set on the conversation, keyed by conversation custom attribute ID. Use the custom attribute definitions for your organization to map IDs to display names.

markAsReadobject

Mark the conversation as read for specific admins and/or contacts.

skipNotificationsbooleandefault:false

Skip admin notifications (push, activity email and in-app notification) for an assignment change in this request (default: false). Useful for bulk imports.

Example: false
snoozedUntilstring | null

ISO datetime when the conversation should be unsnoozed. Required when state is "snoozed". Must be a future date.

Example: 2025-01-20T10:00:00.000Z
stateenum<string>

The state of the conversation. Use "snoozed" with snoozedUntil to snooze.

Available options: open, closed, snoozed
Example: open
teamAssigneeIdstring | null

The team ID to assign the conversation to, or null to unassign.

Example: 507f1f77bcf86cd799439012
titlestring

The title of the conversation.

Maximum string length: 255
Example: Question about pricing

Response

application/json

Success

adminAssigneeIdstring | nullrequired

ID of the assigned admin

Example: 507f1f77bcf86cd799439011
awaitingCustomerReplyboolean

Whether we are awaiting a customer reply

Example: true
botConversationStateenum<string>

State of AI agent handling for this conversation

Available options: active, handed_off_to_human, resolved
Example: active
botConversationStateLastUpdatedAtstring | nullrequired

ISO timestamp when bot state last changed

Example: 2025-01-15T10:30:00.000Z
brandIdstring | nullrequired

ID of the brand associated with this conversation

Example: 507f1f77bcf86cd799439011
conversationPartsobject[]

Array of conversation parts (messages). Only included when fetching a single conversation by ID.

createdAtstringrequired

ISO timestamp when conversation was created

Example: 2025-01-15T10:30:00.000Z
csatDebugobject

Minimal CSAT diagnostics for the current effective request.

csatHistoryobject[]

Historical CSAT requests for this conversation, ordered newest first.

csatSummaryobject

Derived CSAT summary for this conversation when a rating request or rating exists.

customAttributeValuesobject[]

Custom conversation attribute values expanded with definition metadata. Returned only when include=customAttributeDefinitions is provided.

customAttributesobject

Custom conversation attributes keyed by custom attribute ID. Only org-defined, non-archived conversation attributes are returned; internal workflow metadata is omitted.

disableCustomerReplyboolean

Whether customer replies are disabled

Example: false
hasAdminOverriddenLanguagebooleanrequired

Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled.

Example: false
idstringrequired

Unique conversation identifier

Example: 12345
isBlockedbooleanrequired

Whether the user is blocked

Example: false
lastActivityAtstring | nullrequired

ISO timestamp of last activity

Example: 2025-01-15T12:30:00.000Z
objectenum<string>required

Object type identifier

Available options: conversation
Example: conversation
participantsobject[]required

Participants in this conversation

prioritybooleanrequired

Whether this conversation is marked as priority

Example: false
prioritySetAtstring | nullrequired

ISO timestamp when priority was set

Example: 2025-01-15T10:30:00.000Z
readReceiptsobject[]

Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access.

snoozedUntilstring | nullrequired

ISO timestamp until which conversation is snoozed

Example: 2025-01-16T09:00:00.000Z
sourceobject
stateenum<string>required

Current state of the conversation

Available options: open, closed, snoozed
Example: open
tagsobject[]required

Current tags applied anywhere in this conversation

teamAssigneeIdstring | nullrequired

ID of the assigned team

Example: 507f1f77bcf86cd799439012
titlestring

Conversation title

Example: Question about pricing
updatedAtstringrequired

ISO timestamp when conversation was last updated

Example: 2025-01-15T12:30:00.000Z
userPreferredLanguagestringrequired

User's preferred language

Example: en
waitingSincestring | nullrequired

ISO timestamp when conversation started waiting

Example: 2025-01-15T10:30:00.000Z

Still need help? Ask the team