Send a control command to the live Session of a Call

POST /v1/calls/{call_id}/control

Sends one command (say, transfer, end or inject_context) to the live Session and answers 202 with the command id once the Session acknowledges it, within 2 seconds (a target), or 503 session_unreachable. A Call that is not live answers 409 call_not_active. The command passes through the same Policies as model output, and its outcome arrives as command.completed on the events channel. From 1.50.0 transfer is built, cold only: a destination key the pinned Agent version does not name, or that the transfer allowlist of the Organization does not hold, is refused with 403 transfer_refused before anything is relayed, and recorded as the Call event transfer.refused; a 1.49.0 api answered capability_not_available. Every command writes an Audit event, never its text, and a refused transfer writes it denied.

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_.../control" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "type": "say", "text": "<text>" }'

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

import os
import uuid

import requests

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

Parameters

Request body

Content type application/json, required: ControlCommand.

Responses

Fields of the 202 answer

The shape is ControlCommandResult.