Setup guide · Gateway XML

Connect a SIP trunk to FreeSWITCH

In FreeSWITCH a SIP trunk is a gateway on the external Sofia profile. You add one XML file, a dialplan extension that bridges to the gateway, and an ACL entry so inbound calls from our IP are accepted.

Get Rates Talk to NOC

Before you start

What you need

FreeSWITCH 1.10+ with the default external profile on port 5080 (or your own)
A public IP, or ext-sip-ip / ext-rtp-ip set correctly
Your SIPTrunkHub account details: SIP server, auth method, tech prefix if any
Shell access to /etc/freeswitch (or /usr/local/freeswitch/conf)

IP auth or register auth?

IP authentication

Recommended

Set register to false. We whitelist the public IP of your external profile. Add our IP to the providers ACL for inbound.

Register (digest) authentication

Set register to true with username and password. FreeSWITCH keeps the registration alive and retries on failure.

Step by step

Configure FreeSWITCH

sip.example-host.net and 203.0.113.10 are documentation placeholders. Replace them, and the username, password and tech prefix, with the values from your account.

Create the gateway

Add a file in the external profile directory. With IP auth, username and password are still required by Sofia but are not sent.

sip_profiles/external/siptrunkhub.xml

<include>
  <gateway name="siptrunkhub">
    <param name="proxy" value="sip.example-host.net"/>
    <param name="realm" value="sip.example-host.net"/>
    <param name="register" value="false"/>
    <param name="username" value="not-used"/>
    <param name="password" value="not-used"/>
    <param name="caller-id-in-from" value="true"/>
    <param name="ping" value="30"/>
    <!-- register auth instead:
    <param name="register" value="true"/>
    <param name="username" value="YOUR_SIP_USERNAME"/>
    <param name="password" value="YOUR_SIP_PASSWORD"/>
    <param name="expire-seconds" value="600"/>
    <param name="retry-seconds" value="30"/>
    -->
  </gateway>
</include>

Add an outbound dialplan extension

Match 00 + digits, strip the 00 and bridge to the gateway. Set the caller ID you want presented.

dialplan/default/01_siptrunkhub.xml

<include>
  <extension name="siptrunkhub-intl">
    <condition field="destination_number" expression="^00(\d{7,15})$">
      <action application="set" data="effective_caller_id_number=442079460000"/>
      <action application="set" data="hangup_after_bridge=true"/>
      <action application="bridge" data="sofia/gateway/siptrunkhub/$1"/>
      <!-- with tech prefix 1234#: sofia/gateway/siptrunkhub/1234#$1 -->
    </condition>
  </extension>
</include>

03
Accept inbound calls from our IP
The external profile applies the providers ACL by default (apply-inbound-acl). Add our signalling IP so calls are not challenged.
autoload_configs/acl.conf.xml
```
<list name="providers" default="deny">
  <node type="allow" cidr="203.0.113.10/32"/>
</list>
```

Route DIDs

Calls from the external profile land in the public context. Match the DID and transfer it to an extension in the default context.

dialplan/public/01_siptrunkhub_did.xml

<include>
  <extension name="did-442079460000">
    <condition field="destination_number" expression="^\+?442079460000$">
      <action application="transfer" data="1000 XML default"/>
    </condition>
  </extension>
</include>

Reload

Reload XML and the ACL, then rescan the profile to load the new gateway without dropping calls.

fs_cli

fs_cli -x "reloadxml"
fs_cli -x "reloadacl"
fs_cli -x "sofia profile external rescan"
fs_cli -x "sofia status gateway siptrunkhub"

Media

Codec order

Set global_codec_prefs and outbound_codec_prefs in vars.xml: PCMU,PCMA,G729.
G.729 is supported natively (mod_g729) in FreeSWITCH 1.10+.
For T.38 fax set fax_enable_t38=true and fax_enable_t38_request=true on the fax leg.

NAT notes

In vars.xml set external_rtp_ip and external_sip_ip to your public IP (or stun:/autonat:).
The external profile uses ext-rtp-ip and ext-sip-ip from those variables.
Open the RTP range in switch.conf.xml (default 16384–32768) inbound on your firewall.
Disable SIP ALG on the router.

Verify

Test the trunk

ping=30 sends OPTIONS to our server. sofia status gateway should show State REGED (register) or NOREG with Status UP (IP auth). Then originate a test call.

fs_cli

sofia status gateway siptrunkhub
sofia global siptrace on
originate sofia/gateway/siptrunkhub/447700900123 &echo

Troubleshooting

Common SIP errors

What each response means and what to check first on FreeSWITCH. If you still need help, send the Call-ID and timestamp to the NOC.

Common SIP error codes and fixes for FreeSWITCH
Code	Meaning	Likely cause	Fix on FreeSWITCH
401	Unauthorized	We challenged the INVITE or REGISTER and the credentials were wrong or missing. With IP auth it usually means the call arrived from an IP we have not whitelisted.	For inbound: our IP is missing from the providers ACL. For outbound: check username and realm.
403	Forbidden	Authenticated, but not allowed: wrong or missing tech prefix, zero prepaid balance, destination blocked on your account, or an invalid caller ID.	Check balance and tech prefix first, then the caller ID format. If both look right, send the Call-ID to the NOC.
404	Not Found	The dialled number is not in a format we can route: missing country code, an extra 00 or +, or a local trunk prefix left in.	Check the regex capture. The bridge string must contain digits only, no 00 or +.
408	Request Timeout	No response came back. Usually a firewall, wrong port or transport, a DNS failure, or SIP ALG on the router eating packets.	The gateway status shows DOWN. Check that the external profile port (5080) is the one we whitelisted.
480	Temporarily Unavailable	The far end could not be reached: handset off, out of coverage, or the route for that prefix is temporarily down.	Retry later or route to another trunk. If it hits one prefix repeatedly, send examples to the NOC.
486	Busy Here	The called party is busy, or you reached the concurrent-channel limit on your account.	Treat as a normal busy. If every call returns 486, check your active channel count against your limit.
503	Service Unavailable	Capacity limit hit (calls per second or channels), or every route for that destination failed.	Pace your dialer to the agreed CPS. Configure a second trunk for failover. Ask the NOC if it persists.

Seeing one-way audio instead of an error? Read One-Way Audio on VoIP Calls.

FAQ

FreeSWITCH questions

Why is the external profile on port 5080?

That is the FreeSWITCH default. Tell us if your gateway uses 5080 so we send inbound calls to the right port, or move the profile to 5060.

Can I use multiple gateways for failover?

Yes. Use a pipe in the bridge string: sofia/gateway/siptrunkhub/$1|sofia/gateway/backup/$1. FreeSWITCH tries them in order.

How do I see the full SIP trace?

Run sofia global siptrace on in fs_cli, or use sngrep on the server.

Other setup guides

All 12 guides

Popular destinations

Stuck on a step?

The NOC answers 24/7. Send your platform, a SIP trace and the Call-ID of a failed attempt.

Ready to connect FreeSWITCH?

Prepaid from $200. No setup fee, no contract. Get rates and your account details from sales.