# Update a conversation

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

### Path Parameters

- id - The conversation ID (short ID)

### Request Body

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

| Field | Type | Description |
|-------|------|-------------|
| actingAdminId | string | Admin ID performing the action (for attribution). If not provided, uses bot service user. Must be a member of the organization. |
| state | string | Conversation state: "open", "closed", or "snoozed" |
| snoozedUntil | string | ISO datetime when to unsnooze (required when state is "snoozed") |
| adminAssigneeId | string/null | Admin ID to assign, or null to unassign |
| teamAssigneeId | string/null | Team ID to assign, or null to unassign |
| title | string | Conversation title |
| customAttributes | object | Custom attributes to set on the conversation |
| markAsRead | object | Mark conversation as read for specific users |

### markAsRead Object

| Field | Type | Description |
|-------|------|-------------|
| allAdmins | boolean | If true, marks all admins with existing readReceipts as read |
| adminIds | string[] | Array of specific admin IDs to mark as read |
| allContacts | boolean | If true, marks all contacts with existing readReceipts as read |
| contactIds | string[] | 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)

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


### Example: Close a Conversation (bot user)

json
{
  "state": "closed"
}


### Example: Snooze a Conversation

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


### Example: Assign to an Admin

json
{
  "adminAssigneeId": "507f1f77bcf86cd799439011"
}


### Example: Update Title and Custom Attributes

json
{
  "title": "Billing Issue - Priority",
  "customAttributes": {
    "priority_level": "high",
    "category": "billing"
  }
}


### Example: Mark as Read (All Admins)

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


### Example: Mark as Read (All Contacts)

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


### Example: Mark as Read (Specific IDs)

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


### Version Availability

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

Endpoint: PATCH /v2/conversations/{id}
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Path parameters:

  - `id` (string, required)
    Conversation ID (short ID)
    Example: "12345"

## Request fields (application/json):

  - `actingAdminId` (string)
    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"

  - `state` (string)
    The state of the conversation. Use "snoozed" with snoozedUntil to snooze.
    Enum: "open", "closed", "snoozed"

  - `snoozedUntil` (string,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"

  - `adminAssigneeId` (string,null)
    The admin ID to assign the conversation to, or null to unassign.
    Example: "507f1f77bcf86cd799439011"

  - `teamAssigneeId` (string,null)
    The team ID to assign the conversation to, or null to unassign.
    Example: "507f1f77bcf86cd799439012"

  - `title` (string)
    The title of the conversation.
    Example: "Question about pricing"

  - `customAttributes` (object)
    Custom attributes to set on the conversation. Uses the same validation as v1 API.
    Example: {"priority_level":"high","category":"billing"}

  - `markAsRead` (object)
    Mark the conversation as read for specific admins and/or contacts.

  - `markAsRead.allAdmins` (boolean,null)
    If true, marks all admins with existing readReceipts as read.
    Example: true

  - `markAsRead.adminIds` (array)
    Array of admin IDs to mark as read. Only admins with existing readReceipts will be updated.
    Example: ["507f1f77bcf86cd799439011"]

  - `markAsRead.allContacts` (boolean,null)
    If true, marks all contacts (customers and leads) with existing readReceipts as read.
    Example: true

  - `markAsRead.contactIds` (array)
    Array of contact IDs to mark as read. Only contacts with existing readReceipts will be updated.
    Example: ["676f0f6765bdaa7d7d760f88"]

## Response 200 fields (application/json):

  - `object` (string, required)
    Object type identifier
    Enum: "conversation"

  - `id` (string, required)
    Unique conversation identifier
    Example: "12345"

  - `title` (string)
    Conversation title
    Example: "Question about pricing"

  - `state` (string, required)
    Current state of the conversation
    Enum: "open", "closed", "snoozed"

  - `isBlocked` (boolean, required)
    Whether the user is blocked

  - `priority` (boolean, required)
    Whether this conversation is marked as priority

  - `prioritySetAt` (string,null, required)
    ISO timestamp when priority was set
    Example: "2025-01-15T10:30:00.000Z"

  - `adminAssigneeId` (string,null, required)
    ID of the assigned admin
    Example: "507f1f77bcf86cd799439011"

  - `teamAssigneeId` (string,null, required)
    ID of the assigned team
    Example: "507f1f77bcf86cd799439012"

  - `userPreferredLanguage` (string, required)
    User's preferred language
    Example: "en"

  - `source` (object)

  - `source.channel` (string, required)
    Channel through which the conversation was initiated
    Enum: "unknown", "desktop", "android", "ios", "email"

  - `source.deliveredAs` (string)
    How the conversation was initiated
    Enum: "customer_initiated", "admin_initiated"

  - `source.subject` (string)
    Subject line for email conversations
    Example: "Question about pricing"

  - `source.bodyHtml` (string, required)
    Body of the initial message as HTML with signed image URLs
    Example: "<p>Hi, I have a question about your enterprise plan...</p>"

  - `source.bodyMarkdown` (string, required)
    Body of the initial message as markdown
    Example: "Hi, I have a question about your enterprise plan..."

  - `source.author` (object)

  - `source.author.type` (string, required)
    Type of participant
    Enum: "customer", "lead", "admin", "bot", "guest", "integration"

  - `source.author.id` (string, required)
    Participant ID
    Example: "676f0f6765bdaa7d7d760f88"

  - `source.url` (string)
    URL where the conversation was initiated
    Example: "https://example.com/pricing"

  - `participants` (array, required)
    Participants in this conversation

  - `botConversationState` (string)
    State of AI agent handling for this conversation
    Enum: "active", "handed_off_to_human", "resolved"

  - `botConversationStateLastUpdatedAt` (string,null, required)
    ISO timestamp when bot state last changed
    Example: "2025-01-15T10:30:00.000Z"

  - `disableCustomerReply` (boolean)
    Whether customer replies are disabled

  - `awaitingCustomerReply` (boolean)
    Whether we are awaiting a customer reply
    Example: true

  - `lastActivityAt` (string,null, required)
    ISO timestamp of last activity
    Example: "2025-01-15T12:30:00.000Z"

  - `waitingSince` (string,null, required)
    ISO timestamp when conversation started waiting
    Example: "2025-01-15T10:30:00.000Z"

  - `snoozedUntil` (string,null, required)
    ISO timestamp until which conversation is snoozed
    Example: "2025-01-16T09:00:00.000Z"

  - `createdAt` (string, required)
    ISO timestamp when conversation was created
    Example: "2025-01-15T10:30:00.000Z"

  - `updatedAt` (string, required)
    ISO timestamp when conversation was last updated
    Example: "2025-01-15T12:30:00.000Z"

  - `readReceipts` (array)
    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.

  - `readReceipts.id` (string, required)
    The internal ID of the user
    Example: "507f1f77bcf86cd799439011"

  - `readReceipts.userType` (string, required)
    Type of user who has read the conversation
    Enum: "admin", "customer", "lead"

  - `readReceipts.lastReadPartId` (string, required)
    The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility.
    Example: "8"

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

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "invalid_request"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 400

## Response 403 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "authorization_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "forbidden"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 403

## Response 404 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "conversation_not_found", "admin_not_found"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 404