# Archive or label a conversation

Source: https://docs.vlayers.ai/reference/conversations/update-conversation-state

`PATCH /v1/conversations/{id}/state` · scope `conversations:manage`

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.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The conversation id. Example: `"0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21"` |
| `idempotency-key` | header | string | no | 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. Example: `"7f3c9a2e-5b1d-4c8e-9f0a-2d6b8e4c1a37"` |
| `status` | body | "open" \| "archived" \| "deleted" | no | `archived` puts the conversation away; `open` brings it back to the inbox or back from the trash; `deleted` moves it to the trash. |
| `handled` | body | boolean | no | `true` marks it as dealt with (it stays in the inbox); `false` puts it back to needing attention. |
| `read` | body | boolean | no | `true` marks it read for you, `false` unread. Only you are affected. |
| `addLabels` | body | string[] | no | Labels to put on it (letters, numbers, spaces and . _ : / - only; 64 characters each; 20 per conversation). |
| `removeLabels` | body | string[] | no | Labels to take off it. |
| `expectedStatus` | body | "open" \| "closed" \| "archived" \| "deleted" | no | Apply the change only if the conversation is still in this status. |

## Request

cURL:

```bash
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"
    ]
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { summary } = await voicelayer.conversations.updateState('<conversation-id>', {
  status: 'archived',
  handled: true,
  addLabels: ['invoice']
});
console.log(summary);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.conversations.update_state(
    "<conversation-id>",
    status="archived",
    handled=True,
    add_labels=["invoice"],
)
print(result.summary)
```

## Response `200`

```json
{
  "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\"."
}
```
