> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set SIP Registration

> Configure SIP registration settings for an agent to receive calls from a PBX or SIP provider

## Path Parameters

<ParamField path="agentId" type="string" required>
  The unique identifier of the agent (UUID format)
</ParamField>

## Request Body

### Required Fields

<ParamField body="sipDomain" type="string" required>
  SIP domain for the registration.

  **Example:** `sip.example.com`
</ParamField>

<ParamField body="username" type="string" required>
  SIP username for authentication. Also used as the extension number.

  **Example:** `1001`
</ParamField>

<ParamField body="password" type="string" required>
  SIP password for authentication.
</ParamField>

### Optional Fields

<ParamField body="proxy" type="string">
  SIP proxy server address. Use this if your SIP provider requires routing through a proxy.

  **Example:** `proxy.sip.example.com`
</ParamField>

<ParamField body="port" type="integer" default="5060">
  SIP port number.

  **Common values:**

  * `5060` - Standard SIP (UDP/TCP)
  * `5061` - SIP over TLS
</ParamField>

<ParamField body="transport" type="string" default="udp">
  Transport protocol.

  **Supported values:**

  * `udp` - User Datagram Protocol (most common)
  * `tcp` - Transmission Control Protocol
  * `tls` - Transport Layer Security (encrypted)
</ParamField>

<ParamField body="subscribe" type="boolean" default="false">
  Enable SIP SUBSCRIBE for presence/BLF (Busy Lamp Field).

  Set to `true` if you need presence information from the PBX.
</ParamField>

<ParamField body="registrationEnabled" type="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.
</ParamField>

<ParamField body="authUsername" type="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.
</ParamField>

<ParamField body="did" type="string">
  DID (Direct Inward Dialing) number to send in the SIP INVITE.

  **Example:** `+15551234567`
</ParamField>

<ParamField body="sipRoutingHeaderXDestUser" type="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`
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Invalid request data",
    "details": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": ["password"],
        "message": "Required"
      }
    ]
  }
  ```

  ```json 404 theme={null}
  {
    "error": "not_found",
    "error_description": "Agent not found or access denied"
  }
  ```
</ResponseExample>

## How It Works

1. **API validates** the SIP configuration fields
2. **Stores configuration** in the agent's `sip_registration_data` field, with `registrationEnabled` set to the value you provide (defaults to `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

<Info>
  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`.
</Info>

## Common PBX Configurations

### FreePBX / Asterisk

```json theme={null}
{
  "sipDomain": "pbx.local",
  "username": "100",
  "password": "extension_password",
  "port": 5060,
  "transport": "udp"
}
```

### 3CX

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

### Twilio SIP

```json theme={null}
{
  "sipDomain": "yourdomain.sip.twilio.com",
  "username": "agent",
  "password": "twilio_password",
  "port": 5060,
  "transport": "tls"
}
```

<Info>
  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.
</Info>

## 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](/api-reference/agents/sip-registration-status) to check registration state |
| One-way audio                            | NAT/firewall issues          | Try TCP or TLS transport, check proxy settings                                                       |