Skip to main content
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

MethodPathDescription
POST/v1/mic-sessionCreate 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

FieldTypeRequiredDescription
agent_idintegeryesAgent id in this org

​
Response

{
  "call_id": 987654321,
  "token": "<livekit-jwt>",
  "room_name": "mic-987654321",
  "server_url": "wss://livekit.thunderphone.com"
}
FieldTypeDescription
call_idintegerCall id — the session appears in Call history with direction="mic"
tokenstringShort-lived LiveKit JWT
room_namestringLiveKit room
server_urlstringLiveKit 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

StatusCondition
400agent_id is required
402Insufficient balance
404Agent not found
502LiveKit room creation failed
Mic sessions count as calls for billing purposes. The session is billed as a regular voice call using the agent’s product tier.

Agents

Configure the agent you’ll talk to.

Calls

Inspect mic-session call logs and transcripts.

Web Widget

Embed a production-ready mic widget on your own site.