Initiate WebRTC Call

Creates a session and dispatches an AI agent for a WebRTC voice call. Returns connection credentials that work seamlessly with our Vonative client SDKs. This is the WebRTC equivalent of dialing a phone number, it connects the caller directly to an agent for browser/mobile voice.

Endpoint

POST /v1/calls

Request Body

assistant_id

string

required

The UUID of the assistant to dispatch.

client_type

string

The platform of the connecting client. (web, mobile, terminal). Defaults to web.

reconnectable

boolean

Whether the call allows reconnecting after a drop. Defaults to false.

metadata

object

Custom metadata to pass to the agent.

variable_values

object

Variables for prompt templating (e.g. {"name": "John"}).

Authentication

Authorization: Bearer YOUR_API_KEY

(Optionally use the X-Vonative-Api-Key header)

Example Request

curl -X POST https://api.vonative.com/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assistant_id": "668a5015-e94c-4769-9180-72dff89ee9f4", "client_type": "web"}'

Response

{
  "success": true,
  "data": {
    "call_id": "call_9f2a1c",
    "room_name": "vona-call-9f2a1c",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "livekit_url": "wss://your-livekit-instance.livekit.cloud",
    "status": "pending",
    "reconnectable": false,
    "expires_at": "2026-07-28T10:05:00Z"
  }
}

Response Fields

Field	Type	Description
`call_id`	string	Session UUID for tracking and cleanup
`room_name`	string	Internal room name
`token`	string	Scoped access token — pass this to the Vonative SDK
`livekit_url`	string	WebRTC URL — pass this to the Vonative SDK
`status`	string	Status of the call
`reconnectable`	boolean	Whether the call can be reconnected
`expires_at`	string	Token expiration timestamp

Using the response with `@vonative/react`

import { VonativeProvider } from "@vonative/react";

// Fetch the token and url from your backend (which calls POST /v1/calls)
const { token, livekitUrl } = await fetch('/api/start-call', { method: 'POST' }).then(r => r.json());

// Wrap your UI
<VonativeProvider url={livekitUrl} token={token}>
  <YourCallUI />
</VonativeProvider>

For a complete walkthrough, see the Web Quickstart.

Reconnect to a Call

POST /v1/calls/{call_id}/reconnect

Returns a fresh scoped token for an existing call if it was created with reconnectable: true.

End session

POST /v1/sessions/{call_id}/end

Errors

Status	Description
`401`	Unauthorized - Invalid API Key
`402`	Insufficient credits
`404`	Assistant not found
`429`	Concurrent call limit reached on your plan
`500`	Room creation failed

Authentication

Introduction

Assistants

Phone Numbers

Workflows

Calls

Files

Tools

Server Credentials

Sessions

Call Logs

Webhooks

Campaigns

Initiate WebRTC Call

Initiate WebRTC Call

Endpoint

Request Body

Authentication

Example Request

Response

Response Fields

Using the response with `@vonative/react`

Reconnect to a Call

End session

Errors

See also

​Initiate WebRTC Call

​Endpoint

​Request Body

​Authentication

​Example Request

​Response

​Response Fields

​Using the response with @vonative/react

​Reconnect to a Call

​End session

​Errors

​See also

Initiate WebRTC Call

Endpoint

Request Body

Authentication

Example Request

Response

Response Fields

Using the response with `@vonative/react`

Reconnect to a Call

End session

Errors

See also