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"
}'
const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(
`https://api.telzino.com/v1/agents/${agentId}/sip/registration`,
{
method: 'PUT',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
sipDomain: 'sip.example.com',
username: '1001',
password: 'secure_password',
proxy: 'proxy.example.com',
port: 5060,
transport: 'udp'
})
}
);
const result = await response.json();
import requests
agent_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.put(
f'https://api.telzino.com/v1/agents/{agent_id}/sip/registration',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
json={
'sipDomain': 'sip.example.com',
'username': '1001',
'password': 'secure_password',
'proxy': 'proxy.example.com',
'port': 5060,
'transport': 'udp'
}
)
result = response.json()
{
"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"
}
}
{
"error": "Invalid request data",
"details": [
{
"code": "invalid_type",
"expected": "string",
"received": "undefined",
"path": ["password"],
"message": "Required"
}
]
}
{
"error": "not_found",
"error_description": "Agent not found or access denied"
}
Agents
Set SIP Registration
Configure SIP registration settings for an agent to receive calls from a PBX or SIP provider
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"
}'
const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(
`https://api.telzino.com/v1/agents/${agentId}/sip/registration`,
{
method: 'PUT',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
sipDomain: 'sip.example.com',
username: '1001',
password: 'secure_password',
proxy: 'proxy.example.com',
port: 5060,
transport: 'udp'
})
}
);
const result = await response.json();
import requests
agent_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.put(
f'https://api.telzino.com/v1/agents/{agent_id}/sip/registration',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
json={
'sipDomain': 'sip.example.com',
'username': '1001',
'password': 'secure_password',
'proxy': 'proxy.example.com',
'port': 5060,
'transport': 'udp'
}
)
result = response.json()
{
"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"
}
}
{
"error": "Invalid request data",
"details": [
{
"code": "invalid_type",
"expected": "string",
"received": "undefined",
"path": ["password"],
"message": "Required"
}
]
}
{
"error": "not_found",
"error_description": "Agent not found or access denied"
}
Path Parameters
string
required
The unique identifier of the agent (UUID format)
Request Body
Required Fields
string
required
SIP domain for the registration.Example:
sip.example.comstring
required
SIP username for authentication. Also used as the extension number.Example:
1001string
required
SIP password for authentication.
Optional Fields
string
SIP proxy server address. Use this if your SIP provider requires routing through a proxy.Example:
proxy.sip.example.cominteger | null
default:"5060"
Registrar/proxy port.Common values:
5060- Standard SIP (UDP/TCP)5061- SIP over TLS
null to omit the port from the SIP URI, so the platform resolves the host by DNS SRV (with failover) instead of an A record. This is required for SRV-only hosts, which publish _sip._udp / _sip._tcp / _sips._tcp records and no A record. 0 is not accepted; null is the only “no port” spelling.string
Optional
User-Agent header sent on the outbound SIP REGISTER in place of the platform default. Use it when the registrar only accepts registrations from specific phone models, for example Yealink SIP-T54W 96.86.0.75. Printable ASCII only, a single line, at most 255 characters. Omit or send an empty string to use the default.string
default:"udp"
Transport protocol.Supported values:
udp- User Datagram Protocol (most common)tcp- Transmission Control Protocoltls- Transport Layer Security (encrypted)
boolean
default:"false"
Enable SIP SUBSCRIBE for presence/BLF (Busy Lamp Field).Set to
true if you need presence information from the PBX.boolean
default:"true"
Whether the SIP registration is active.Defaults to
true when omitted, so saving a registration enables it. Set to
false to disable the registration — marking the agent inactive — while keeping
its SIP configuration stored. Use the DELETE method instead if you want to
remove the configuration entirely.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.string
DID (Direct Inward Dialing) number to send in the SIP INVITE.Example:
+15551234567string
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@examplecurl -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"
}'
const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(
`https://api.telzino.com/v1/agents/${agentId}/sip/registration`,
{
method: 'PUT',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
sipDomain: 'sip.example.com',
username: '1001',
password: 'secure_password',
proxy: 'proxy.example.com',
port: 5060,
transport: 'udp'
})
}
);
const result = await response.json();
import requests
agent_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.put(
f'https://api.telzino.com/v1/agents/{agent_id}/sip/registration',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
json={
'sipDomain': 'sip.example.com',
'username': '1001',
'password': 'secure_password',
'proxy': 'proxy.example.com',
'port': 5060,
'transport': 'udp'
}
)
result = response.json()
{
"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"
}
}
{
"error": "Invalid request data",
"details": [
{
"code": "invalid_type",
"expected": "string",
"received": "undefined",
"path": ["password"],
"message": "Required"
}
]
}
{
"error": "not_found",
"error_description": "Agent not found or access denied"
}
How It Works
- API validates the SIP configuration fields
- Stores configuration in the agent’s
sip_registration_datafield, withregistrationEnabledset to the value you provide (defaults totrue) - Sync service picks up the change via Supabase realtime and registers with OpenSIPS
- Agent can now receive inbound calls via the SIP registration
The
extension field is automatically set to match username. The registrationEnabled flag defaults to true when saving — so saving a registration enables it unless you explicitly pass registrationEnabled: false.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
| Error | Cause | Solution |
|---|---|---|
| ”Agent not found” | Invalid agentId or no access | Verify the agent ID and your access token |
| ”Cannot update vida agents via this API” | Agent is not a LiveKit agent | Only LiveKit agents support SIP registration via API |
| Agent not receiving calls | SIP registration failed | Use the status endpoint to check registration state |
| One-way audio | NAT/firewall issues | Try TCP or TLS transport, check proxy settings |
