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

# SIP Integration

> Connect enterprise PBX systems to Kallglot via SIP

# SIP Integration

Integrate Kallglot with your existing PBX, contact center, or telephony infrastructure using standard SIP protocols.

## Prerequisites

* A SIP-capable PBX or SBC
* Network connectivity between your infrastructure and **sip.kallglot.com** (follow your TLS/TCP profile and firewall rules)
* A Kallglot API key (for programmatic session workflows)
* Developer Portal SIP settings configured (**Telephony** → **SIP / PBX**)

## Architecture

At a high level, your PBX sends SIP signaling to Kallglot’s SIP endpoint and exchanges audio while Kallglot performs real-time translation and related voice features. Credential checks, optional IP filtering, TLS/SRTP preferences, concurrency limits, and session defaults configured in the **Developer Portal** are applied when SIP calls authenticate.

```mermaid theme={null}
graph LR
    subgraph Your Infrastructure
        PBX[PBX / Contact Center]
        AG[Agent Softphone]
    end

    subgraph Kallglot
        SIP[SIP Gateway]
        K[Kallglot Core]
    end

    subgraph PSTN
        C[Customer]
    end

    C -->|Phone Call| PBX
    PBX -->|SIP INVITE| SIP
    SIP -->|Audio| K
    K -->|Translated Audio| SIP
    SIP -->|SIP| PBX
    PBX --> AG
```

**Two common integration patterns:**

1. **Programmatic sessions** — Your backend calls **`POST https://api.kallglot.com/v1/sessions`** with `routing.type: "sip"` and routes the SIP leg to **`sip:<session_id>@sip.kallglot.com`** (or equivalent as documented for your provisioning flow).
2. **Inbound-first** — Kallglot may authenticate the SIP trunk and associate or create session context consistent with your policy; specifics depend on your routing and numbering plan—validate with **`support@kallglot.com`** if you rely on unattended ingress.

Outbound calling initiated through the API may use SIP trunks your account is provisioned for; availability and configuration are account-specific.

## Setup Steps

### 1. Configure SIP Credentials

