---
title: "Gateways Module Documentation"
description: "Documentation for Gateways"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [Configuration Fields Reference](#4-configuration-fields-reference)
7. [Gateway SIP Profiles](#5-gateway-sip-profiles)
8. [Common Scenarios & Examples](#6-common-scenarios--examples)
9. [Model Context Protocol (MCP) AI Integration](#7-model-context-protocol-mcp-ai-integration)
10. [Limitations & Important Notes](#8-limitations--important-notes)
11. [Troubleshooting Tips](#9-troubleshooting-tips)
12. [Glossary](#10-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.
![Gateways List View](/screenshots/pbx/call-routing/gateways-list.png)

### Gateway Configuration Form
Provides full configuration across Basic Information and granular tabs: Connection, SIP Behavior, Registration, Media, and Routing.
![Gateway Configuration Form](/screenshots/pbx/call-routing/gateways-form.png)

---

## 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:
```xml
<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
```json
{
  "tool": "get_gateway_status",
  "arguments": {
    "name": "Telnyx_Primary"
  }
}
```

#### Diagnosing Connection Failures with AI Log Parsing
```json
{
  "tool": "diagnose_gateway_connection",
  "arguments": {
    "name": "Twilio_Outbound",
    "linesCount": 200
  }
}
```

#### Provisioning an IP-Authentication SIP Trunk
```json
{
  "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

```bash
# 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:**
```sql
SELECT id, name, proxy, username, enabled, register
FROM public.sip_gateways
ORDER BY name;
```

**Check gateway settings:**
```sql
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*