# Archive or label many conversations

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

`POST /v1/conversations/state` · scope `conversations:manage`

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.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `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 them away; `open` brings them back to the inbox. |
| `handled` | body | boolean | no | `true` marks them as dealt with; `false` puts them back to needing attention. |
| `read` | body | boolean | no | `true` marks them read for you, `false` unread. Only you are affected. |
| `addLabels` | body | string[] | no | Labels to put on each. |
| `removeLabels` | body | string[] | no | Labels to take off each. |
| `expectedStatus` | body | "open" \| "closed" \| "archived" \| "deleted" | no | Change each only if it is still in this status. |
| `conversationIds` | body | string[] | yes | The conversations to change, 1 to 100. |

## Request

cURL:

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

TypeScript:

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

const voicelayer = new VoiceLayer();

const { summary } = await voicelayer.conversations.batchUpdateState({
  conversationIds: ['0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21'],
  status: 'archived'
});
console.log(summary);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.conversations.batch_update_state(
    conversation_ids=["0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21"],
    status="archived",
)
print(result.summary)
```

## Response `200`

```json
{
  "results": [
    {
      "id": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
      "ok": true,
      "changed": true
    }
  ],
  "summary": "Archived 1 conversation."
}
```
