SIP Trunks

Configure SIP trunks to enable call transfers from your AI assistant to external phone systems.

SIP trunks enable call transfers from your AI assistant to external phone systems, such as your office PBX or contact center.

What is a SIP Trunk?

A SIP trunk is a connection to a phone system that allows calls to be transferred over the internet using the SIP (Session Initiation Protocol) protocol.

When Do You Need a SIP Trunk?

Call transfers to your PBX - Route calls to internal extensions
Contact center integration - Transfer to human agents in your call center
Multi-location routing - Route calls to different offices

Creating a SIP Trunk

curl -X POST https://api.hmsovereign.com/api/v1/sip-trunks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Office PBX",
    "host": "pbx.example.com",
    "port": 5060,
    "username": "hms-sovereign",
    "password": "secure-password"
  }'

Response:

{
  "sip_trunk": {
    "id": "trunk-uuid",
    "name": "Office PBX",
    "host": "pbx.example.com",
    "port": 5060,
    "username": "hms-sovereign",
    "created_at": "2025-12-13T10:00:00.000Z"
  }
}

SIP Trunk Fields

Field	Type	Required	Description
`name`	string	Yes	Display name for the trunk
`host`	string	Yes	SIP server hostname or IP
`port`	integer	No	SIP port (default: 5060)
`username`	string	No	Authentication username
`password`	string	No	Authentication password

Note: Passwords are stored securely and encrypted at rest. They are never exposed in API responses.

Assigning a Trunk to a Phone Number

After creating a trunk, assign it to phone numbers that should use it for transfers:

curl -X PATCH https://api.hmsovereign.com/api/v1/numbers/NUMBER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transfer_trunk_id": "trunk-uuid"
  }'

Now transfers from this phone number will route through your SIP trunk.

Using Transfers

Assistant-Initiated Transfers

Add the transfer tool to your assistant:

{
  "llm_config": {
    "tools": [
      {
        "type": "transfer_call",
        "destinations": [
          {
            "type": "number",
            "number": "+31612345678",
            "description": "Human support assistant",
            "message": "I'm transferring you to a colleague."
          }
        ]
      }
    ]
  }
}

API-Initiated Transfers

Transfer an active call via the API:

curl -X POST https://api.hmsovereign.com/api/v1/calls/CALL_ID/control \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "transfer",
    "destination": "+31612345678",
    "message": "One moment, I'm transferring you."
  }'

SIP Trunk Configuration Examples

FreePBX / Asterisk

{
  "name": "FreePBX",
  "host": "192.168.1.100",
  "port": 5060,
  "username": "hms-sovereign-trunk",
  "password": "your-trunk-password"
}

FreePBX configuration:

Create a new SIP trunk in Connectivity > Trunks
Set the trunk name and peer details
Add HMS Sovereign's IP to your firewall allowlist

3CX

{
  "name": "3CX Office",
  "host": "yourcompany.3cx.com",
  "port": 5060,
  "username": "hms-sovereign",
  "password": "trunk-password"
}

Generic SIP Provider

{
  "name": "SIP Provider",
  "host": "sip.provider.com",
  "port": 5060,
  "username": "your-account",
  "password": "your-password"
}

Listing SIP Trunks

curl https://api.hmsovereign.com/api/v1/sip-trunks \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting a SIP Trunk

When you delete a SIP trunk, any phone numbers using it will have their transfer_trunk_id set to null:

curl -X DELETE https://api.hmsovereign.com/api/v1/sip-trunks/TRUNK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"