Telepath Documentation

1. Introduction

Telepath is the infrastructure layer for Voice AI. We provide the low-latency "rails" that connect your telephony carriers (Twilio, Telnyx, etc.) to your AI models (OpenAI, ElevenLabs, Retell, Vapi).

We operate on a "Glass-Box" philosophy:

• BYOC (Bring Your Own Carrier): You pay your carrier directly for SIP trunking.
• BYOK (Bring Your Own Keys): You pay your AI provider directly for tokens.
• Infrastructure Only: Telepath provides the bridge and observability layer.

Signal Flow

Telepath sits between your carrier and your AI provider. We handle:

• SIP termination and media handling
• Audio transcoding (G.711 ↔ PCM)
• WebSocket bridging to AI providers
• Real-time telemetry and observability

2. Quick Start

Prerequisites

• A SIP Trunking provider (Twilio, Telnyx, Vonage, Bandwidth, SignalWire, Plivo, etc.)
• An API Key from an AI provider (OpenAI, ElevenLabs, Retell, or Vapi)

Step 1: Create a Connection

1. Log in to the Telepath Dashboard
2. Click "Create Connection"
3. Enter a SIP Username (e.g., my-sales-bot)
4. Select your AI Provider and enter your credentials
5. Click Create

Step 2: Point Your Carrier to Telepath

Copy the Integration URI from your connection:

sip:[email protected]

Paste this into your carrier's Origination SIP URI or SIP Server field.

Step 3: Make a Test Call

Call your carrier's phone number. The call will route through Telepath to your AI agent. View the results in the Dashboard Logs.

3. Creating a Connection

A Connection (also called a Trunk) represents a single SIP endpoint that bridges to an AI provider.

Required Fields

Optional Fields

Integration URI

Once created, your connection is accessible at:

sip:{sip_username}@sip.telepath.live

4. AI Voice Agent Provider

Telepath supports multiple AI providers out of the box. Select your provider in the Create Connection dialog and enter the required credentials.

5. Carrier Configuration

Telepath is carrier-agnostic. Any SIP trunking provider that can send a standard SIP INVITE will work.

Setup Instructions

1. Create your Connection in Telepath and copy the SIP URI
2. Log in to your carrier's portal
3. Paste your Telepath URI: {username}@sip.telepath.live into the SIP Server/Origination URI field.

Supported Carriers

Click below to jump to official documentation for your carrier.

6. Dashboard

The Telepath Dashboard is available at dashboard.telepath.live.

Dashboard Pages

Call Logs

The Logs page updates in real-time as calls start and end. Each call record includes:

• Call ID: Unique identifier (copyable for API use)
• Status: completed or failed (failed shown in red)
• Duration: Call length in seconds
• Turn Count: Number of conversation turns
• AI Latency: Average AI response time (ms)
• Blame: Attribution for any issues
• Disconnect Reason: SIP code or internal status

7. Webhooks

Telepath sends an HTTP POST to your configured webhook URL when each call ends.

Configuration

Set the Status Webhook URL and optional Webhook Secret in the Create/Edit Connection dialog.

Behavior

• Trigger: Fires when call ends (normal hangup or failure)
• Retry Policy: None (fire-and-forget)
• Timeout: 10 seconds
• Security: If a secret is set, it's sent in the X-Telepath-Secret header

Payload Format

{
  "sip_call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-01-15T10:30:00Z",
  "formatted_time": "10:30 AM",
  "direction": "inbound",
  "from_number": "+15550100",
  "to_number": "+15550200",
  "carrier": "twilio",
  "status": "completed",
  "disconnect_reason": "BYE",
  "duration": 45.2,
  "turn_count": 8,
  "blame": "",
  "ai_latency": 450,
  "jitter_max": 12.5,
  "packet_loss": 0.01
}

Payload Fields

Blame Values

8. API Reference

The Telepath API allows you to programmatically access call data and manage connections.

Base URL

https://api.telepath.live/v1

Authentication

All API requests require a Bearer token. Find your API key in Developer Settings.

Authorization: Bearer sk_live_...

Endpoints

List Calls

GET /v1/calls

Returns a paginated list of call records.

Example:

curl -X GET "https://api.telepath.live/v1/calls?limit=10&page=1" \
  -H "Authorization: Bearer sk_live_..."

Get Single Call

GET /v1/calls/{call_id}

Returns the same payload as the webhook for a specific call.

Example:

curl -X GET "https://api.telepath.live/v1/calls/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer sk_live_..."

List Connections

GET /v1/trunks

Returns all connections (trunks) for the authenticated user.

Create Connection

POST /v1/trunks

Request Body:

{
  "sip_username": "my-bot",
  "provider": "openai",
  "provider_credential": "sk-...",,
  "provider_config": {
    "model": "gpt-4o-realtime-preview"
  },
  "webhook_url": "https://api.yourapp.com/webhooks/telepath",
  "webhook_secret": "your-secret"
}

Update Connection

PATCH /v1/trunks/{id}

Partial updates supported. Only send the fields you want to change.

{
  "webhook_url": "https://api.yourapp.com/webhooks/new-endpoint"
}

Delete Connection

DELETE /v1/trunks/{id}

Rotate API Key

POST /v1/users/rotate-key

Rotates the API key for the authenticated user. Returns the new key.

Response:

{
  "new_api_key": "sk_live_new..."
}

9. Codec & VAD

Supported Codecs

Telepath supports standard telephony codecs:

• G.711 μ-law (PCMU) - North America standard
• G.711 A-law (PCMA) - International standard

Telepath handles transcoding to 16-bit PCM for the AI provider. Your carrier doesn't need to do anything special.

Voice Activity Detection (VAD)

VAD is handled by the AI provider, not Telepath:

10. Security

Telepath is designed for security-conscious deployments.

return request.headers.get("X-Telepath-Secret") == secret

11. Troubleshooting

Disconnect Reason Values

The disconnect_reason field contains either a SIP code or a Telepath internal status:

SIP Codes

For a complete list of SIP codes, see Wikipedia: SIP Response Codes.

Telepath Internal Statuses