Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.kallglot.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Quick Start Guide

This guide walks you through creating a real-time voice translation session using the Kallglot API.

​
Choose Your Telephony Path

Before creating a session, decide how the call will reach Kallglot:
  1. Kallglot-managed number: use an active number provisioned by Kallglot
  2. External provider connection: use your own Twilio or Telnyx account via routing.connection_id
  3. SIP / PBX: create the session first, then route your PBX call to sip:<session_id>@sip.kallglot.com
See Choose your telephony integration for the routing guide.

​
Prerequisites

1

Get an API Key

Create your developer account at kallglot.com, then generate an API key in the Developer Portal.
2

Activate Billing

Make sure the organization has an active subscription and available API credits before sending production API requests.

​
Base URLs

EnvironmentBase URL
REST APIhttps://api.kallglot.com/v1
WebSocketwss://api.kallglot.com/v1

​
Create a Session

A session establishes a real-time voice connection with Kallglot. The example below uses a Kallglot-managed number because it is the fastest setup path.
Request shape: use routing, not provider. For POST /v1/sessions, telephony selection belongs under routing (phone_number, connection_id, or SIP fields per Create Session). The session response may include a string field provider (for example "twilio") describing which carrier was resolved—that is not something you send as provider: { "type": "twilio", ... } in the request body. Older samples that used a nested provider object for outbound creation are not the public contract; integrations should always follow routing.
Language auto-detection: source_language and target_language are optional. When omitted, Kallglot infers each speaker’s language from the audio. Set them explicitly when you already know the pair for more predictable startup behavior.
curl -X POST https://api.kallglot.com/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "mode": "bidirectional_translation",
    "source_language": "de",
    "target_language": "en",
    "routing": {
      "phone_number": "+19788006140"
    },
    "metadata": {
      "external_call_id": "call_abc123"
    }
  }'

​
Response

{
  "id": "sess_01HXYZ",
  "object": "session",
  "status": "created",
  "mode": "bidirectional_translation",
  "source_language": "de",
  "target_language": "en",
  "stream": {
    "url": "wss://api.kallglot.com/v1/sessions/sess_01HXYZ/connect",
    "token": "kst_live_xxxxxxxx",
    "expires_at": "2026-03-10T12:00:00Z"
  },
  "call": null,
  "created_at": "2026-03-10T11:55:00Z"
}
Successful POST /v1/sessions requests currently consume 1 API credit. Check X-API-Credits-Remaining and X-API-Credits-Used in the response headers to track usage. If the organization subscription is inactive, the API returns 403 organization_inactive. If credits are exhausted, it returns 402 insufficient_api_credits.

​
Connect to the WebSocket

The session response includes a WebSocket URL for real-time streaming. The token expires in 5 minutes, so connect promptly. Once connected, token expiry does NOT terminate the stream. 
async function connectToSession(sessionId, streamToken) {
  const ws = new WebSocket(
    `wss://api.kallglot.com/v1/sessions/${sessionId}/connect?token=${streamToken}`
  );

  ws.onopen = () => {
    console.log('Connected to Kallglot stream');
  };

  ws.onmessage = (event) => {
    const data = JSON.parse(event.data);

    switch (data.type) {
      case 'session.ready':
        console.log('Session ready');
        break;

      case 'transcript.partial':
        console.log(`[Partial] ${data.speaker}: ${data.text}`);
        break;

      case 'transcript.final':
        console.log(`[${data.speaker}] ${data.text}`);
        if (data.translation) {
          console.log(`  → ${data.translation.text}`);
        }
        break;

      case 'audio.output':
        // Play translated audio
        playAudio(data.audio.payload);
        break;

      case 'session.ended':
        console.log('Session ended:', data.reason);
        ws.close();
        break;

      case 'error':
        console.error(`Error [${data.code}]: ${data.message}`);
        break;
    }
  };

  return ws;
}

// Send audio to the stream
function sendAudio(ws, audioBase64, speaker) {
  ws.send(JSON.stringify({
    type: 'audio.input',
    sequence: Date.now(),
    timestamp_ms: Date.now(),
    speaker: speaker,
    audio: {
      encoding: 'mulaw',
      sample_rate_hz: 8000,
      payload: audioBase64
    }
  }));
}

​
End the Session

When the conversation is complete, end the session to stop billing: 
curl -X POST https://api.kallglot.com/v1/sessions/sess_01HXYZ/end \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Idempotency-Key: $(uuidgen)"

​
Response

{
  "id": "sess_01HXYZ",
  "object": "session",
  "status": "ended",
  "duration_seconds": 312,
  "ended_at": "2026-03-10T12:05:44Z"
}

​
Retrieve the Transcript

After the session ends, retrieve the complete transcript: 
curl https://api.kallglot.com/v1/sessions/sess_01HXYZ/transcript \
  -H "Authorization: Bearer sk_live_your_api_key"

​
Response

{
  "id": "trn_01HXYZ",
  "object": "transcript",
  "session_id": "sess_01HXYZ",
  "status": "completed",
  "turns": [
    {
      "sequence": 1,
      "speaker": "customer",
      "language": "de",
      "text": "Ich möchte meine Bestellung ändern",
      "translation": {
        "language": "en",
        "text": "I want to change my order"
      },
      "confidence": 0.96,
      "timestamp": "2026-03-10T11:58:02Z"
    }
  ],
  "metadata": {
    "total_turns": 14,
    "duration_seconds": 312
  }
}

​
Next Steps

Session Modes

Learn about different translation modes

Webhooks

Set up real-time event notifications

AI Agents

Deploy intelligent voice agents

Error Handling

Handle errors gracefully