Web Calls

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.

required

Bearer your-web-calls-api-key

required

application/json

Request Body

string

required

The UUID of the agent to connect with. Must be an agent belonging to your company.

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.

object

Optional metadata object to pass to the agent. Supports the following fields:

Show metadata properties

object

Dynamic variables to inject into the agent’s prompt (same as phone calls)

object

Variables available to pre-call data enhancement tools

any

Any additional fields will be passed as custom metadata

Example Request

{
  "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

string

required

The LiveKit server URL to connect to

string

required

The name of the LiveKit room created for this session

string

required

JWT token for the participant to join the room. Valid for 15 minutes.

string

required

The identity assigned to the participant

Example Response

{
  "serverUrl": "wss://your-livekit-server.livekit.cloud",
  "roomName": "sawt_web_room_a1b2c3d4e5f6",
  "participantToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "participantName": "sawt_web_user_a1b2c3d4e5f6"
}

Error Handling

string

Error message if the request fails

Common Errors

Status	Error	Description
400	Invalid agentId format	The agentId must be a valid UUID
403	Web Calls API is not enabled	Contact support to enable this feature
403	Access denied to this agent	API key doesn’t have permission for this agent
404	Agent not found	Agent doesn’t exist or belongs to another company
500	Service not configured	LiveKit is not configured on the server

Example Error Response

{
  "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"
      }
    }
  }'

const axios = require("axios");

const createWebCall = async () => {
  try {
    const response = await axios.post(
      "https://app.sawt.sa/api/v1/web-calls/connect",
      {
        agentId: "e63355c6-cf51-40f3-b006-b615d9ab762d",
        userRef: "user_12345",
        metadata: {
          promptVariables: {
            customer_name: "Mohammed"
          }
        }
      },
      {
        headers: {
          Authorization: "Bearer your-web-calls-api-key",
          "Content-Type": "application/json",
        },
      }
    );

    console.log(response.data);
    // Use serverUrl, participantToken to connect via LiveKit SDK
    return response.data;
  } catch (error) {
    console.error(error);
  }
};

createWebCall();

import requests

def create_web_call():
    url = "https://app.sawt.sa/api/v1/web-calls/connect"
    
    headers = {
        "Authorization": "Bearer your-web-calls-api-key",
        "Content-Type": "application/json"
    }
    
    data = {
        "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
        "userRef": "user_12345",
        "metadata": {
            "promptVariables": {
                "customer_name": "Mohammed"
            }
        }
    }
    
    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

result = create_web_call()
print(result)
# Use serverUrl, participantToken to connect via LiveKit SDK

Phone Calls

Make outbound phone calls with Sawt AI agents

Webhooks

Receive real-time call events and transcripts

Sawt API Introduction

Voice Call Endpoints

Speech Services

Overview

API Endpoint

Authentication

Request Body

Response

Error Handling

Common Errors

Client Integration

Phone Calls

Webhooks

​Overview

​API Endpoint

​Authentication

​Request Body

​Response

​Error Handling

​Common Errors

​Client Integration

​Related

Phone Calls

Webhooks

Overview

API Endpoint

Authentication

Request Body

Response

Error Handling

Common Errors

Client Integration

Related