Archive or label many conversations

POST
/v1/conversations/state

The same change as updating one conversation, for up to 100 at once. The answer lists each conversation: a conversation that is not yours, or is not in the status you expected, is reported as not changed and the others still apply.

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.

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 them away; open brings them back to the inbox.

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

true marks them as dealt with; false puts them back to needing attention.

read?boolean

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

addLabels?array<>

Labels to put on each.

Itemsitems <= 20
removeLabels?array<>

Labels to take off each.

Itemsitems <= 20
expectedStatus?string

Change each only if it is still in this status.

Value in"open""closed""archived""deleted"
conversationIds*array<>

The conversations to change, 1 to 100.

Items1 <= items <= 100

Response Body

One result per conversation, in the order asked, and a one-sentence summary

application/json
  1. response
results*array<>
summary*string
Example Request
curl -X POST https://api.vlayers.ai/v1/conversations/state \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "conversationIds": [      "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21"    ],    "status": "archived"  }'
Example Response
{  "results": [    {      "id": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",      "ok": true,      "changed": true    }  ],  "summary": "Archived 1 conversation."}