# Livekit

Connect your LiveKit real-time voice agents to KrosAI phone numbers for emerging market coverage.

## Overview

LiveKit is an open-source platform for building real-time audio/video applications. With KrosAI, you can bridge LiveKit agents to phone calls in Africa and the Middle East.

## Prerequisites

* KrosAI account with verified KYC
* LiveKit Cloud account or self-hosted instance
* A LiveKit agent configured and running
* SIP Trunk configured in LiveKit
* At least one KrosAI phone number

## Setup Steps

{% stepper %}
{% step %}

### Configure LiveKit SIP Trunk

* Log into your [LiveKit Dashboard](https://cloud.livekit.io/)
* Navigate to **SIP** → **Trunks**
* Create or select a SIP Trunk
* Copy:
  * **Agent ID** (your agent's name/ID)
  * **SIP Trunk ID**
  * **SIP URI** (e.g., `sip:xxxxx.sip.livekit.cloud`)
    {% endstep %}

{% step %}

### Connect LiveKit in KrosAI

* Go to **Settings → Integrations** in your KrosAI Dashboard
* Click **Connect** next to LiveKit
* Enter:
  * **API Key** (from LiveKit)
  * **API Secret**
  * **Server URL** (WebSocket URL, e.g., `wss://your-app.livekit.cloud`)
* Click **Save & Test**
  {% endstep %}

{% step %}

### Create a LiveKit Endpoint

{% code title="Create Endpoint (curl)" %}

```bash
curl -X POST "https://api.krosai.com/v1/endpoints" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LiveKit Voice Agent",
    "type": "agent",
    "url": "sip:xxxxx.sip.livekit.cloud",
    "provider_config": {
      "provider": "livekit",
      "livekit_agent_name": "my-voice-agent",
      "livekit_sip_trunk_id": "trunk_abc123",
      "livekit_sip_uri": "sip:xxxxx.sip.livekit.cloud"
    }
  }'
```

{% endcode %}
{% endstep %}

{% step %}

### Attach to Phone Number

{% code title="Attach Endpoint to Phone Number (curl)" %}

```bash
curl -X PATCH "https://api.krosai.com/v1/phone-numbers/pn_abc123" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_id": "ep_livekit_xyz"
  }'
```

{% endcode %}
{% endstep %}
{% endstepper %}

## Configuration Options

### Provider Config Fields

| Field                  | Required | Description                        |
| ---------------------- | -------- | ---------------------------------- |
| `livekit_agent_name`   | Yes      | Your LiveKit agent ID for dispatch |
| `livekit_sip_trunk_id` | Yes      | Your LiveKit SIP Trunk ID          |
| `livekit_sip_uri`      | Yes      | Full SIP URI from LiveKit          |

### Global Settings (Integration Level)

| Field        | Required | Description                |
| ------------ | -------- | -------------------------- |
| `api_key`    | Yes      | LiveKit API Key            |
| `api_secret` | Yes      | LiveKit API Secret         |
| `server_url` | Yes      | WebSocket URL (wss\://...) |

## Agent Verification

<details>

<summary>Important: Agent verification behavior</summary>

LiveKit agents are ephemeral worker processes. They cannot be verified via API before a call. Verification happens at call-time dispatch.

Ensure your agent is:

* Running and connected to LiveKit
* Registered with the correct Agent ID
* Ready to handle SIP calls

</details>

## Outbound Calls

{% code title="Create Outbound Call (curl)" %}

```bash
curl -X POST "https://api.krosai.com/v1/outbound-calls" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+2348012345678",
    "to_number": "+14155551234",
    "endpoint_id": "ep_livekit_xyz"
  }'
```

{% endcode %}

## Webhooks

Receive call events:

```json
{
  "event": "call.completed",
  "call_id": "call_abc123",
  "direction": "inbound",
  "from_number": "+14155551234",
  "to_number": "+2348012345678",
  "duration": 180,
  "provider": "livekit",
  "agent_name": "my-voice-agent"
}
```

## Troubleshooting

<details>

<summary>Call Not Connecting</summary>

* Verify SIP Trunk is configured in LiveKit
* Check the SIP URI is correct
* Ensure your agent is running
* Review LiveKit logs for SIP errors

</details>

<details>

<summary>Agent Not Dispatching</summary>

* Confirm agent is registered with correct ID
* Check LiveKit worker is connected
* Verify room permissions in LiveKit

</details>

<details>

<summary>Audio Issues</summary>

* Check codec compatibility (Opus preferred)
* Verify SIP trunk audio settings
* Review network latency

</details>

## LiveKit Agent Example

{% code title="livekit\_agent.py" %}

```python
# Python LiveKit Agent Example
from livekit.agents import AutoSubscribe, JobContext, WorkerOptions, cli
from livekit.agents.voice_assistant import VoiceAssistant
from livekit.plugins import openai, silero

async def entrypoint(ctx: JobContext):
    await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)
    
    assistant = VoiceAssistant(
        vad=silero.VAD.load(),
        stt=openai.STT(),
        llm=openai.LLM(),
        tts=openai.TTS(),
    )
    
    assistant.start(ctx.room)
    await assistant.say("Hello! How can I help you today?")

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.krosai.com/integration/livekit.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.