# Assign a conversation

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

`POST /v1/conversations/{id}/assign` · scope `conversations:control`

Assigns the conversation to one person on your team (their user id), or to nobody with `null`. Assigning does not change who answers: use `PATCH /v1/conversations/{id}` with `handoff: accept` to take a conversation over, which also assigns it to the person who took it. Each change is recorded on the conversation.

Requires an API key with the `conversations:control` 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"` |
| `assignedTo` | body | string | yes | The user id to assign it to, or `null` for nobody. A bare id such as `user_2abc`, never `user:user_2abc`. |

## Request

cURL:

```bash
curl -X POST "https://api.vlayers.ai/v1/conversations/$CONVERSATION_ID/assign" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assignedTo": "user_2abc"
  }'
```

TypeScript:

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

const voicelayer = new VoiceLayer();

const { conversation } = await voicelayer.conversations.assign('<conversation-id>', {
  assignedTo: 'user_2abc'
});
console.log(conversation.assignedTo);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.conversations.assign("<conversation-id>", assigned_to="user_2abc")
print(result.conversation.assigned_to)
```

## Response `200`

```json
{
  "conversation": {
    "id": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
    "channel": "sms",
    "lineId": "0192f5a8-1a2b-7c3d-8e4f-5a6b7c8d9e01",
    "bindingId": null,
    "peer": {
      "address": "+15550123"
    },
    "controller": "human",
    "status": "open",
    "openedAt": "2026-10-20T15:04:05.000Z",
    "lastActivityAt": "2026-10-20T15:04:05.000Z",
    "test": true,
    "assignedTo": "user_2abc"
  },
  "changed": true
}
```
