Gateways Module Documentation

Table of Contents

1. Navigation & Access
2. Screenshots & Visual Interface
3. Module Overview (Technical)
4. Module Overview (Commercial/Business)
5. Module Overview (End User/Administrator)
6. Configuration Fields Reference
7. Gateway SIP Profiles
8. Common Scenarios & Examples
9. Model Context Protocol (MCP) AI Integration
10. Limitations & Important Notes
11. Troubleshooting Tips
12. Glossary

---

Navigation & Access

To access the Gateways & SIP Trunks module:

1. Log in to the Ring2All Web Portal.
2. In the left navigation sidebar, expand PBX Engine.
3. Under Call Routing, click Gateways / Trunks (/pbx/calls-routing/gateways).

---

Screenshots & Visual Interface

Gateways Management List View

Displays all configured SIP gateways, their registration status, host/proxy, profile, and action shortcuts.

Gateway Configuration Form

Provides full configuration across Basic Information and granular tabs: Connection, SIP Behavior, Registration, Media, and Routing.

---

1. Module Overview (Technical)

What Are Gateways?

Gateways define SIP trunk connections to external carriers, ITSPs, or other PBX systems. Each gateway represents a configured connection with authentication, registration, and routing settings.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Gateway System                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Gateway SIP Profile: "Standard Carrier"                        │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Transport: UDP   │ DTMF: RFC2833   │ Codec: G711, G729    │ │
│  │ NAT: Enabled     │ TLS: Disabled   │ Media: Proxy         │ │
│  └────────────────────────────────────────────────────────────┘ │
│                          │                                      │
│            Assigned to Gateways:                                │
│                          │                                      │
│  ┌──────────────────┐    │    ┌──────────────────┐              │
│  │ Gateway: CarrierA│    │    │ Gateway: CarrierB│              │
│  │ Proxy: sip.a.com │◄───┼────▶ Proxy: sip.b.com │              │
│  │ Username: user1  │    │    │ Username: user2  │              │
│  │ Register: Yes    │    │    │ Register: Yes    │              │
│  │ Channels: 30     │    │    │ Channels: 20     │              │
│  │ Failover: B      │    │    │ Failover: None   │              │
│  └──────────────────┘         └──────────────────┘              │
│                                                                 │
│  Used by:                                                       │
│  ├─ Outbound Routes (dial patterns → gateway selection)        │
│  ├─ Inbound Routes (gateway → destination1)                    │
│  └─ ARS Profiles (time-based gateway selection)                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Integration with Telephony Server

Gateways are translated into Telephony Server XML configuration:

<gateway name="carrier_a">
  <param name="username" value="user1"/>
  <param name="password" value="secret"/>
  <param name="proxy" value="sip.carrier-a.com"/>
  <param name="register" value="true"/>
  ...
</gateway>

---

2. Module Overview (Commercial/Business)

Business Value

Gateways enable external telephony connectivity:

Without Gateways	With Gateways
Internal calls only	External PSTN/SIP calls
No carrier integration	Multiple carrier support
No failover	Automatic failover
Single path	Load balancing

Use Cases

1. PSTN Connectivity

   • Connect to telco carriers
   • Terminate calls to phone numbers

2. SIP Trunking

   • Connect to VoIP providers
   • Cost-effective calling

3. Multi-Carrier Routing

   • Primary/backup carriers
   • Least-cost routing

4. PBX Interconnection

   • Connect branch offices
   • Legacy system integration

Feature Highlights

Feature	Benefit
Gateway SIP Profiles	Reusable carrier settings
Registration	Dynamic registration with carriers
Authentication	Username/password, realm support
NAT Traversal	Works behind firewalls
Failover	Automatic backup gateway
Channel Limits	Concurrent call control
Codec Selection	Audio/video codec preference
TLS/SRTP	Secure signaling and media

---

3. Module Overview (End User/Administrator)

What Can You Do?

Gateways:

• Create SIP trunk connections
• Configure authentication
• Set registration parameters
• Define channel limits
• Configure failover cascades

Gateway SIP Profiles:

• Create reusable settings templates
• Configure transport and codecs
• Set NAT/security options
• Apply to multiple gateways

Administrator Workflow

┌─────────────────────────────────────────────────────────────────┐
│              Creating a Gateway                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Basic Information                                              │
│  ├─ Gateway Name: "carrier_main"                               │
│  ├─ Description: "Primary VoIP Carrier"                        │
│  ├─ Gateway SIP Profile: Standard Carrier                      │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Authentication & Connection                                    │
│  ├─ Proxy: sip.carrier.com                                     │
│  ├─ Username: account123                                       │
│  ├─ Password: ●●●●●●●●                                         │
│  └─ Realm: carrier.com                                         │
│                                                                 │
│  Registration & Keepalive                                       │
│  ├─ Register: ✓                                                │
│  ├─ Expire Seconds: 3600                                       │
│  ├─ Retry Seconds: 30                                          │
│  └─ Ping Interval: 25                                          │
│                                                                 │
│  Routing & Limits                                               │
│  ├─ Context: public                                            │
│  ├─ Max Channels: 30                                           │
│  └─ Failover Gateway: carrier_backup                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

