Update a conversation

PATCH /v1/inbox/conversations/{conversation_id}

Marks a conversation read or unread, or archives or restores it.

Scope: inbox:reply

Access: The key's member must be able to see the conversation in the inbox.

Send exactly one of read or archived per request; to change both, send two requests. It is the same change your team makes in the inbox, and it never takes messages out of the inbound feed. There is no delete.

Archiving closes the conversation (status becomes closed unless it is suppressed), marks it read, turns the AI agent off for it (ai_status becomes disabled) and cancels its pending AI replies. Replies are refused while it is archived. Restoring (archived: false) sets status back to open (a suppressed conversation stays suppressed); it does not turn the AI agent back on and sends nothing.

Repeating a request is safe. If a PATCH after a reply fails, retry the PATCH; never resend the email to fix the conversation's state.

Path parameters

Name	Type	Required	Description
conversation_id	UUID	Yes	The conversation.

Body

Content type: application/json

Name	Type	Required	Description
read	boolean	No	true marks it read, false unread. Send exactly one of read or archived. A JSON boolean; strings and numbers are rejected.
archived	boolean	No	true archives it, false restores it. Send exactly one of read or archived. A JSON boolean; strings and numbers are rejected.

Response

Status: 200 OK

Name	Type	Description
id	UUID	The conversation.
read	boolean	Whether it is read now.
archived	boolean	Whether it is archived now.
status	string	Its status now. One of open, needs_review, booked, not_interested, closed, suppressed.
updated_at	timestamp	When it last changed (RFC 3339, UTC).

Example request

curl

curl -X PATCH "https://development.agencydevworks.ai/v1/inbox/conversations/44444444-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer dei_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "archived": true
}'

JavaScript

const response = await fetch("https://development.agencydevworks.ai/v1/inbox/conversations/44444444-0000-4000-8000-000000000002", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer dei_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "archived": true
  }),
});
const data = await response.json();

Example response

Status: 200 OK

{
  "id": "44444444-0000-4000-8000-000000000002",
  "read": true,
  "archived": true,
  "status": "closed",
  "updated_at": "2026-11-02T16:25:41Z"
}

Errors

HTTP	Code	When
403	insufficient_scope	The key does not have inbox:reply. Checked before the body is validated.
404	not_found	The conversation does not exist, was deleted, or the key's member cannot see it.
409	reply_in_progress	Archiving: a reply to the conversation is being sent right now. retryable is true: retry shortly.
413	payload_too_large	The body is larger than 1 MB. It was not read and nothing changed.
422	invalid_request	conversation_id is not a UUID, or the body is not exactly one of read or archived as a boolean. error.fields names body (none or both sent), the field that is not a boolean, or an unknown field.
503	dependency_unavailable	The inbox or the access check is temporarily unavailable. Retry with backoff.

Every endpoint can also answer 401 invalid_api_key, 429 rate_limited and 503 dependency_unavailable. See Errors in the overview.

Related endpoints

• GET /v1/inbox/conversations/{conversation_id} · Retrieve a conversation
• POST /v1/inbox/conversations/{conversation_id}/replies · Reply to a conversation
• GET /v1/inbox/conversations · List conversations