Skip to main content

​
Quick Start Guide

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

​
Prerequisites

1

Get an API Key

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

​
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. Here’s how to create one: 
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",
    "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"
}

​
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 'session.error':
        console.error('Error:', data.error.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