Create WebRTC Call

Creates a test call via the Ultravox API using WebRTC medium. The frontend uses the returned join_url with the Ultravox Client SDK to connect the user's browser microphone to the AI agent.

Endpoint

Property	Value
Function Name	calls-create
HTTP Method	POST
Authentication	Supabase JWT (Bearer token)
Required Role	Any authenticated agency user

Request

Headers

Authorization: Bearer <supabase_jwt_token>
Content-Type: application/json

Body

Field	Type	Required	Description
agent_id	string	Yes	Ultravox agent ID from agent_mappings.ultravox_agent_id

Response

Success (201)

{
  "call_id": "uuid",
  "ultravox_call_id": "uv-call-abc123",
  "join_url": "wss://voice.ultravox.ai/...",
  "created_at": "2025-01-15T10:30:00Z"
}

Partial Success (201)

If the call is created in Ultravox but the local database insert fails, a 201 response is still returned with a warning:

{
  "call_id": null,
  "ultravox_call_id": "uv-call-abc123",
  "join_url": "wss://voice.ultravox.ai/...",
  "created_at": "2025-01-15T10:30:00Z",
  "warning": "Call created but failed to save to database"
}

Error Responses

Status	Condition
400	agent_id is missing
400	Ultravox API key not configured for the agency
401	Missing or invalid authorization header
403	User is not associated with an agency
404	Agent not found or does not belong to the user's agency
405	HTTP method is not POST
500	Failed to retrieve API credentials from the database
500	Unexpected server error
502	Ultravox API returned an error when creating the call

Behavior

• Authenticates the user via Supabase JWT and retrieves their agency_id from the users table.
• Validates that agent_id is provided and belongs to the user's agency via the agent_mappings table.
• Retrieves the agency's decrypted Ultravox API key by calling the get_agency_credentials RPC.
• Calls the Ultravox API (POST /api/calls) with medium: { webRtc: {} } to create a browser-based call.
• Stores the call in the calls table with source='webrtc', direction='outbound', and metadata: { test_call: true }.
• Returns the joinUrl from Ultravox for use with the Ultravox Client SDK.

Database Tables

Table / RPC	Operation	Description
users	Read	Fetches user profile to determine agency_id
agent_mappings	Read	Validates agent_id belongs to the user's agency
get_agency_credentials (RPC)	Read	Retrieves decrypted Ultravox API key
calls	Insert	Stores the call record with WebRTC source

External APIs

API	Method	Endpoint	Description
Ultravox	POST	/api/calls	Creates a WebRTC call for the specified agent

Related Functions

• Create Outbound Call -- Initiate a phone call via Telnyx instead of WebRTC
• Get Call Recording -- Retrieve recording URL after the call completes
• Webhook Ingest -- Receives call status updates from Ultravox