Archive or label a conversation

PATCH
/v1/conversations/{id}/state

Changes how a conversation is filed, in one request: status (archived puts it away, open brings it back), handled (dealt with, but it stays in the inbox), read (read or unread for you only) and addLabels / removeLabels. A new message on an archived conversation brings it back on its own. status: deleted moves it to the trash (it leaves every list and search; it needs a key allowed to delete conversations, and it goes in a request of its own); status: open on a deleted conversation brings it back from the trash, until the trash window ends (409 trash_expired) and unless a newer conversation for the same thread has started (409 conversation_forked). Pass expectedStatus to apply the change only if nobody moved the conversation first: otherwise the request is refused with 409 state_conflict. Sending the same request twice changes nothing the second time.

Requires an API key with the conversations:manage scope.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

id*string

The conversation id.

Header Parameters

idempotency-key?string

A unique value (a UUID works) that makes a retry safe: sending the same key again returns the first result instead of acting twice. 1–255 printable characters.

Length1 <= length <= 255

Request Body

application/json
  1. body
status?string

archived puts the conversation away; open brings it back to the inbox or back from the trash; deleted moves it to the trash.

Value in"open""archived""deleted"
handled?boolean

true marks it as dealt with (it stays in the inbox); false puts it back to needing attention.

read?boolean

true marks it read for you, false unread. Only you are affected.

addLabels?array<>

Labels to put on it (letters, numbers, spaces and . _ : / - only; 64 characters each; 20 per conversation).

Itemsitems <= 20
removeLabels?array<>

Labels to take off it.

Itemsitems <= 20
expectedStatus?string

Apply the change only if the conversation is still in this status.

Value in"open""closed""archived""deleted"

Response Body

The conversation after the change

application/json
  1. response
conversation*
changed*boolean
summary*string
Example Request
curl -X PATCH "https://api.vlayers.ai/v1/conversations/$CONVERSATION_ID/state" \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "status": "archived",    "handled": true,    "addLabels": [      "invoice"    ]  }'
Example Response
{  "conversation": {    "id": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",    "channel": "sms",    "lineId": "0192f5a8-1a2b-7c3d-8e4f-5a6b7c8d9e01",    "bindingId": null,    "peer": {      "address": "+15550123"    },    "controller": "api",    "status": "archived",    "openedAt": "2026-10-20T15:04:05.000Z",    "lastActivityAt": "2026-10-20T15:04:05.000Z",    "test": true,    "handled": true,    "labels": [      "invoice"    ]  },  "changed": true,  "summary": "Archived the conversation and added the label \"invoice\"."}