> ## 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.

# Sessions vs Calls

> Understanding the difference between sessions and calls in Kallglot

# 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](/guides/choose-telephony-integration) |
| Raw streaming    | Point your client at the `stream.url` plus token                                                                |

```mermaid theme={null}
graph TB
    subgraph "Session Layer"
        S[Kallglot Session]
    end

    subgraph "Provider Layer"
        T[Twilio Call]
        X[Telnyx Call]
        W[WebRTC]
        P[SIP Endpoint]
    end

    T --> S
    X --> S
    W --> S
    P --> S
```

## 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

1. Call **`POST /v1/sessions`** with `mode`, optional languages, routing (or defaults from the Developer Portal).
2. Send media on the **`stream`** WebSocket (`audio.input`), or attach telephony streams per vendor guide (`/guides/twilio`, `/guides/telnyx`, `/guides/sip`).
3. 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:

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```mermaid theme={null}
stateDiagram-v2
    [*] --> Created: POST /sessions
    Created --> Connecting: Audio connected
    Connecting --> Active: Stream established
    Active --> Active: Audio processing
    Active --> Ending: POST /sessions/:id/end
    Ending --> Ended: Cleanup complete
    Ended --> [*]
```

### 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:

```javascript theme={null}
// 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

<AccordionGroup>
  <Accordion title="Create sessions early">
    Create the session before the call connects. This ensures the processing pipeline is ready when audio starts flowing.
  </Accordion>

  <Accordion title="End sessions promptly">
    End sessions as soon as the conversation is complete. This stops billing and triggers recording/transcript finalization.
  </Accordion>

  <Accordion title="Use session metadata">
    Attach custom metadata to sessions for easy correlation with your CRM, ticketing, or routing systems:

    ```json theme={null}
    {
      "metadata": {
        "customer_id": "cust_123",
        "ticket_id": "ticket_456",
        "agent_id": "agent_789"
      }
    }
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>