Chat takeover

GET /v1/takeover-presence#

List representative availability. Every representative's current availability row for this tenant. Availability decays: a row that has not been refreshed for a day stops counting, so a closed console cannot hold a queue open forever. The active load per representative is derived from the claimed sessions, never stored.

Responses

Example request

curl "https://api.voiceland.ai/v1/takeover-presence" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a TakeoverPresenceListResponse.

Example response

{
  "items": [
    {
      "available": true,
      "capacity": 3,
      "display_name": "Maria",
      "rep_id": "maria@acme.example",
      "updated_at": "2026-08-06T09:00:00Z"
    }
  ]
}

PUT /v1/takeover-presence#

Set a representative's availability. Upserts one representative's availability flag and capacity (how many concurrent taken-over chats they will hold; declaring available without a capacity defaults it to 1). Re-send periodically to keep the row fresh, presence decays after a day without a refresh. Whether *anyone* is available is what decides the visitor's "no one is available right now" notice.

Request body

application/json Schema: TakeoverPresencePutRequest

Responses

Example request

curl -X PUT "https://api.voiceland.ai/v1/takeover-presence" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "available": true,
  "capacity": 3,
  "display_name": "Maria",
  "rep_id": "maria@acme.example"
}'

A successful response returns a TakeoverPresenceView.

Example response

{
  "available": true,
  "capacity": 3,
  "display_name": "Maria",
  "rep_id": "maria@acme.example"
}

GET /v1/takeovers#

List chat takeover sessions. One page of your chat sessions that ever asked for a human, in session-id order. ?state=pending_human is the waiting queue a representative picks from; ?state=human is the sessions currently held by one; ?state=ai is the history. **Paging.** Pass the next_cursor from the previous response back as ?cursor=. **An empty next_cursor is the only signal that you have seen everything**, the state filter is applied after each read, so a short page, including an empty one, with a cursor set is normal and means "ask again".

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/takeovers" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a TakeoverListResponse.

Example response

{
  "items": [
    {
      "agent": "front-desk",
      "reason": "visitor asked for a person",
      "requested_at": "2026-08-06T09:15:04Z",
      "session_id": "widget-8c2f1a7e-4b3d-4e21-9c0a-5f6d7e8a9b0c",
      "state": "pending_human",
      "trigger": "visitor"
    }
  ],
  "next_cursor": ""
}

GET /v1/takeovers/{session_id}#

Get one takeover session. One session's takeover record. While the session is waiting (pending_human), queue_position carries its 1-based place in the tenant's waiting line.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/takeovers/{session_id}" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a TakeoverSessionView.

Example response

{
  "agent": "front-desk",
  "queue_position": 2,
  "reason": "could not answer after repeated attempts",
  "requested_at": "2026-08-06T09:15:04Z",
  "session_id": "widget-8c2f1a7e-4b3d-4e21-9c0a-5f6d7e8a9b0c",
  "state": "pending_human",
  "trigger": "llm"
}

POST /v1/takeovers/{session_id}/claim#

Claim a waiting session. Atomically assigns a waiting session to one representative and moves it to human. **Exactly one claim wins**: when two representatives race for the same session, the loser gets 409 and should pick another from the queue. From this moment the assistant stays silent and replies go through POST /takeovers/{session_id}/reply. **The response carries claim_token, and it is shown only once.** It is the proof of this claim, and EVERY route that touches the session afterwards requires it in the X-Takeover-Claim header: the two reads (/feed, /history), the draft (/assist) and the three writes (/reply, /resume, /close). claimed_by is a value the queue listing displays to everyone, so holding the claim, not knowing the claimant's name, is what authorizes reading a visitor's words, speaking to them, or ending the episode. Store it for the life of the episode; it cannot be re-read or re-issued, and it stops working the moment the episode ends. **take_over: true claims a session that is ALREADY HELD**, displacing its holder: their claim_token stops working and claimed_by becomes the caller, in one conditional write. It is the recovery path for a lost token, without it, a session whose token is gone could never be answered or ended and the visitor would be left in a chat nobody can close. It grants nothing a caller could not already reach with resume + request + claim; what it changes is that the displacement is a single audited action under the CALLER'S OWN rep_id instead of a sequence whose first step wore the previous holder's name. It answers 409 on a session nobody holds, claim those with the ordinary form, which still loses a race rather than displacing the winner.

