Assign a conversation

POST
/v1/conversations/{id}/assign

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.

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.

Path Parameters

id*string

The conversation id.

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
assignedTo*|

The user id to assign it to, or null for nobody. A bare id such as user_2abc, never user:user_2abc.

Match^(?!(plugin|user|principal|line|counterparty|system):)\S+$
Length1 <= length <= 200

Response Body

The conversation after the change

application/json
  1. response
conversation*
changed*boolean
Example Request
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"  }'
Example Response
{  "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}