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

# Mic Sessions

> Start a browser-audio session to talk to an agent in real time (for testing and demos).

Mic sessions let you talk to an agent directly from a web browser using
your microphone — no phone number required. ThunderPhone creates a
LiveKit room and returns a join token; your front-end uses the
LiveKit Web SDK to publish audio. This endpoint is typically used for
agent iteration and demos.

## Endpoint

| Method | Path              | Description                           |
| ------ | ----------------- | ------------------------------------- |
| `POST` | `/v1/mic-session` | Create a mic session against an agent |

## Create a session

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thunderphone.com/v1/mic-session \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"agent_id": 12}'
  ```

  ```python Python theme={null}
  session = requests.post(
      "https://api.thunderphone.com/v1/mic-session",
      headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
      json={"agent_id": 12},
  ).json()
  ```

  ```javascript Node.js theme={null}
  const session = await fetch("https://api.thunderphone.com/v1/mic-session", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: 12 }),
  }).then((r) => r.json());
  ```
</CodeGroup>

### Request fields

| Field      | Type    | Required | Description          |
| ---------- | ------- | -------- | -------------------- |
| `agent_id` | integer | yes      | Agent id in this org |

### Response

```json theme={null}
{
  "call_id": 987654321,
  "token": "<livekit-jwt>",
  "room_name": "mic-987654321",
  "server_url": "wss://livekit.thunderphone.com"
}
```

| Field        | Type    | Description                                                                                   |
| ------------ | ------- | --------------------------------------------------------------------------------------------- |
| `call_id`    | integer | Call id — the session appears in [Call history](/api-reference/calls) with `direction="test"` |
| `token`      | string  | Short-lived LiveKit JWT                                                                       |
| `room_name`  | string  | LiveKit room                                                                                  |
| `server_url` | string  | LiveKit WebSocket URL — pass to the Web SDK                                                   |

### Connecting from the browser

Use the LiveKit Web SDK to join the room with the returned token. The
agent joins the room from Core's side and you publish your microphone
as the local participant.

```javascript theme={null}
import { Room, RoomEvent } from "livekit-client";

const room = new Room();
await room.connect(session.server_url, session.token);
await room.localParticipant.setMicrophoneEnabled(true);

room.on(RoomEvent.TrackSubscribed, (track) => {
  if (track.kind === "audio") track.attach(document.body);
});
```

### Errors

| Status | Condition                    |
| ------ | ---------------------------- |
| `400`  | `agent_id is required`       |
| `402`  | Insufficient balance         |
| `404`  | Agent not found              |
| `502`  | LiveKit room creation failed |

<Note>
  Mic sessions count as calls for billing purposes. The session is
  billed as a regular voice call using the agent's `product` tier.
</Note>

***

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Configure the agent you'll talk to.
  </Card>

  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Inspect mic-session call logs and transcripts.
  </Card>

  <Card title="Web Widget" icon="window-maximize" href="/widget/overview">
    Embed a production-ready mic widget on your own site.
  </Card>
</CardGroup>