Parameters

Request body

application/json Schema: TakeoverClaimRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/takeovers/{session_id}/claim" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rep_id": "maria@acme.example",
  "rep_name": "Maria"
}'

A successful response returns a TakeoverClaimResponse.

Example response

{
  "agent": "front-desk",
  "claim_token": "9f2c…",
  "claimed_at": "2026-08-06T09:15:41Z",
  "claimed_by": "maria@acme.example",
  "session_id": "widget-8c2f…",
  "state": "human"
}

POST /v1/takeovers/{session_id}/close#

Close the takeover as handled. Ends the human segment with resolution closed: the representative considers the conversation handled. The chat session itself may live on with the assistant, ending the chat is the visitor's move. **Requires the X-Takeover-Claim header**, for the same reason /resume does.

Parameters

Request body

application/json Schema: TakeoverRepRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/takeovers/{session_id}/close" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rep_id": "maria@acme.example"
}'

A successful response returns a TakeoverSessionView.

Example response

{
  "resolution": "closed",
  "resolved_at": "2026-08-06T09:24:10Z",
  "session_id": "widget-8c2f…",
  "state": "ai"
}

GET /v1/takeovers/{session_id}/feed#

Join the live feed of a claimed session. Mints a short-lived, subscribe-only join grant for the session's realtime conversation stream, so the claiming representative sees the visitor's messages as they are typed. topics names the streams to subscribe to: visitor_turns (what the visitor types), agent_turns (assistant and human bubbles), transcript (role-tagged turn frames) and takeover (state changes). The grant is read-only by design, replies go through POST /takeovers/{session_id}/reply so every human turn is validated, attributed and recorded on the transcript. **Requires the X-Takeover-Claim header**: the claim_token returned by POST /takeovers/{session_id}/claim. The feed carries the visitor's live words, and claimed_by is visible to everyone who can list the queue, so holding the claim, not knowing the claimant's name, is what opens it.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/takeovers/{session_id}/feed" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a TakeoverFeedResponse.

Example response

{
  "expires_in_s": 900,
  "livekit_url": "wss://rt.example.com",
  "room": "widget-8c2f…",
  "token": "eyJhb…",
  "topics": {
    "agent_turns": "lk.transcription",
    "takeover": "vl.takeover",
    "transcript": "transcript",
    "visitor_turns": "lk.chat"
  }
}

GET /v1/takeovers/{session_id}/history#

Read what was said before you claimed. The conversation as it stood while the visitor was waiting, so the representative who claims a chat does not start reading it mid-sentence. The live feed can only show what arrives after you join it, and the full transcript is only written when the session ends; this is the part in between. It is a **bounded snapshot**, not a log: the newest turns are kept, and truncated: true means older ones were dropped. as_of is when the snapshot was taken; compare it with the session's claimed_at to see how much of the wait it covers. offset_ms is the same anchor the live feed's transcript frames carry, so turns that appear in both can be matched. Answers 200 with an empty turns list when nothing was captured - a chat claimed the instant it opened has no history to show. **Requires the X-Takeover-Claim header**, exactly like the live feed and for the same reason: this is the visitor's own words, and it answers only the holder of the claim.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/takeovers/{session_id}/history" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a TakeoverHistoryResponse.

Example response

{
  "as_of": "2026-08-06T09:14:33Z",
  "session_id": "widget-8c2f…",
  "turns": [
    {
      "at": "2026-08-06T09:14:02Z",
      "offset_ms": 4120,
      "role": "caller",
      "text": "My invoice for March looks wrong."
    },
    {
      "at": "2026-08-06T09:14:05Z",
      "offset_ms": 7480,
      "role": "agent",
      "text": "I can look at that with you. Which amount were you expecting?"
    },
    {
      "at": "2026-08-06T09:14:31Z",
      "offset_ms": 33200,
      "role": "caller",
      "text": "Can I speak to a person please?"
    }
  ]
}

