The LiveKit SIP inbound transport handles incoming calls routed through LiveKit SIP trunks. A phone call arrives at a DID, LiveKit creates a room, and dispatches VoxCore to join.

​
Connection flow

​
Endpoint

POST /livekit/dispatch

​
Request body

{
  "room_name": "sip-room-abc",
  "caller_number": "+919876543210",
  "dialed_number": "+911234567890",
  "call_id": "optional-uuid"
}
FieldTypeRequiredDescription
room_namestringYesLiveKit room name created by the SIP dispatch rule
caller_numberstringYesCaller’s phone number
dialed_numberstringYesDID that was called — used to look up bot ID
call_idstringNoOptional call ID. Generated if not provided.

​
Response

{
  "status": "accepted",
  "call_id": "uuid-string"
}
The endpoint returns immediately. The pipeline runs in a background task.

​
Audio format

PropertyValue
EncodingLINEAR16 (signed 16-bit PCM)
Sample rate16,000 Hz
ChannelsMono
TransportLiveKit SDK (WebRTC)

​
Bot ID lookup

VoxCore resolves the bot ID from the dialled number by calling VoxBridge: 
GET {voxbridge_url}/sip/lookup?number={dialed_number}
Returns {"bot_id": "..."}. If no bot is mapped to the DID, the call is rejected.

​
Hangup behavior

Bot-initiated: VoxCore calls transport.disconnect(), which leaves the LiveKit room. LiveKit SIP infrastructure tears down the phone call. Customer hangup: LiveKit fires on_participant_left. VoxCore captures disconnected_by = "customer" and winds down the pipeline. Transfer: VoxCore calls the LiveKit SIP transfer API (lkapi.sip.transfer_sip_participant()) to transfer the call to another number.

​
Prerequisites

  • LiveKit server with SIP trunks configured
  • SIP dispatch rule pointing to VoxCore’s /livekit/dispatch endpoint
  • DID → bot ID mapping in VoxBridge
  • Environment variables: LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET