End a Call

POST /v1/calls/{call_id}/end

Ends a Call with the ended reason canceled (FR-calls-8). A Call no worker runs, scheduled or queued and not yet claimed, ends at once and its reservation is released. Otherwise the api records the request in end_requested_at and the Call event call.end_requested, then pushes it to the worker that runs the Call (1.36.0; the Call event call.end_pushed records the result, accepted, refused, no_room or no_participant, and elapsed_ms). The worker stops the agent audio at once, ends the Session with canceled and finalizes, which FR-calls-8 asks within 2 seconds (a target), and the Call event call.end_received records its receipt. The end_requested flag on the answer to the worker's next signal is the fallback: a push that LiveKit refuses or that no worker reads leaves the end to the next heartbeat, up to one heartbeat period (15 seconds, target), and the audio is cut as soon as the worker learns of it. A second request records nothing new and pushes again. A Call whose worker was already lost reads nothing: the request brings its lease forward and the sweeper ends it worker_lost, its own rule, with the request kept in the Call events. The answer is the Call as it stands once the request is recorded. A Call that has already ended answers 409 call_not_active.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the calls:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/calls/call_.../end" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const response = await fetch(`${process.env.VOCAL_API}/v1/calls/call_.../end`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/calls/call_.../end",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={},
)
print(response.status_code, response.text)

Parameters

Request body

Content type application/json, required: CallEndRequest.

Responses

Fields of the 200 answer

The shape is Call.