Skip to main content
PUT
/
v1
/
agents
/
{agentId}
/
sip
/
registration
curl -X PUT https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000/sip/registration \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sipDomain": "sip.example.com",
    "username": "1001",
    "password": "secure_password",
    "proxy": "proxy.example.com",
    "port": 5060,
    "transport": "udp"
  }'

{
  "success": true,
  "data": {
    "sipDomain": "sip.example.com",
    "username": "1001",
    "password": "secure_password",
    "proxy": "proxy.example.com",
    "port": 5060,
    "transport": "udp",
    "subscribe": false,
    "authUsername": null,
    "did": null,
    "sipRoutingHeaderXDestUser": null,
    "registrationEnabled": true,
    "extension": "1001"
  }
}

​
Path Parameters

​
agentId
string
required
The unique identifier of the agent (UUID format)

​
Request Body

​
Required Fields

​
sipDomain
string
required
SIP domain for the registration.Example: sip.example.com
​
username
string
required
SIP username for authentication. Also used as the extension number.Example: 1001
​
password
string
required
SIP password for authentication.

​
Optional Fields

​
proxy
string
SIP proxy server address. Use this if your SIP provider requires routing through a proxy.Example: proxy.sip.example.com
​
port
integer
default:"5060"
SIP port number.Common values:
  • 5060 - Standard SIP (UDP/TCP)
  • 5061 - SIP over TLS
​
transport
string
default:"udp"
Transport protocol.Supported values:
  • udp - User Datagram Protocol (most common)
  • tcp - Transmission Control Protocol
  • tls - Transport Layer Security (encrypted)
​
subscribe
boolean
default:"false"
Enable SIP SUBSCRIBE for presence/BLF (Busy Lamp Field).Set to true if you need presence information from the PBX.
​
authUsername
string
Optional authentication username, if different from the SIP username.Some providers use a separate auth identity. If not set, username is used for authentication.
​
did
string
DID (Direct Inward Dialing) number to send in the SIP INVITE.Example: +15551234567
​
sipRoutingHeaderXDestUser
string
Optional value sent in the SIP X-Dest-User routing header. Used by upstream providers/PBXs that route calls based on a destination user identifier rather than the SIP username.Sent on the wire only when set. Empty strings are treated as unset.Allowed characters: a-z, A-Z, 0-9, and . _ + @ ~ / -Example: routing.user+1@example
curl -X PUT https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000/sip/registration \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sipDomain": "sip.example.com",
    "username": "1001",
    "password": "secure_password",
    "proxy": "proxy.example.com",
    "port": 5060,
    "transport": "udp"
  }'

{
  "success": true,
  "data": {
    "sipDomain": "sip.example.com",
    "username": "1001",
    "password": "secure_password",
    "proxy": "proxy.example.com",
    "port": 5060,
    "transport": "udp",
    "subscribe": false,
    "authUsername": null,
    "did": null,
    "sipRoutingHeaderXDestUser": null,
    "registrationEnabled": true,
    "extension": "1001"
  }
}

​
How It Works

  1. API validates the SIP configuration fields
  2. Stores configuration in the agent’s sip_registration_data field with registrationEnabled: true
  3. Sync service picks up the change via Supabase realtime and registers with OpenSIPS
  4. Agent can now receive inbound calls via the SIP registration
The extension field is automatically set to match username. The registrationEnabled flag is automatically set to true when saving — saving a registration means enabling it.

​
Common PBX Configurations

​
FreePBX / Asterisk

{
  "sipDomain": "pbx.local",
  "username": "100",
  "password": "extension_password",
  "port": 5060,
  "transport": "udp"
}

​
3CX

{
  "sipDomain": "company.3cx.us",
  "username": "1001",
  "password": "sip_password",
  "proxy": "company.3cx.us",
  "port": 5060,
  "transport": "tls"
}

​
Twilio SIP

{
  "sipDomain": "yourdomain.sip.twilio.com",
  "username": "agent",
  "password": "twilio_password",
  "port": 5060,
  "transport": "tls"
}
After configuring SIP registration, the agent will automatically receive calls sent to the configured SIP address. Make sure your PBX or SIP provider is configured to route calls to this address.

​
Troubleshooting

ErrorCauseSolution
”Agent not found”Invalid agentId or no accessVerify the agent ID and your access token
”Cannot update vida agents via this API”Agent is not a LiveKit agentOnly LiveKit agents support SIP registration via API
Agent not receiving callsSIP registration failedUse the status endpoint to check registration state
One-way audioNAT/firewall issuesTry TCP or TLS transport, check proxy settings