1. configuration
VoiceDock
  • introduction
  • configuration
    • analysis-templates
    • custom-tools
    • sip-trunks
    • tool-templates
  • core-concepts
    • assistants
    • calls
    • phone-numbers
    • webhooks
  • features
    • ai-generation
    • autonomous-silence-handling
    • call-analysis
    • call-transfers
    • campaigns-setup
    • campaigns
    • privacy-compliance
    • voicemail-detection
    • web-calls
  • get-started
    • authentication
    • quickstart
  • guides
    • data-processing-agreement
  • integrations
    • byok-setup
    • mcp-server
    • provider-pricing
    • xai-grok-integration
  • platform
    • billing
    • dashboard-security
    • eu-data-sovereignty
    • privacy-policy
    • voice-selection-psychology
    • whitelabel
  • reference
    • error-codes
    • rate-limits
    • troubleshooting
  • sdks
    • node
  • webhooks
    • assistant-request
    • end-of-call-report
    • overview
    • security
    • status-update
    • tool-calls
Book a meeting
Linkedin
Github
📄 Documentation
🔌 API Reference🤖 MCP📦 SDK🟢 Status
📄 Documentation
🔌 API Reference🤖 MCP📦 SDK🟢 Status
  1. configuration

sip-trunks

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#

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#

FieldTypeRequiredDescription
namestringYesDisplay name for the trunk
hoststringYesSIP server hostname or IP
portintegerNoSIP port (default: 5060)
usernamestringNoAuthentication username
passwordstringNoAuthentication password
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:
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:

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:
1.
Create a new SIP trunk in Connectivity > Trunks
2.
Set the trunk name and peer details
3.
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#

Deleting a SIP Trunk#

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

Troubleshooting#

Transfers Not Connecting#

1.
Verify the SIP trunk host is accessible
2.
Check firewall allows SIP traffic (port 5060)
3.
Verify credentials are correct
4.
Test the destination number directly

Audio Issues After Transfer#

1.
Check NAT configuration on your PBX
2.
Verify RTP ports are open
3.
Ensure codecs are compatible

Related#

Call Transfers Guide
SIP Trunks API
Phone Numbers API
Modified at 2026-05-04 13:09:50
Previous
custom-tools
Next
tool-templates
Built with