POST /v1/takeovers/{session_id}/reply#

Send a human reply into a claimed session. Delivers one reply from the claiming representative to the visitor. It renders in the widget as a human bubble, distinct from the assistant's, and lands on the transcript under the human_agent role, so every turn of a taken-over session stays attributable. **Requires the X-Takeover-Claim header**: the claim_token returned by POST /takeovers/{session_id}/claim. This is the call that puts WORDS IN FRONT OF A CUSTOMER attributed to rep_id, and rep_id is a value the caller writes while claimed_by is visible to everyone who can list the queue, so possession of the claim, not knowledge of the claimant's name, is what authorizes it. Missing header is 400; a wrong token, another representative's session, or an episode that already ended is 409. Set suggested_by_ai when the text came from an assist draft (POST /takeovers/{session_id}/assist or POST /assist/suggest), whether you sent it as-is or edited it first. The transcript turn records it, which is what keeps the answer-quality numbers honest about what a machine wrote and what a person did.

Parameters

Request body

application/json Schema: TakeoverReplyRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/takeovers/{session_id}/reply" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rep_id": "maria@acme.example",
  "rep_name": "Maria",
  "suggested_by_ai": false,
  "text": "Hi, Maria here, happy to help with your order."
}'

Example response

{
  "sent": true,
  "suggested_by_ai": false
}

POST /v1/takeovers/{session_id}/request#

Force a takeover on a live chat session. Moves a live chat session into the waiting queue on the operator's initiative, the third trigger next to the assistant's own judgement and the visitor's button. The assistant stops answering immediately; the visitor sees the transfer notice and their queue position. Idempotent while an episode is live: requesting a session that is already waiting or already with a human answers 200 with its current standing, untouched.

Parameters

Request body

application/json Schema: TakeoverConsoleRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/takeovers/{session_id}/request" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": "front-desk",
  "reason": "visitor sounds frustrated"
}'

A successful response returns a TakeoverRequestResponse.

Example response

{
  "queue_position": 1,
  "rep_available": true,
  "session": {
    "agent": "front-desk",
    "session_id": "widget-8c2f…",
    "state": "pending_human",
    "trigger": "console"
  },
  "waiting_count": 1
}

POST /v1/takeovers/{session_id}/resume#

Hand the chat back to the assistant. Ends the human segment with resolution resumed: the assistant answers the next visitor message again, with the human's replies in its context. **Requires the X-Takeover-Claim header**, exactly as /reply does. Ending an episode is not a lesser act than writing into one, the representative holding the chat is cut off and the visitor's conversation goes back to the assistant, and it used to cost only the claimed_by printed in the queue listing. If you no longer hold the token for a session you need to end, claim it with take_over: true first; that puts your own rep_id on the row before you touch it.

Parameters

Request body

application/json Schema: TakeoverRepRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/takeovers/{session_id}/resume" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rep_id": "maria@acme.example"
}'

A successful response returns a TakeoverSessionView.

Example response

{
  "resolution": "resumed",
  "resolved_at": "2026-08-06T09:24:10Z",
  "session_id": "widget-8c2f…",
  "state": "ai"
}

Schemas#

Error#

Error envelope returned for non-2xx responses.

TakeoverClaimRequest#

TakeoverClaimResponse#

TakeoverConsoleRequest#

TakeoverFeedResponse#

TakeoverHistoryResponse#

TakeoverHistoryTurnView#

TakeoverListResponse#

TakeoverPresenceListResponse#

TakeoverPresencePutRequest#

TakeoverPresenceView#

TakeoverRepRequest#

TakeoverReplyRequest#

TakeoverRequestResponse#

TakeoverSessionView#