Create your developer account at [kallglot.com](https://www.kallglot.com/users/sign_up), then in the Developer Portal:

1. Go to **Telephony** > **SIP / PBX** and click **Configure SIP**
2. Enable SIP access using the toggle
3. Note your automatically generated credentials:
   * **Username**: Your unique SIP username
   * **Domain**: `sip.kallglot.com`
4. Configure security:
   * Add your PBX IP addresses to the **IP Allowlist** (recommended)
   * Click **Regenerate Password** to create new credentials if needed
5. Copy your password when prompted (shown only once)

In the **same** SIP configuration modal, open **Advanced Settings** (collapsible section) to manage TLS/SRTP requirements, session defaults, region, default languages, and concurrent call limits. Those values are saved with your organization and applied when SIP calls are authenticated.

### 2. Create Sessions via API

Before routing a call to Kallglot, create a session:

<Note>
  Kallglot does not currently provide official SDKs. Helper functions like `createKallglotSession(...)` and `endKallglotSession(...)` in this guide are thin wrappers around the HTTP API.
</Note>

```javascript theme={null}
async function createSIPSession(callerInfo) {
  const response = await fetch('https://api.kallglot.com/v1/sessions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.KALLGLOT_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      mode: 'bidirectional_translation',
      source_language: 'de',
      target_language: 'en',
      routing: {
        type: 'sip'
      },
      metadata: {
        caller_id: callerInfo.callerId,
        pbx_call_id: callerInfo.pbxCallId
      }
    })
  });

  const session = await response.json();

  // The SIP URI to route the call to:
  const sipUri = `sip:${session.id}@sip.kallglot.com`;

  return { session, sipUri };
}
```

### 3. Configure Your PBX

Route calls to the Kallglot SIP endpoint. Configuration varies by PBX:

#### Asterisk

```ini theme={null}
; sip.conf
[kallglot]
type=peer
host=sip.kallglot.com
port=5061
transport=tls
username=your_sip_username
secret=your_sip_password
fromdomain=sip.kallglot.com
qualify=yes
disallow=all
allow=opus
allow=g722
allow=g729
allow=ulaw
allow=alaw

; extensions.conf
[translated-calls]
exten => _X.,1,Dial(SIP/kallglot/${SESSION_ID})
```

#### Example: SIP gateway (XML)

The following illustrates a minimal SIP gateway XML snippet—the exact layout depends on your PBX vendor.

```xml theme={null}
<!-- SIP gateway registration block (syntax varies by vendor) -->
<gateway name="kallglot">
  <param name="username" value="your_sip_username"/>
  <param name="password" value="your_sip_password"/>
  <param name="realm" value="sip.kallglot.com"/>
  <param name="proxy" value="sip.kallglot.com"/>
  <param name="register" value="false"/>
  <param name="caller-id-in-from" value="true"/>
</gateway>

<!-- dialplan -->
<extension name="translated_call">
  <condition field="destination_number" expression="^(\d+)$">
    <action application="bridge" data="sofia/gateway/kallglot/${SESSION_ID}@sip.kallglot.com"/>
  </condition>
</extension>
```

#### Cisco CUCM

1. Add a SIP Trunk:
   * Destination Address: `sip.kallglot.com`
   * Port: `5061`
   * Transport Type: TLS
2. Configure SIP Security Profile with digest authentication
3. Create a Route Pattern pointing to the trunk

### 4. Handle Call Flow

Typical call flow with session management:

```javascript theme={null}
// When a call comes in to your PBX
app.post('/pbx/incoming', async (req, res) => {
  const { callId, from, to } = req.body;

  // 1. Create Kallglot session
  const { session, sipUri } = await createSIPSession({
    callerId: from,
    pbxCallId: callId
  });

  // 2. Store mapping
  await db.callMappings.insert({
    pbx_call_id: callId,
    kallglot_session_id: session.id
  });

  // 3. Return SIP URI for PBX to route to
  res.json({
    action: 'route',
    destination: sipUri
  });
});

// When call ends
app.post('/pbx/hangup', async (req, res) => {
  const { callId } = req.body;

  // Find and end Kallglot session
  const mapping = await db.callMappings.findOne({ pbx_call_id: callId });
  if (mapping) {
    await endKallglotSession(mapping.kallglot_session_id);
  }

  res.status(200).send('OK');
});
```

## SIP Configuration Options

### Transport

| Transport | Port | Description                                      |
| --------- | ---- | ------------------------------------------------ |
| **TLS**   | 5061 | Encrypted signaling (recommended for production) |
| **TCP**   | 5060 | Unencrypted, reliable delivery                   |
| **UDP**   | 5060 | Unencrypted, standard SIP                        |

**Default:** TLS is enabled by default. Configure allowed transports in **Advanced Settings**.

### Codecs

Kallglot supports the following audio codecs for SIP calls:

| Codec          | Sample Rate | Bandwidth | Description                  |
| -------------- | ----------- | --------- | ---------------------------- |
| **Opus**       | Variable    | Variable  | Best quality, modern systems |
| **G.722**      | 16 kHz      | 64 kbps   | Wideband, HD voice           |
| **G.729**      | 8 kHz       | 8 kbps    | Narrowband, low bandwidth    |
| **G.711 PCMU** | 8 kHz       | 64 kbps   | µ-law (North America)        |
| **G.711 PCMA** | 8 kHz       | 64 kbps   | A-law (International)        |

**Defaults:** PCMU and PCMA are enabled by default for maximum compatibility.

**Developer Portal:** Under **Configure SIP → Advanced Settings**, select **Allowed audio codecs** (preference order follows the checklist top to bottom when multiple codecs are selected). **Require TLS** / **Require SRTP** complement those lists—for borderline interoperability questions, email **[support@kallglot.com](mailto:support@kallglot.com)**.

### DTMF

DTMF relay behavior depends on the negotiated media path and telephony relay; Kallglot does **not** interpret DTMF digits as session control inputs today.

## Security

### TLS Configuration

Always use TLS for SIP signaling (port 5061) in production. Turn on **Require TLS** in the Developer Portal so connections that do not meet your policy can be rejected:

1. Go to **Telephony** > **SIP / PBX** → **Configure SIP** → **Advanced Settings**
2. Enable **Require TLS**
3. Your PBX must support TLS 1.2 or higher

```bash theme={null}
# Verify TLS connectivity
openssl s_client -connect sip.kallglot.com:5061 -tls1_2
```

### IP Allowlisting

Restrict which IPs can authenticate as your SIP trunk:

1. Go to **Developer Portal** > **Telephony** > **SIP / PBX**
2. Click **Configure SIP**
3. Add your PBX egress IPs to the **IP Allowlist** (one per line; CIDR supported)

**Behavior:** If the allowlist is **empty**, Kallglot does **not** apply source-IP filtering (authenticate attempts still require valid credentials). After you add **one or more** entries, only those networks are accepted. For production, populate the allowlist.

### SRTP for Media

Require encrypted RTP when your policy demands it:

1. Go to **Developer Portal** > **Telephony** > **SIP / PBX** → **Configure SIP** → **Advanced Settings**
2. Enable **Require SRTP** — connections that do not complete SRTP negotiation where required may be rejected (your PBX must negotiate SRTP successfully when this is on)
3. Align crypto suites and RTP/SRTP profiles with your PBX vendor’s documentation; if media fails to establish, collect SIP traces from **your** environment and work with **[support@kallglot.com](mailto:support@kallglot.com)** alongside your telephony team.

## Advanced Scenarios

<Note>
  The following advanced features are on our roadmap. Contact [support@kallglot.com](mailto:support@kallglot.com) for early access or to discuss your requirements.
</Note>

### SIP REFER for Transfers (Coming Soon)

Call transfer support via SIP REFER is planned for a future release. Currently, to transfer a call:

1. End the current Kallglot session
2. Create a new session for the transfer target
3. Route the call to the new session URI

### Multiple Participants (Coming Soon)

Conference call translation support is planned. Currently, Kallglot supports two-party calls (agent + customer).

### Regional Processing

Configure where your calls are processed in the Developer Portal:

1. Go to **Telephony** > **SIP / PBX** > **Configure SIP**
2. Under **Session Defaults**, select your **Region**:
   * **Europe (EU)** - GDPR-compliant processing
   * **US** - Americas
   * **Asia-Pacific (AP)** - APAC region

All regions use the same SIP endpoint: `sip.kallglot.com`

## Troubleshooting

### Registration Issues

```bash theme={null}
# Test SIP connectivity
sipsak -s sip:test@sip.kallglot.com -v

# Check firewall allows SIP traffic
nc -zv sip.kallglot.com 5061
```

### No Audio

1. Check NAT configuration - ensure RTP ports are open
2. Verify SRTP settings match on both sides
3. Check codec negotiation in SIP logs

### Call Quality Issues

1. Monitor jitter and packet loss
2. Check network latency to Kallglot
3. Ensure your region setting matches your network topology

### Debugging

For SIP debugging, check:

1. **Developer Portal** > **API Logs** — recent integration activity (for example webhook delivery attempts). It is **not** a full SIP signaling trace viewer.
2. **Your PBX / SBC logs** — SIP dialogs, SDP, RTP/SRTP negotiation.
3. **Kallglot support** — for authentication or routing issues that need correlation across both environments after you share traces from your side.

```bash theme={null}
# Test SIP connectivity from your PBX
sipsak -s sip:test@sip.kallglot.com -v

# Verify TLS handshake
openssl s_client -connect sip.kallglot.com:5061
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use TLS and SRTP">
    Always encrypt signaling (TLS) and media (SRTP) for production deployments.
  </Accordion>

  <Accordion title="Implement proper failover">
    Configure your PBX with failover to handle Kallglot outages gracefully.
  </Accordion>

  <Accordion title="Monitor call quality">
    Set up monitoring for RTP quality metrics (MOS, jitter, packet loss).
  </Accordion>

  <Accordion title="Pre-create sessions">
    Create sessions before calls are established to reduce setup latency.
  </Accordion>
</AccordionGroup>

## Security Hardening

### Production Security Checklist

<Warning>
  Complete these security measures before deploying SIP integration to production.
</Warning>

| Requirement         | Description                                                                           | Priority                            |
| ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------- |
| TLS 1.2+            | Use port 5061 with TLS for SIP signaling aligned with policy                          | Required (production expectation)   |
| IP Allowlist        | Enter allowed source IPs in **Configure SIP** (empty allowlist = **no** IP filtering) | Strongly recommended for production |
| Strong Credentials  | Use generated credentials, never default passwords                                    | Required                            |
| Credential Rotation | Rotate SIP credentials every 90 days                                                  | Recommended                         |
| SRTP                | Enable SRTP for encrypted media streams                                               | Recommended                         |
| Private Network     | Use VPN or private connectivity where possible                                        | Recommended                         |

### Credential Security

<Tip>
  SIP credentials should be treated as sensitive secrets. Store them securely and never commit them to version control.
</Tip>

```javascript theme={null}
// Good: Load credentials from environment
const sipConfig = {
  username: process.env.KALLGLOT_SIP_USERNAME,
  password: process.env.KALLGLOT_SIP_PASSWORD,
  domain: 'sip.kallglot.com'
};

// Bad: Never hardcode credentials
// const sipConfig = {
//   username: 'sip_abc123',
//   password: 'hardcoded-password'  // SECURITY RISK
// };
```

### Network Security

Configure your firewall to allow only the required traffic:

| Protocol | Port        | Direction | Purpose                                               |
| -------- | ----------- | --------- | ----------------------------------------------------- |
| TCP      | 5061        | Outbound  | SIP TLS signaling                                     |
| UDP      | 20000-20100 | Both      | RTP media (example sizing; tune for your concurrency) |

Block traffic you do not need; widen media port ranges as your concurrent call volume grows.

## Contracts, compliance, and data handling

Legal terms, questionnaires, DPIAs, and certifications (**SOC 2, GDPR, HIPAA**, etc.) are covered by **your agreement** and collateral from Kallglot—not this SIP how-to.

For SIP specifically: SIP credentials appear **once** in the portal after create/rotate—store them like any production secret.

**Processing region** (`eu`, `us`, `ap` in SIP **Session defaults**) selects the preference shown in **Developer Portal**; confirm suitability with your legal team if you have residency requirements—**[support@kallglot.com](mailto:support@kallglot.com)** for paperwork.

## Policy Configuration

### Session Defaults

Configurable in **Telephony** > **SIP / PBX** → **Configure SIP** → **Advanced Settings**:

| Setting                 | Options                   | Default                   |
| ----------------------- | ------------------------- | ------------------------- |
| Session Mode            | Bidirectional Translation | Bidirectional Translation |
| Region                  | Europe (EU)               | EU                        |
| Default Source Language | Language code or `auto`   | `auto`                    |
| Default Target Language | Language code or `auto`   | `auto`                    |
| Max Concurrent Calls    | 1–100                     | 5                         |

> **Note:** Additional regions (US, Asia Pacific) coming soon.

Concurrency limits are part of your policy; treat them as operational and contractual limits for your plan.

### Transport and media policy flags

**Require TLS** and **Require SRTP** in **Advanced Settings** reinforce transport security alongside the **Allowed signaling transports** and **Allowed audio codecs** sections. Escalations or exotic PBX interoperability needs → **[support@kallglot.com](mailto:support@kallglot.com)**.

## Quick Reference

```
Server:     sip.kallglot.com
TLS Port:   5061
UDP/TCP:    5060
Codecs:     Opus, G.722, G.729, PCMU, PCMA
Transport:  TLS (recommended)
```

## Operations checklist

Ship with basic observability:

* **Invite / setup latency** — alert if PSTN callers hear long silence before audio.
* **Your PBX counters** — failed registrations, `401`/`403`, RTP timeouts vs baseline.
* **Concurrent calls vs portal cap** — avoid hitting organizational limits mid-day.
* **Developer Portal API Logs** — correlates webhook/API failures; deeper SIP traces live on **your SBC**.

Escalations with PCAP from your edge + timestamps → **[support@kallglot.com](mailto:support@kallglot.com)**.