Sessions vs Calls

You always begin with a Session (POST /v1/sessions): it returns sess_…, stream URL/token, and the resolved routing that lets Kallglot process audio for translation, transcript, recordings, etc.

What is a Session?

A session is simply the identifier you correlate with every API call thereafter (GET session, transcripts, recordings, wss stream, webhook handlers). Plug in telephony whichever way fits your deployment:

Path	Typical next step
Programmatic SIP	Publish `sip:{session_id}@sip.kallglot.com` from your PBX
Vendor trunk	Tie numbers or `routing.connection_id` per Choose telephony integration
Raw streaming	Point your client at the `stream.url` plus token

What is a Call?

A Call is a telephony connection managed by a provider (Twilio, Telnyx, or SIP). Calls handle:

Phone number dialing
PSTN connectivity
Call routing
Telephony features (hold, transfer, etc.)

A single session can involve multiple calls:

Incoming call from a customer
Outgoing call to an agent
Conference call with multiple participants

Practical flow

Call POST /v1/sessions with mode, optional languages, routing (or defaults from the Developer Portal).
Send media on the stream WebSocket (audio.input), or attach telephony streams per vendor guide (/guides/twilio, /guides/telnyx, /guides/sip).
Tear down with POST /v1/sessions/{id}/end once your call leg finishes.

Example: Inbound call (pseudo-code)

When your HTTP webhook fires for inbound telephony:

// 1. Webhook receives payload from Twilio (example keys)
app.post('/twilio/incoming', async (req, res) => {
  const { CallSid, From, To } = req.body;

  // 2. Create session: telephony uses `routing` (E.164 of your Kallglot-managed number = the called number To)
  const session = await createKallglotSession({
    mode: 'bidirectional_translation',
    source_language: 'de',
    target_language: 'en',
    routing: {
      phone_number: To
    },
    metadata: {
      twilio_call_sid: CallSid,
      from_number: From,
      to_number: To
    }
  });

  // 3. Connect the call to Kallglot's media stream
  const response = new twiml.VoiceResponse();
  response.connect().stream({
    url: session.stream.url,
    parameters: { token: session.stream.token }
  });

  res.type('text/xml').send(response.toString());
});

Example: WebRTC Session

// 1. Create session for browser-based voice
const session = await createKallglotSession({
  mode: 'ai_agent',
  source_language: 'en',
  target_language: 'en'
  // No `routing` — browser sends audio on stream WebSocket only
});

// 2. Connect from browser
const ws = new WebSocket(`${session.stream.url}?token=${session.stream.token}`);

// 3. Stream microphone audio
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
// ... stream audio to WebSocket

Billing Model

Billing is based on session duration, not call duration:

What’s Billed	Description
Active session time	Time from first audio received to session end
Translation minutes	Minutes where translation was active
AI agent minutes	Minutes where AI agent was processing

This means:

A 5-minute call with a 5-minute session = 5 minutes billed
A 5-minute call with a 10-minute session (including hold) = 10 minutes billed
Two 3-minute calls in one session = 6 minutes billed total

Session Lifecycle

Status Descriptions

Status	Description
`created`	Session created, waiting for audio connection
`connecting`	Audio source connecting
`active`	Processing audio in real-time
`ending`	Finalizing recording and transcript
`ended`	Session complete, resources available

Multiple Participants

A single session can handle multiple audio sources:

// Conference session with multiple participants
const session = await createKallglotSession({
  mode: 'bidirectional_translation',
  source_language: 'de',
  target_language: 'en',
  participants: [
    { type: 'agent', language: 'en' },
    { type: 'customer', language: 'de' }
  ]
});

// Both participants connect to the same session
// Agent connects via WebRTC
// Customer connects via phone call

Best Practices

Create sessions early

Create the session before the call connects. This ensures the processing pipeline is ready when audio starts flowing.

End sessions promptly

End sessions as soon as the conversation is complete. This stops billing and triggers recording/transcript finalization.

Use session metadata

Attach custom metadata to sessions for easy correlation with your CRM, ticketing, or routing systems:

{
  "metadata": {
    "customer_id": "cust_123",
    "ticket_id": "ticket_456",
    "agent_id": "agent_789"
  }
}

Handle session reconnection

If a call disconnects but may reconnect, keep the session active. You can reconnect new audio to the same session within 5 minutes.

​Sessions vs Calls

​What is a Session?

​What is a Call?

​Practical flow

​Example: Inbound call (pseudo-code)

​Example: WebRTC Session

​Billing Model

​Session Lifecycle

​Status Descriptions

​Multiple Participants

​Best Practices