[!TIP] Use SIP Profiles: Create profiles for common carrier types to reuse settings.

[!TIP] Set Failover: Always configure a backup gateway for reliability.

[!CAUTION] Channel Limits: Set realistic limits to prevent carrier billing surprises.

---

4. Configuration Fields Reference

Gateway Fields

Basic Information

Field	Description	Example
Gateway Name	Unique identifier	carrier_main
Description	Optional description	Primary VoIP Carrier
Gateway SIP Profile	Inherited settings	Standard Carrier
Dial Profile	Reusable template to apply call variables and behaviors	Office Default
Enabled	Gateway active status	On/Off

Authentication & Connection

Field	Description	Example
Proxy	Carrier SIP address	sip.carrier.com
Username	SIP authentication user	account123
Password	SIP password	●●●●●●●●
Auth Username	Alternative auth user	(optional)
Realm	Authentication realm	carrier.com
Outbound Proxy	Separate signaling path	(optional)
Register Proxy	Separate registration	(optional)
Register Transport	UDP/TCP/TLS	UDP

Registration & Keepalive

Field	Description	Default
Register	Enable registration	On
Expire Seconds	Registration period	3600
Retry Seconds	Retry on failure	30
Ping Interval	OPTIONS ping interval	25
Ping Min/Max	Up/down thresholds	1/5
Contact in Ping	Include Contact header	Off

Media & Overrides

Field	Description
Audio Codecs	Preferred codec list
Video Codecs	Video codec list
Allow Video	Enable video calls
Packetization Time	RTP packet size
T.38 Support	Fax relay support

Routing & Limits

Field	Description	Default
Context	Inbound dialplan context	public
Extension	Default inbound extension	-
Max Channels	Concurrent call limit	0 (unlimited)
Failover Gateway	Backup gateway	None

---

5. Gateway SIP Profiles

Purpose

Gateway SIP Profiles are reusable configuration templates that define:

• Transport settings (UDP/TCP/TLS)
• DTMF mode
• Codec preferences
• NAT handling
• TLS/SRTP security

Profile Sections

Signaling & Transport

Field	Options	Description
Transport	UDP, TCP, TLS	SIP transport
DTMF Mode	RFC2833, INFO, Inband	DTMF signaling
INVITE Format	user@domain, E.164	URI format
Caller ID Policy	From, PAI, RPID	CID header
NAT Mapping	On/Off	Contact rewrite
Register Transport	UDP, TCP, TLS	Registration transport

Media & Codecs

Field	Description
Audio Codecs	PCMU, PCMA, G729, G722, OPUS
Video Codecs	VP8, H264, H263, AV1
Allow Video	Enable video negotiation
RTP Proxy	Force media through PBX
Packetization Time	10, 20, 30, 40 ms
T.38 Support	Fax relay

Security / TLS

Field	Description
TLS Enabled	Enable TLS signaling
TLS Verify Policy	Certificate verification
TLS Version	Minimum TLS version
SRTP Mode	Always, Optional, Never
Require Secure Media	Reject non-SRTP

---

6. Common Scenarios & Examples

Scenario 1: Basic ITSP Connection

Gateway: “voip_carrier”

Setting	Value
Proxy	sip.voip-carrier.com
Username	12345678
Password	●●●●●●●●
Register	Yes
Transport	UDP
Codecs	PCMU, PCMA, G729

Scenario 2: Primary + Backup Carriers

Gateway: “carrier_primary”

Setting	Value
Proxy	sip.carrier-a.com
Max Channels	30
Failover	carrier_backup

Gateway: “carrier_backup”

Setting	Value
Proxy	sip.carrier-b.com
Max Channels	20
Failover	None

Scenario 3: Secure TLS Trunk

Gateway SIP Profile: “Secure Carrier”

Setting	Value
Transport	TLS
TLS Version	1.2
TLS Verify	Peer
SRTP Mode	Always

Gateway: “secure_trunk”

Setting	Value
Gateway SIP Profile	Secure Carrier
Proxy	sips.carrier.com:5061

---

7. Model Context Protocol (MCP) AI Integration

Ring2All exposes native Model Context Protocol (MCP) tools for Gateways & SIP Trunks, enabling AI agents, NOC Copilots, and platform engineers to inspect live Telephony Server Sofia registrations, provision external carrier trunks, trigger dynamic non-disruptive gateway reloads, analyze SIP handshake failures, and troubleshoot trunk availability programmatically with domain-level isolation and relational integrity safeguards.

Available MCP Tools

