Skip to main content
This feature requires the Web Calls API to be enabled for your account. Contact support if you need access.

​
Overview

The Web Calls API allows you to create real-time voice conversations with Sawt AI agents directly in the browser or mobile apps. This is perfect for:
  • Customer support widgets - Embed voice AI in your website
  • Web applications - Add voice capabilities to your app
  • Kiosks & terminals - Deploy voice AI on any web-capable device
The API returns LiveKit connection credentials that you can use with the LiveKit Client SDKs to establish a WebRTC voice session with your Sawt AI agent.

​
API Endpoint

POST https://app.sawt.sa/api/v1/web-calls/connect

​
Authentication

This endpoint requires a Web Calls API key. Generate one from your Settings page under API Keys.
​
Authorization
required
Bearer your-web-calls-api-key
​
Content-Type
required
application/json

​
Request Body

​
agentId
string
required
The UUID of the agent to connect with. Must be an agent belonging to your company.
​
userRef
string
Optional user reference identifier (max 128 characters). Useful for tracking which user initiated the call. Will be sanitized to alphanumeric characters, dashes, underscores, and dots.
​
metadata
object
Optional metadata object to pass to the agent. Supports the following fields:
{
  "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
  "userRef": "user_12345",
  "metadata": {
    "promptVariables": {
      "customer_name": "Mohammed",
      "language": "Arabic"
    },
    "preCallVariables": {
      "account_id": "ACC123"
    },
    "session_source": "support_widget"
  }
}

​
Response

​
serverUrl
string
required
The LiveKit server URL to connect to
​
roomName
string
required
The name of the LiveKit room created for this session
​
participantToken
string
required
JWT token for the participant to join the room. Valid for 15 minutes.
​
participantName
string
required
The identity assigned to the participant
{
  "serverUrl": "wss://your-livekit-server.livekit.cloud",
  "roomName": "sawt_web_room_a1b2c3d4e5f6",
  "participantToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "participantName": "sawt_web_user_a1b2c3d4e5f6"
}

​
Error Handling

​
error
string
Error message if the request fails

​
Common Errors

StatusErrorDescription
400Invalid agentId formatThe agentId must be a valid UUID
403Web Calls API is not enabledContact support to enable this feature
403Access denied to this agentAPI key doesn’t have permission for this agent
404Agent not foundAgent doesn’t exist or belongs to another company
500Service not configuredLiveKit is not configured on the server
{
  "error": "Web Calls API is not enabled for this account"
}

​
Client Integration

Once you receive the connection credentials, use the LiveKit Client SDK to establish the voice session with your Sawt AI agent. See the LiveKit Client SDK documentation for platform-specific guides on JavaScript, React, iOS, Android, Flutter, and more. 
curl -X POST "https://app.sawt.sa/api/v1/web-calls/connect" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-web-calls-api-key" \
  -d '{
    "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
    "userRef": "user_12345",
    "metadata": {
      "promptVariables": {
        "customer_name": "Mohammed"
      }
    }
  }'

Phone Calls

Make outbound phone calls with Sawt AI agents

Webhooks

Receive real-time call events and transcripts