Archive or label a conversation
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.
apiKeyAuthorizationBearer <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.
id*stringThe conversation id.
idempotency-key?stringA 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.
1 <= length <= 255application/json- body
status?stringarchived puts the conversation away; open brings it back to the inbox or back from the trash; deleted moves it to the trash.
"open""archived""deleted"handled?booleantrue marks it as dealt with (it stays in the inbox); false puts it back to needing attention.
read?booleantrue 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).
items <= 20removeLabels?array<>Labels to take off it.
items <= 20expectedStatus?stringApply the change only if the conversation is still in this status.
"open""closed""archived""deleted"The conversation after the change
application/json- response
conversation*changed*booleansummary*stringcurl -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" ] }'{ "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\"."}