Create a Web Call

Connect a browser participant to a Convoi agent over LiveKit.

6 min read

Endpoint

http

POST /api/v1/public/calls

Headers

Optional: include an Idempotency-Key header (any random UUID) to make this POST safe to retry within a 24-hour window. Repeating the same key returns the original call instead of creating a duplicate.

http

Idempotency-Key: 6f1c4b7e-… (any UUID)

Request body: minimal

Set type to "web" and provide an agent_id (the agent that will run the call). Convoi provisions a LiveKit room, mints a participant token, and returns both in the response.

json

{
  "type": "web",
  "agent_id": "agt_b88d642dd68747f28305c428b209xxxx"
}

Request body: with overrides

agent_overrides lets you tweak the agent's first message, system prompt, or any LLM/TTS/STT setting for this call only, without editing the agent itself.

json

{
  "type": "web",
  "agent_id": "agt_b88d642dd68747f28305c428b209xxxx",
  "participant_name": "xyz",
  "agent_overrides": {
    "first_message": "Hi, how can I help?",
    "system_prompt": "You are a concise support agent.",
    "llm":  { "model": "gpt-4o-mini", "temperature": 0.7 },
    "tts":  { "voice_id": "rachel", "speed": 1.0 },
    "stt":  { "language": "en", "model": "nova-2" },
    "knowledge_base_ids": ["kb_3a1c…32hex…"]
  },
  "metadata": { "source": "landing-page", "user_ref": "u_42" }
}

Field	Type	Required	Notes
type	string	yes	Must be "web".
agent_id	string	yes	An agent on your account.
participant_name	string	no	Display name for the participant in LiveKit.
agent_overrides	object	no	Per-call overrides: first_message, system_prompt, llm, tts, stt, knowledge_base_ids.
metadata	object	no	Free-form key/value pairs returned with every call event.

Response

json

{
  "id": "call_01HX…",
  "object": "call",
  "type": "web",
  "status": "initiated",
  "agent_id": "agt_…",
  "room_id": "…",
  "livekit": {
    "url": "wss://your-livekit-host",
    "token": "eyJhbGciOi…",
    "participant_identity": "public-…"
  },
  "duration_seconds": 0.0,
  "cost": { "amount": 0.0, "currency": "USD" },
  "metadata": { "source": "landing-page" },
  "created_at": "...",
  "updated_at": "..."
}

Pass livekit.url and livekit.token to the LiveKit client SDK in your browser to join the call. The agent joins automatically as soon as the participant connects. duration_seconds and cost.amount update as the call progresses.

Related in Calls