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

# LiveKit

> Test your LiveKit agent and score live calls.

Connect an agent that runs as a LiveKit Agents worker.

![The LiveKit connection fields with saved LiveKit credentials, an agent name, a customer tool topic, and metadata JSON](https://mintcdn.com/bluejay/EeUk0hD_moG9tWmI/images/connect-livekit.png?fit=max\&auto=format\&n=EeUk0hD_moG9tWmI\&q=85\&s=064926fdcdaeb3cec04a4fc439ad4cb0)

## Connect

**1. Save the LiveKit keys**

In LiveKit Cloud, open **Settings > API keys** and copy the API key, API secret, and server URL. The URL looks like `wss://your-project.livekit.cloud`. In Bluejay, open **Settings → Integrations** and choose the **LiveKit** tab. Paste them there. Skip this step if your server will issue room tokens through a [token webhook](#token-webhook).

**2. Create the agent**

Create a Voice agent with the **LiveKit** connection type:

* **LiveKit Agent Name**: the name your worker registers with. Leave it empty only if your worker uses automatic dispatch, because Bluejay then dispatches no agent.
* **LiveKit Customer Tool Topic (Optional)**: set it to record tool calls. See [Tool calls](#tool-calls).
* **LiveKit Metadata (Optional JSON)**: Bluejay sends it as the job metadata when it dispatches your agent, with each Digital Human's `livekit_metadata` merged over it and the simulation IDs added, such as `X-Simulation-Result-Id`.

**3. Choose how Bluejay joins the room**

In the agent's **Connection Settings**, set **Authentication**:

* **API Key**: Bluejay creates the room token with the keys you saved.
* **Token Webhook**: your server creates the room token, so Bluejay stores no LiveKit keys. Put the full header value in **Authorization Header (Optional)**, scheme included, for example `Bearer <token>`. See [Token webhook](#token-webhook).

## Test

> [tab] Direct
>
> Use this path to iterate on agent logic without phone audio. Bluejay creates a room in your LiveKit project and dispatches your agent into it, so you need no phone number. An agent with the **LiveKit** connection type, set up as in [Connect](#connect), uses this path.
>
> <video controls muted playsInline preload="metadata" src="https://mintcdn.com/bluejay/KMCbf2NezpR35C6-/videos/connection-settings.mp4?fit=max&auto=format&n=KMCbf2NezpR35C6-&q=85&s=80ba6b2dc18c6edb37a13e13909335ed" />

> [tab] SIP
>
> Use SIP to test the same path that your phone calls take. Bluejay sends a SIP INVITE to `sip:<number>@<your-project>.sip.livekit.cloud`. The number does not need to be one you bought, as long as it matches your trunk.
>
> **1. Create an inbound trunk**
>
> Create the trunk in the project that owns the SIP host.
>
> ```json trunk.json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> { "trunk": { "name": "bluejay-inbound", "numbers": ["+15551230000"] } }
> ```
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> lk sip inbound create trunk.json
> ```
>
> To read the result ID from your agent, for example to call [Update Simulation Result](https://docs.getbluejay.ai/api-reference/endpoint/update-simulation-result.md), map the `X-Simulation-Result-Id` header to a participant attribute. Run `lk sip inbound update --id ST_your_trunk_id -` with:
>
> ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> { "headers_to_attributes": { "X-Simulation-Result-Id": "X-Simulation-Result-Id" } }
> ```
>
> The ID then shows in `participant.attributes`. LiveKit sets the attribute asynchronously, so it can be missing at the moment the SIP participant joins.
>
> **2. Create a dispatch rule**
>
> Create the rule on the trunk, and set `agentName` to your worker name.
>
> ```json dispatch.json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> {
>   "name": "bluejay-dispatch",
>   "rule": { "dispatchRuleIndividual": { "roomPrefix": "sip-" } },
>   "trunkIds": ["ST_your_trunk_id"],
>   "roomConfig": { "agents": [{ "agentName": "your-agent" }] }
> }
> ```
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> lk sip dispatch create dispatch.json
> ```
>
> **3. Create the Bluejay agent**
>
> Create a Voice agent with the **SIP** connection type, and set **SIP URI** to `sip:+15551230000@your-project.sip.livekit.cloud`. Use the number exactly as it appears in the trunk `numbers`. See [SIP](https://docs.getbluejay.ai/integrations/sip.md) for the other SIP fields.
>
> Bluejay puts each custom SIP header from **Connection Settings** on the INVITE under the name you enter, and also sends all of them together as JSON in `X-Custom-Headers`. Your agent can read them with the `lk.sip.GetRemoteHeaders` RPC:
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import json
> from livekit import rtc
>
> participant = await ctx.wait_for_participant()
> if participant.kind == rtc.ParticipantKind.PARTICIPANT_KIND_SIP:
>     response = await ctx.room.local_participant.perform_rpc(
>         destination_identity=participant.identity,
>         method="lk.sip.GetRemoteHeaders",
>         payload=json.dumps({}),
>     )
>     headers = json.loads(response)["headers"]
> ```

> [tab] Outbound
>
> To test an agent that places calls, your agent dials the Digital Humans. The **LiveKit** connection type is inbound only, so use the **Phone** connection type.
>
> **1. Create the agent**
>
> Create an Outbound Voice agent with the **Phone** connection type, and give each Digital Human a phone number.
>
> **2. Set a trigger**
>
> Set **Outbound Trigger Webhook URL** on the agent, or subscribe a [webhook](https://docs.getbluejay.ai/api-reference/webhooks.md) to `outbound_simulation_started`. Without a trigger, your agent never learns that a run started, and the Digital Humans wait until the run times out.
>
> **3. Dial the Digital Humans**
>
> When the trigger fires, have your agent dial each `phone_number`, for example with `create_sip_participant`. The [event payload](https://docs.getbluejay.ai/api-reference/webhook/events-webhook.md) lists the numbers.

### Token webhook

With **Token Webhook** authentication, Bluejay sends a `POST` to the **Token Webhook URL** before each call:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "room_name": "test-room-812192",
  "participant_identity": "digital-human-812192",
  "agent_name": "your-agent-name",
  "agent_metadata": { "any": "metadata you configured" },
  "sim_conversation_id": 812192
}
```

| Response field | Description |
| - | - |
| `token` | Required. A LiveKit token for the identity with `room_join`, `can_publish`, and can\_subscribe. Add can\_publish\_data for tool call tracking. The TTL must cover the call. |
| `livekit_url` | Replaces the server URL from the integration. Required if you saved no LiveKit integration. |
| `room_name` | Optional. Replaces the room the Digital Human joins. |

Make sure your agent is dispatched. Put a `RoomAgentDispatch` in the token room configuration, or dispatch the agent from your server.

Bluejay waits 15 seconds for the response. If the request times out or returns `408`, `429`, or a `5xx` status, Bluejay tries again, up to 3 attempts in total. If your endpoint returns `401` or `403`, Bluejay does not try again, and the run fails with `NO_CONNECTION` and `LIVEKIT_SESSION_SETUP_FAILED`.

### Tool calls

To record your agent's tool calls in a simulation, set **LiveKit Customer Tool Topic**, then have your agent publish one data packet on that topic each time it calls a tool. Bluejay saves the packets when the simulation ends.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import json

async def report_tool_call(room, tool_name, parameters, output):
    payload = json.dumps({"name": tool_name, "parameters": parameters, "output": output}).encode()
    await room.local_participant.publish_data(payload, topic="customer.tool.calls")
```

| Field | Description |
| - | - |
| `name` | Required. The tool name. |
| `parameters` | The tool input. |
| `output` | The tool return value. |
| start\_offset\_ms | Milliseconds from call start. |
| `client_ts` | ISO 8601 time of the call. Bluejay uses it when start\_offset\_ms is not set. If you send neither, Bluejay uses the time it gets the packet. |
| invocation\_id | Bluejay drops a second packet with the same ID. |

### Traces

To see your agent's traces on a simulation result, export OpenTelemetry traces to Bluejay, then link them to the result when the call shuts down.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import httpx
from opentelemetry import context as otel_context
from opentelemetry.sdk import trace as trace_sdk
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.resources import SERVICE_NAME, Resource
from livekit.agents.telemetry import set_tracer_provider
import opentelemetry.trace as otel_trace

tracer_provider = trace_sdk.TracerProvider(resource=Resource.create({SERVICE_NAME: "my-agent"}))
tracer_provider.add_span_processor(
    SimpleSpanProcessor(
        OTLPSpanExporter("https://otlp.getbluejay.ai/v1/traces", headers={"X-API-KEY": BLUEJAY_API_KEY})
    )
)
set_tracer_provider(tracer_provider)
otel_trace.set_tracer_provider(tracer_provider)

# Before session.start():
span = otel_trace.get_tracer("my-agent").start_span("call")
otel_context.attach(otel_trace.set_span_in_context(span))
trace_ids = [format(span.get_span_context().trace_id, "032x")]

# simulation_result_id: the X-Simulation-Result-Id value from the job metadata
# or, over SIP, from the participant attributes.

async def on_shutdown():
    span.end()
    tracer_provider.force_flush()
    if simulation_result_id:
        async with httpx.AsyncClient(timeout=10) as client:
            res = await client.post(
                "https://api.getbluejay.ai/v1/update-simulation-result",
                json={"simulation_result_id": simulation_result_id, "trace_ids": trace_ids},
                headers={"X-API-Key": BLUEJAY_API_KEY},
            )
            res.raise_for_status()
    tracer_provider.shutdown()

ctx.add_shutdown_callback(on_shutdown)
```

Keep the order in `on_shutdown`: `span.end()`, then `force_flush()`, then the POST, then `shutdown()`. If you send the POST before the flush, the trace can be missing. See [Traces](https://docs.getbluejay.ai/test/traces.md).

## Monitor

To score your live calls, send them with the LiveKit webhook or from your agent through the API. Use the API if you need tool calls.

> [tab] Webhook
>
> LiveKit sends every call in the project to Bluejay. This path does not capture tool calls.
>
> > [!WARNING]
> >
> > Cost risk. The LiveKit webhook streams call data to Bluejay. LiveKit can bill you for the egress.
>
> **1. Copy the webhook URL**
>
> In Bluejay, open **Settings → Integrations** and choose the **LiveKit** tab. Save your LiveKit keys, then copy the webhook URL from **Show configuration**.
>
> **2. Add the webhook in LiveKit Cloud**
>
> In LiveKit Cloud, go to **Settings > Webhooks** and add the URL, signed with your API key.
>
> **3. Set a dispatch name**
>
> Make sure your agent has a [dispatch name](https://docs.livekit.io/agents/build/dispatch/) (`agent_name` in `WorkerOptions`).
>
> On the first call with a new dispatch name, Bluejay creates an agent for it. If you refresh the webhook URL in Bluejay, the old URL stops working, so update it in LiveKit Cloud too.
>
> <video controls muted playsInline preload="metadata" src="https://mintcdn.com/bluejay/XlhRTd0LcvaVmeYl/videos/livekit-obs-full.mp4?fit=max&auto=format&n=XlhRTd0LcvaVmeYl&q=85&s=fab3437591c194d3048124b0273c2ebb" />

> [tab] API
>
> Your agent sends each finished call to [`/v1/evaluate`](https://docs.getbluejay.ai/api-reference/endpoint/evaluate) in a shutdown callback. This path captures tool calls and attributes each call to one Bluejay agent.
>
> **1. Create the agent**
>
> Create an agent in Bluejay and copy its agent ID.
>
> **2. Add a shutdown callback**
>
> Add a shutdown callback that sends the call.
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import os
> import httpx
> from livekit.agents import JobContext
>
> async def entrypoint(ctx: JobContext):
>     async def report_to_bluejay():
>         payload = {
>             "agent_id": os.environ["BLUEJAY_AGENT_ID"],
>             "start_time_utc": started_at_iso,  # ISO 8601 UTC, captured at call start
>             "participants": [{"role": "AGENT"}, {"role": "USER"}],
>             "transcript": transcript,  # [{start_offset_ms, end_offset_ms, speaker, utterance}]
>             "tool_calls": tool_calls,  # [{name, parameters, output, start_offset_ms}]
>             # "recording_url": recording_url,  # enables audio metrics
>         }
>         async with httpx.AsyncClient(timeout=10) as client:
>             res = await client.post(
>                 "https://api.getbluejay.ai/v1/evaluate",
>                 json=payload,
>                 headers={"X-API-Key": os.environ["BLUEJAY_API_KEY"]},
>             )
>             res.raise_for_status()
>
>     ctx.add_shutdown_callback(report_to_bluejay)
> ```
>
> If the project also sends calls through the webhook, set `bluejay.bypass_webhook` when the agent joins, so Bluejay does not get each call twice:
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> await req.accept(identity="support-bot", attributes={"bluejay.bypass_webhook": "true"})
> ```

## Troubleshooting

| What you see | What to do |
| - | - |
| **No Connection** with LIVEKIT\_SESSION\_SETUP\_FAILED | Bluejay could not join the room. If you use a token webhook, check that it accepts the **Authorization Header** and returns a working token. A `401` or `403` from the webhook is not retried. |
| SIP `404 No trunk found` | The INVITE reached LiveKit, but no trunk matched. Create the trunk on the project in the SIP URI, and make its `numbers` match the URI. |
| SIP `408 request timed out` | The trunk matched, but nothing answered. Add the dispatch rule, and check that a worker runs with that `agentName`. |
| The call connects but the agent is silent | The agent joined but made no audio, for example because of a bad LLM or TTS key. Bluejay scores this as no answer. |
| A SIP result stays running with no transcript | The SIP URI has no number. Use `sip:<number>@<host>`. |

## Related

* [Agents API](https://docs.getbluejay.ai/api-reference/endpoint/add-agent.md)
* [Agents MCP tools](https://docs.getbluejay.ai/mcp/testing-tools.md#agents)
* [Logs](https://docs.getbluejay.ai/monitor/logs.md)
* [Traces](https://docs.getbluejay.ai/monitor/traces.md)
* [SIP](https://docs.getbluejay.ai/integrations/sip.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.