View as Markdown
Open in
Mic Sessions
Start browser-audio sessions that let you talk to an agent in real time from a web page — the same path the dashboard uses for agent testing and live 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
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}'session = requests.post(
"https://api.thunderphone.com/v1/mic-session",
headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
json={"agent_id": 12},
).json()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());Request fields
| Field | Type | Required | Description |
|---|---|---|---|
agent_id | integer | yes | Agent id in this org |
Response
{
"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 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.
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 |
429 | concurrent_call_limit_reached: the organization is at its concurrent-call limit; retry after Retry-After seconds |
502 | LiveKit room creation failed |