See what is waiting for a person

GET
/v1/inbox/needs-you

Everything that needs someone on your team, oldest first: an agent that asked for a person (offered, with its reason and summary), a conversation a person has that the customer is still waiting on (waiting_for_human), a message held back from the agent (held, with why), and a message that could not be delivered (delivery_failed, with its code). It is read from the conversation records, so nothing is lost if it is read late.

Requires an API key with the messages:read 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.

Query Parameters

kind?string

Only this kind of item: offered, waiting_for_human, held, delivery_failed, take_call (a call waiting for a person) or follow_up (a callback a caller asked for).

Value in"offered""waiting_for_human""held""delivery_failed""take_call""follow_up""question"
channel?string

Only this channel.

Length1 <= length <= 64
lineId?string

Only this line.

Formatuuid
assignedTo?string

Only what is assigned to this user.

Length1 <= length <= 200
conversationId?string

Only this conversation (its ask, if it has one).

Formatuuid
limit?integer

At most this many items (1-100).

Range1 <= value <= 100

Response Body

What is waiting for a person, oldest first

application/json
  1. response
items*array<>
counts*
summary*string
Example Request
curl "https://api.vlayers.ai/v1/inbox/needs-you?kind=offered&limit=20" \  -H "Authorization: Bearer $VOICELAYER_API_KEY"
Example Response
{  "items": [    {      "kind": "offered",      "conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",      "channel": "sms",      "lineId": "0192f5a8-1a2b-7c3d-8e4f-5a6b7c8d9e01",      "peer": "+15550123",      "since": "2026-10-20T15:04:05.000Z",      "waitedSeconds": 140,      "assignedTo": null,      "reason": "Wants a refund over the limit",      "summary": "Order 7, 400 dollars, damaged on arrival",      "holdReason": null,      "heldId": null,      "code": null,      "messageId": null    }  ],  "counts": {    "offered": 1,    "waiting_for_human": 0,    "held": 0,    "delivery_failed": 0,    "take_call": 0,    "follow_up": 0,    "question": 0  },  "summary": "1 conversation is waiting for a person to join."}