Skip to main content
Telepath

POST Create Trunk

Create a new SIP trunk (connection).

endpoint 
POST https://api.telepathvoice.com/v1/trunks

Overview

Create a new SIP trunk that links an AI agent to a SIP identity. Each trunk contains the credentials your SIP carrier uses to route calls and the provider configuration Telepath uses to reach your AI agent.

Request

Body Parameters

name string required Friendly name for this trunk (e.g., "Production OpenAI Agent").
ai_provider string required AI provider type: openai, elevenlabs, or custom.
sip_username string required Unique SIP username. Alphanumeric characters and hyphens only. Must be unique across your account.
sip_password string required SIP authentication password. Minimum 8 characters.
openai_api_key string OpenAI API key. Required when ai_provider is openai.
elevenlabs_api_key string ElevenLabs API key. Required when ai_provider is elevenlabs.
elevenlabs_agent_id string ElevenLabs Conversational AI agent ID. Required when ai_provider is elevenlabs.
custom_endpoint string WebSocket endpoint URL (wss://) for your custom AI agent. Required when ai_provider is custom.
system_prompt string Optional system prompt sent to the AI agent at the start of each call.

Example Request

bash 
curl -X POST https://api.telepathvoice.com/v1/trunks \
  -H "Authorization: Bearer sk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production OpenAI Agent",
    "ai_provider": "openai",
    "sip_username": "agent-prod-01",
    "sip_password": "s3cur3P@ssw0rd!",
    "openai_api_key": "sk-openai-abc123...",
    "system_prompt": "You are a helpful customer service agent."
  }'

Python Example

python 
import requests

API_KEY = "sk_live_abc123def456..."
BASE_URL = "https://api.telepathvoice.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "name": "Production OpenAI Agent",
    "ai_provider": "openai",
    "sip_username": "agent-prod-01",
    "sip_password": "s3cur3P@ssw0rd!",
    "openai_api_key": "sk-openai-abc123...",
    "system_prompt": "You are a helpful customer service agent."
}

response = requests.post(f"{BASE_URL}/trunks", headers=headers, json=payload)
response.raise_for_status()
trunk = response.json()
print(f"Created trunk: {trunk['id']}")
print(f"SIP endpoint: {trunk['sip_endpoint']}")

Response

Response Fields

id string Unique trunk identifier (e.g., conn_abc123xyz).
name string Friendly name as provided.
status string Initial status, typically active.
ai_provider string The AI provider type as provided.
sip_username string The SIP username as provided.
sip_endpoint string The full SIP endpoint to configure in your carrier (e.g., [email protected]).
created_at string ISO 8601 timestamp of creation.

Example Response

json 
{
  "id": "conn_abc123xyz",
  "name": "Production OpenAI Agent",
  "status": "active",
  "ai_provider": "openai",
  "sip_username": "agent-prod-01",
  "sip_endpoint": "[email protected]",
  "created_at": "2024-03-10T12:00:00Z"
}

Error Responses

Missing Required Fields (400)

json 
{
  "error": {
    "code": "missing_required_field",
    "message": "sip_password is required",
    "status": 400
  }
}

Invalid SIP Username (400)

json 
{
  "error": {
    "code": "invalid_sip_username",
    "message": "sip_username may only contain alphanumeric characters and hyphens",
    "status": 400
  }
}

SIP Username Already Exists (409)

json 
{
  "error": {
    "code": "conflict",
    "message": "A trunk with sip_username 'agent-prod-01' already exists",
    "status": 409
  }
}

Invalid API Credentials (401)

json 
{
  "error": {
    "code": "invalid_provider_credentials",
    "message": "The provided openai_api_key could not be validated",
    "status": 401
  }
}

Creating Different Provider Types

OpenAI Realtime

json 
{
  "name": "OpenAI Realtime Agent",
  "ai_provider": "openai",
  "sip_username": "oai-agent-01",
  "sip_password": "s3cur3P@ssw0rd!",
  "openai_api_key": "sk-openai-abc123...",
  "system_prompt": "You are a helpful assistant."
}

ElevenLabs Conversational AI

json 
{
  "name": "ElevenLabs Sales Agent",
  "ai_provider": "elevenlabs",
  "sip_username": "el-sales-01",
  "sip_password": "s3cur3P@ssw0rd!",
  "elevenlabs_api_key": "el_api_abc123...",
  "elevenlabs_agent_id": "agent_xyz789..."
}

Custom WebSocket Agent

json 
{
  "name": "Custom WebSocket Agent",
  "ai_provider": "custom",
  "sip_username": "custom-agent-01",
  "sip_password": "s3cur3P@ssw0rd!",
  "custom_endpoint": "wss://your-agent.example.com/voice"
}

Usage Examples

Create with Error Handling

python 
import requests

def create_trunk(api_key, name, ai_provider, sip_username, sip_password, **kwargs):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    payload = {
        "name": name,
        "ai_provider": ai_provider,
        "sip_username": sip_username,
        "sip_password": sip_password,
        **kwargs
    }
    r = requests.post(
        "https://api.telepathvoice.com/v1/trunks",
        headers=headers,
        json=payload
    )
    if r.status_code == 409:
        raise ValueError(f"SIP username '{sip_username}' already exists")
    if r.status_code == 400:
        raise ValueError(r.json()["error"]["message"])
    r.raise_for_status()
    return r.json()

Batch Create Trunks

python 
configs = [
    {"name": "Agent US-East", "sip_username": "agent-us-east", "ai_provider": "openai"},
    {"name": "Agent US-West", "sip_username": "agent-us-west", "ai_provider": "openai"},
    {"name": "Agent EU",      "sip_username": "agent-eu",      "ai_provider": "openai"},
]

created = []
for cfg in configs:
    trunk = create_trunk(
        api_key=API_KEY,
        sip_password="s3cur3P@ssw0rd!",
        openai_api_key=OPENAI_KEY,
        **cfg
    )
    created.append(trunk)
    print(f"Created {trunk['name']}: {trunk['sip_endpoint']}")

See Also