Tool Name	Description	Key Parameters
list_gateways	Lists all SIP gateways and trunks in the domain with their proxy, realm, registration status, enabled state, and failover targets.	search (optional string)
get_gateway_status	Retrieves complete database configuration and live Telephony Server Sofia registration state (ping status, state machine, registration IP, expiration) for a specific trunk.	name (required string)
create_gateway	Provisions a new SIP trunk or carrier connection with authentication credentials, proxy host, registration flags, and channel limits. Strictly enforces name uniqueness per domain.	name, proxy, realm, username, password, register, expireSeconds, fromDomain, description
update_gateway	Updates gateway connection parameters, SIP proxies, credentials, registration flags, or administrative state (enabled).	name, newName, proxy, realm, username, password, register, enabled
diagnose_gateway	Conducts deep automated diagnostic analysis on a trunk: verifies DNS A/SRV resolution, queries Sofia registration state, tests live SIP OPTIONS ping latency, scans Telephony log buffers for SIP error codes (401, 403, 408, 503), and produces root-cause analysis with concrete remediation steps.	name (required string), linesCount (optional number, default: 300)
diagnose_gateway_connection	Legacy compatibility alias for diagnose_gateway.	name (required string), linesCount (optional number)
delete_gateway	Safely removes a gateway trunk after verifying via assertCanDeleteGateway that no active outbound routes or inbound routes depend on it.	name (required string)

Protection Guards & Integrity

• Name Uniqueness: Every gateway name must be unique within its tenant domain. Duplicate names are immediately rejected.
• Relational Integrity (assertCanDeleteGateway): A gateway cannot be deleted if it is designated as primary or failover trunk in any Outbound Route, or if inbound DIDs route through it. The MCP server returns a descriptive rejection detailing the blocking routes.
• Hot-Reload Telephony Server Isolation: Modifying or reloading a gateway executes targeted Sofia commands via ESL, preventing broad PBX service interruptions.

AI Agent Operational Examples

Auditing Gateway Status & Live Registration

{
  "tool": "get_gateway_status",
  "arguments": {
    "name": "Telnyx_Primary"
  }
}

Diagnosing Connection Failures with AI Log Parsing

{
  "tool": "diagnose_gateway_connection",
  "arguments": {
    "name": "Twilio_Outbound",
    "linesCount": 200
  }
}

Provisioning an IP-Authentication SIP Trunk

{
  "tool": "create_gateway",
  "arguments": {
    "name": "Flowroute_Direct",
    "proxy": "sip.flowroute.com",
    "realm": "sip.flowroute.com",
    "register": false,
    "description": "Direct IP-authenticated termination trunk"
  }
}

Recommended Natural Language Prompts

• “Check the registration status of all SIP gateways in this domain.”
• “Why is the Twilio_Primary gateway failing to register? Run a diagnostic and check the recent SIP logs.”
• “Reload the Telnyx gateway in Telephony Server so the new credentials take effect.”
• “Create a new SIP trunk named ‘Bandwidth_US’ pointing to ‘sip.bandwidth.com’ with registration disabled.”

---

8. Limitations & Important Notes

Technical Notes

[!NOTE] Configuration Module: Gateways are configuration entities. Settings are translated to Telephony Server XML by the configuration generator.

[!WARNING] Reload Required: Gateway changes require Telephony Server sofia profile reload.

[!WARNING] NAT Considerations: Enable NAT mapping when PBX is behind firewall.

Best Practices

1. Use Profiles: Create profiles for common carrier types
2. Set Channel Limits: Prevent unexpected charges
3. Configure Failover: Always have a backup
4. Test Registration: Verify gateway registers successfully
5. Monitor Status: Check gateway status regularly
6. Secure Credentials: Use strong passwords

---

9. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Not registered	Wrong credentials	Verify username/password
Registration timeout	Firewall blocking	Check ports 5060/5061
Calls fail	Wrong proxy	Verify proxy address
One-way audio	NAT issue	Enable NAT mapping
No audio	Codec mismatch	Check codec preferences
TLS errors	Certificate issue	Verify TLS settings

Telephony Server Commands

# List all sofia profiles
sofia status

# Show gateway status
sofia status gateway carrier_main

# Reload gateway
sofia profile external restart gateway carrier_main

# Kill gateway registration
sofia profile external killgw carrier_main

# Show registrations
sofia status profile external reg

Diagnostic SQL

List gateways:

SELECT id, name, proxy, username, enabled, register
FROM public.sip_gateways
ORDER BY name;

Check gateway settings:

SELECT g.name, s.name as setting, s.value
FROM public.sip_gateways g
JOIN public.gateway_settings s ON g.id = s.gateway_id
WHERE g.name = 'carrier_main';

---

10. Glossary

Term	Definition
Gateway	SIP trunk connection to external carrier
SIP Profile	Reusable configuration template
Registration	Process of registering with carrier
Proxy	Carrier’s SIP server address
Realm	Authentication domain
Failover	Automatic switch to backup gateway
ITSP	Internet Telephony Service Provider
NAT	Network Address Translation
SRTP	Secure Real-time Transport Protocol

---

Documentation last updated: January 2026