> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sawt.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Calls

> Create browser-based voice calls with Sawt AI agents using LiveKit

<Note>
  This feature requires the **Web Calls API** to be enabled for your account. Contact support if you need access.
</Note>

## 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](https://docs.livekit.io/transport/sdk-platforms/) to establish a WebRTC voice session with your Sawt AI agent.

## API Endpoint

```bash theme={null}
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](https://app.sawt.sa/settings) under API Keys.

<ParamField header="Authorization" required>
  Bearer your-web-calls-api-key
</ParamField>

<ParamField header="Content-Type" required>
  application/json
</ParamField>

## Request Body

<ParamField body="agentId" type="string" required>
  The UUID of the agent to connect with. Must be an agent belonging to your company.
</ParamField>

<ParamField body="userRef" type="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.
</ParamField>

<ParamField body="metadata" type="object">
  Optional metadata object to pass to the agent. Supports the following fields:
</ParamField>

<Expandable title="metadata properties">
  <ParamField body="metadata.promptVariables" type="object">
    Dynamic variables to inject into the agent's prompt (same as phone calls)
  </ParamField>

  <ParamField body="metadata.preCallVariables" type="object">
    Variables available to pre-call data enhancement tools
  </ParamField>

  <ParamField body="[custom fields]" type="any">
    Any additional fields will be passed as custom metadata
  </ParamField>
</Expandable>

<Accordion title="Example Request">
  ```json theme={null}
  {
    "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
    "userRef": "user_12345",
    "metadata": {
      "promptVariables": {
        "customer_name": "Mohammed",
        "language": "Arabic"
      },
      "preCallVariables": {
        "account_id": "ACC123"
      },
      "session_source": "support_widget"
    }
  }
  ```
</Accordion>

## Response

<ResponseField name="serverUrl" type="string" required>
  The LiveKit server URL to connect to
</ResponseField>

<ResponseField name="roomName" type="string" required>
  The name of the LiveKit room created for this session
</ResponseField>

<ResponseField name="participantToken" type="string" required>
  JWT token for the participant to join the room. Valid for 15 minutes.
</ResponseField>

<ResponseField name="participantName" type="string" required>
  The identity assigned to the participant
</ResponseField>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "serverUrl": "wss://your-livekit-server.livekit.cloud",
    "roomName": "sawt_web_room_a1b2c3d4e5f6",
    "participantToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "participantName": "sawt_web_user_a1b2c3d4e5f6"
  }
  ```
</Accordion>

## Error Handling

<ResponseField name="error" type="string">
  Error message if the request fails
</ResponseField>

### 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           |

<Accordion title="Example Error Response">
  ```json theme={null}
  {
    "error": "Web Calls API is not enabled for this account"
  }
  ```
</Accordion>

## 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](https://docs.livekit.io/transport/sdk-platforms/) for platform-specific guides on JavaScript, React, iOS, Android, Flutter, and more.

<RequestExample>
  ```bash cURL theme={null}
  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"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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
  ```
</RequestExample>

## Related

<CardGroup cols={2}>
  <Card title="Phone Calls" icon="phone" href="/api-reference/endpoint/create-phone-call">
    Make outbound phone calls with Sawt AI agents
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/endpoint/webhooks">
    Receive real-time call events and transcripts
  </Card>
</CardGroup>