Update a conversation (archive, spam, business_unread, follow-up, soft delete)

put

https://api.vcita.biz/v2/conversations/{id}

Overview

Updates a single conversation. This endpoint is used for several distinct operations against the same conversation resource:

Archive / unarchive
Mark as spam / not spam
Mark as read / unread for the business side (business_unread)
Soft delete (deleted)
Create, update, complete, or remove a follow-up reminder for the requesting staff member

All fields are optional in the request body — send only the fields you want to change. Only fields that are present in the request body are evaluated.

Available for Staff tokens.

Follow-up flow

Follow-ups in vcita are scoped to a single staff member on a single conversation, and are stored on the underlying Collaborator record (per staff/conversation), not on the conversation itself. Sending follow-up fields on this endpoint always operates on the follow-up record of the staff identified by the bearer token.

The endpoint branches based on the combination of follow_up and archived in the request body:

Sent fields	Behavior
`follow_up: true`, no `archived` (or `archived: false`)	Create or update a follow-up for the requesting staff. Creates a Collaborator if one does not already exist. Sets `follow_up=true`, `follow_up_message`, and optionally `follow_up_date`. If the conversation was archived, it is automatically unarchived. If a `follow_up_message` is provided without a `follow_up_date`, an internal text message is added to the conversation.
`follow_up: true`, `archived: true`	Remove the follow-up (used to dismiss/snooze). If `complete_follow_up: true` is also sent, the follow-up is marked as completed.
`follow_up: false`	Remove the follow-up. If `complete_follow_up: true` is also sent, the follow-up is marked as completed.

Note: The follow-up branch only fires when the request body actually contains a follow_up key, and the add/remove logic only fires when the new follow_up value differs from the current one (with the exception of the follow_up: true, archived: true case, which always removes).

Permitted update fields

Fields outside of the follow-up flow are permitted via Conversation::READ_WRITE_PARAMS: archived, business_unread, spam, deleted, campaign, source_type, mobile. The follow-up fields (follow_up, follow_up_date, follow_up_message, complete_follow_up) are read separately from the request body and are not part of the permitted attributes list.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

string

required

Unique identifier (uid) of the conversation to update (e.g., "89m2pnabgozdvd9f"). If the uid points to a conversation that has been merged into another, the request is automatically routed to the merged target conversation.

Query Params

full_client

boolean

When set to a truthy value, the response client object is rendered in its full representation (instead of the default summary), and the conversation is rendered in its deep representation (adds source/source_data/source_type/sourceable fields and sets depth to "deep").

Body Params

Partial update payload. All fields are optional; send only the fields you want to change.

follow_up

boolean

Whether a follow-up should be active on this conversation for the requesting staff. Setting this field is what triggers the follow-up branch. Set to true to create/update a follow-up, or false to remove it. When combined with archived: true, follow_up: true removes the follow-up (used to dismiss it from the inbox).

follow_up_date

string

When the follow-up reminder should fire. Accepts any string parseable by Ruby's Time parser, including the JavaScript-style format the UI sends (e.g., "Wed May 06 2026 13:31:21 GMT+0300 (Israel Daylight Time)") and ISO 8601 (e.g., "2026-05-06T10:31:21Z"). Must be in the future. Only consumed when creating/updating a follow-up.

follow_up_message

string

Free-text note attached to the follow-up (e.g., "just a test", "call back about pricing"). Defaults to an empty string. When a non-empty follow_up_message is sent without a follow_up_date, an internal text message is automatically added to the conversation as a record of the follow-up note.

complete_follow_up

boolean

Defaults to false

Only meaningful when removing a follow-up (i.e., follow_up: false, or follow_up: true with archived: true). When true, the follow-up is marked as completed rather than simply dismissed.

archived

boolean

Archive (true) or unarchive (false) the conversation. When sent together with follow_up: true, it instead removes the follow-up (see the follow-up branching table above).

business_unread

boolean

Mark the conversation as unread (true) or read (false) for the business side. When this field is present, the read state is propagated to the relevant staff collaboration record.

spam

boolean

Mark the conversation as spam (true) or not spam (false). When set, the spam state is also applied to the associated client.

deleted

boolean

Soft-delete (true) the conversation (sets deleted_at to the current time). Hard deletion is performed via the DELETE endpoint, not via this field.

campaign

string

Free-form campaign tag stored on the conversation.

source_type

string

Source classifier of the conversation (e.g., "contact_form", "profile_page", "email_campaign").

mobile

boolean

Internal flag indicating whether the conversation originated from a mobile device.

Responses

401Unauthorized. The bearer token is missing, invalid, expired, or not a staff token.

403Forbidden. The authenticated staff is not allowed to update this conversation (Pundit policy denied access).

404Not Found. No conversation with the given uid exists, or the conversation belongs to a different business than the one resolved from the bearer token.

422Unprocessable Entity. The follow-up validation failed. The most common cause is follow_up_date being in the past; the staff resolved from the bearer token could not be found is also possible.