---
title: "Device SIP Profiles Module Documentation"
description: "Documentation for Device Profiles"
---

## 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. [User Roles & Key Capabilities](#-user-roles--key-capabilities)
7. [Configuration Categories](#4-configuration-categories)
8. [Settings Reference](#5-settings-reference)
9. [Common Scenarios & Examples](#6-common-scenarios--examples)
10. [Limitations & Important Notes](#7-limitations--important-notes)
11. [Troubleshooting Tips](#8-troubleshooting-tips)
12. [Glossary](#9-glossary)
13. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
---

## Navigation & Access

To access the Device Profiles configuration module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Settings**.
3. Under **Technology**, click **Device profiles** (`/settings/technology/device-profile`).
4. To add a new device profile template, click **+ Add Profile** (`/settings/technology/device-profile/new`). To edit an existing profile, click on the profile row or the **Edit** action button (`/settings/technology/device-profile/:id`).

---

## Screenshots & Visual Interface

### Device Profiles Directory
Directory of registered device profile templates applied to extensions and IP endpoints, detailing profile names, descriptions, associated Telephony Server profile bindings, and modification history.
![Device Profiles List](/screenshots/settings/technology/device-profiles-list.png)

### Device Profile Configuration Form
Granular configuration form for provisioning and extension registration templates, enabling administrators to define NAT traversal parameters, codec negotiation hierarchies, TLS encryption, and custom Sofia directory variables.
![Device Profile Form](/screenshots/settings/technology/device-profiles-form.png)

---

## 1. Module Overview (Technical)

### What Are Device SIP Profiles?

Device SIP Profiles are **provisioning templates** that define SIP parameters for devices (IP phones, softphones, WebRTC clients). Unlike SIP Profiles (which configure Telephony Server), Device SIP Profiles configure how individual device registrations are handled with specific NAT, codec, and security settings.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│               Device SIP Profiles Architecture                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Device SIP Profiles                               │   │
│  │                                                          │   │
│  │  Templates:                                              │   │
│  │  ├─ LAN Phones (NAT disabled, UDP)                      │   │
│  │  ├─ Remote Phones (NAT enabled, TLS)                    │   │
│  │  └─ WebRTC Clients (WSS, DTLS, ICE)                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Assigned to devices                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Extensions / Devices                              │   │
│  │                                                          │   │
│  │  Extension 1001 → LAN Phones profile                    │   │
│  │  Extension 1002 → Remote Phones profile                 │   │
│  │  Extension 1003 → WebRTC Clients profile                │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Applied during registration                            │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Telephony Server                                        │   │
│  │                                                          │   │
│  │  Device registers → Profile settings applied:           │   │
│  │  ├─ NAT handling                                        │   │
│  │  ├─ Codec preferences                                   │   │
│  │  ├─ Security (TLS, SRTP)                                │   │
│  │  └─ SIP headers                                         │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 1.1 Dynamic Profile Inheritance vs Explicit Override (`None` / Inherit from Profile)

### How `None (inherit from profile)` Works
When creating or editing an extension, the **SIP Profile** field defaults to `None (inherit from profile)` (`sip_profile_id = null`).

* **Dynamic Transport Auto-Detection**: Without static device profile overrides in the user's directory XML, Telephony Server's Sofia `internal` profile auto-detects the connecting transport:
  * **UDP (Port 5060)**: Automatically negotiates standard RTP for physical desk phones (Yealink, Grandstream, Cisco).
  * **WebSocket / WSS (Port 7443)**: Automatically enables DTLS-SRTP, ICE candidates, and RTCP-mux for browser-based WebRTC clients.
* **Hybrid Simultaneous Registration**: Leaving the profile as `None` allows the **same extension** to be registered simultaneously on a physical desk phone and a web browser app without configuration conflicts.

### When to Assign an Explicit Device Profile
Assign an explicit profile (e.g., `Default Internal` or `Default WebRTC`) **only when you need to enforce static overrides** for specific endpoints, such as:
* Forcing a specific re-registration interval (e.g. 120 seconds).
* Forcing strict codec constraints or disabling media transcoding.
* Enforcing custom network ACLs (`authAcl`) or bypass media policies.

---

## 2. Module Overview (Commercial/Business)

### Business Value

Device SIP Profiles provides **device-specific configuration**:

| Without Device Profiles | With Device Profiles |
|-------------------------|---------------------|
| One-size-fits-all | Tailored per device type |
| NAT issues | Proper NAT handling |
| Security gaps | TLS/SRTP per profile |
| Codec problems | Optimized codecs |

### Use Cases

1. **LAN Phone Deployment**
   - Disable NAT traversal
   - Use all codecs

2. **Remote Workers**
   - Enable aggressive NAT
   - Require TLS/SRTP

3. **WebRTC Clients**
   - Enable WSS, ICE, DTLS
   - Configure RTCP-mux

4. **Legacy Devices**
   - Adjust for compatibility
   - Specific codec order

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Templates** | Reusable configurations |
| **NAT Settings** | Handle any network |
| **Codec Control** | Optimize quality |
| **Security Options** | TLS, SRTP, DTLS |
| **WebRTC Support** | Browser clients |
| **Per-Device** | Granular control |

---

## 3. Module Overview (End User/Administrator)

### What Can You Do?

- Create device SIP profile templates
- Configure NAT traversal settings
- Set codec preferences
- Enable security (TLS, SRTP)
- Configure WebRTC support
- Assign profiles to devices/extensions

### Device SIP Profiles Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              Device SIP Profiles                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [+ Create Device Profile]                                      │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Profile Name     │ Description          │ Usage │ Status │  │
│  ├──────────────────┼──────────────────────┼───────┼────────┤  │
│  │ LAN Phones       │ Local office phones  │ 45    │ ✓ On   │  │
│  │ Remote Phones    │ Work from home       │ 20    │ ✓ On   │  │
│  │ WebRTC Clients   │ Browser softphone    │ 15    │ ✓ On   │  │
│  │ Legacy ATA       │ Older analog adapters│ 5     │ ✓ On   │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Profile Edit View

```
┌─────────────────────────────────────────────────────────────────┐
│              Edit Device Profile: WebRTC Clients                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Profile Name: [WebRTC Clients                  ]               │
│  Description: [Browser-based softphones         ]               │
│  Sofia Profile: [internal-tls ▼]                                │
│  Enabled: ✓                                                     │
│                                                                 │
│  ▼ Network                                                      │
│  ├─ Authentication ACL: [ANY ▼]                                │
│  └─ Force Register Domain: ✓                                   │
│                                                                 │
│  ▼ NAT Traversal                                                │
│  ├─ Aggressive NAT Detection: ✓                                │
│  ├─ Rewrite Contact Header: ✓                                  │
│  └─ Force rport: ✓                                             │
│                                                                 │
│  ▼ Media Control                                                │
│  ├─ RTP Timeout (Seconds): [300               ]                │
│  ├─ Bypass Media: ☐                                            │
│  └─ Disable Transcoding: ☐                                     │
│                                                                 │
│  ▼ Codec Preferences                                            │
│  ├─ Inbound Codecs: [OPUS, PCMU, PCMA ▼]                       │
│  ├─ Outbound Codecs: [OPUS, PCMU, PCMA ▼]                      │
│  └─ DTMF Method: [RFC 2833 ▼]                                  │
│                                                                 │
│  ▼ Transport & Security                                         │
│  ├─ Enable WebSocket (WS): ☐                                   │
│  ├─ Enable Secure WebSocket (WSS): ✓                           │
│  ├─ Enable TLS: ✓                                              │
│  └─ TLS Only Mode: ✓                                           │
│                                                                 │
│  ▼ Security & RTP                                               │
│  ├─ Enable DTLS-SRTP: ✓                                        │
│  ├─ Enable ICE NAT Traversal: ✓                                │
│  ├─ Enable RTCP Multiplexing: ✓                                │
│  └─ Secure RTP (SRTP) Mode: [Always Use SRTP ▼]                │
│                                                                 │
│  [Save] [Cancel]                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **WebRTC**: Enable WSS, DTLS, ICE, and RTCP-mux for browser clients.

> [!TIP]
> **Remote Workers**: Enable aggressive NAT detection and TLS.

> [!NOTE]
> **Usage Count**: Shows how many devices use this profile.

---

## 🎯 User Roles & Key Capabilities

| Role | Permissions | Key Capabilities |
|------|-------------|------------------|
| **Super Administrator** | Full Access (`read`, `write`, `delete`, `clone`) | Create global and domain-specific device templates, configure default WebRTC/TLS media profiles, and manage encryption rules. |
| **PBX Administrator** | Domain Management (`read`, `write`) | Assign device profiles to extensions, customize codec ordering (e.g. OPUS first), and enforce aggressive NAT detection for remote softphones. |
| **Provisioning Specialist** | Operational (`read`, `write`) | Create vendor-tailored device profiles for Yealink, Grandstream, Polycom, and Cisco physical IP phones. |
| **Support Specialist** | Read & Diagnostic (`read`) | Inspect extension device profile assignments, verify DTLS/SRTP settings, and diagnose media negotiation failures. |

---

## 4. Configuration Categories

### Network

| Setting | Description |
|---------|-------------|
| **Authentication ACL** | LAN, WAN, or ANY |
| **Force Register Domain** | Lock registration domain |

### NAT Traversal

| Setting | Description |
|---------|-------------|
| **Aggressive NAT Detection** | Deep NAT inspection |
| **Rewrite Contact Header** | Fix Contact for NAT |
| **Force rport** | Use source port |

### Media Control

| Setting | Description |
|---------|-------------|
| **RTP Timeout** | Inactivity timeout |
| **RTP Hold Timeout** | Hold inactivity timeout |
| **Bypass Media** | Direct RTP between devices |
| **Disable Transcoding** | Allow asymmetric codecs |
| **Session Timeout** | Maximum call duration |

### Codec Preferences

| Setting | Description |
|---------|-------------|
| **Inbound Codec Prefs** | Incoming codec priority |
| **Outbound Codec Prefs** | Outgoing codec priority |
| **DTMF Method** | RFC2833, SIP INFO, In-band |
| **RFC2833 Payload Type** | DTMF RTP payload |

### SIP Headers

| Setting | Description |
|---------|-------------|
| **Send Remote-Party-ID** | Include RPID header |
| **Send P-Asserted-Identity** | Include PAI header |
| **Send SIP Diversion** | Include Diversion header |
| **SIP Caller ID Type** | None, PAI, or RPID |

### Transport & Security

| Setting | Description |
|---------|-------------|
| **Enable WebSocket** | WS for debugging |
| **Enable Secure WebSocket** | WSS for browsers |
| **Enable TLS** | Encrypted signaling |
| **TLS Only Mode** | Require TLS |
| **Registration Expires** | Re-registration interval |
| **TLS Verify Policy** | Certificate validation |

### Security & RTP

| Setting | Description |
|---------|-------------|
| **Enable DTLS-SRTP** | Encrypted media (WebRTC) |
| **Enable ICE** | NAT traversal for WebRTC |
| **Enable RTCP-mux** | Share RTP/RTCP port |
| **Secure RTP Mode** | Always, Optional, Never |
| **Require Secure Media** | Enforce SRTP |

---

## 5. Settings Reference

### Profile Types

| Profile Type | Key Settings |
|--------------|--------------|
| **LAN Phones** | NAT off, UDP, all codecs |
| **Remote Phones** | NAT on, TLS, SRTP |
| **WebRTC Clients** | WSS, ICE, DTLS, RTCP-mux |
| **Legacy ATA** | Basic codecs, relaxed NAT |

### WebRTC Requirements

| Setting | Value |
|---------|-------|
| **WSS** | ✓ Required (via Nginx proxy on port 443) |
| **DTLS-SRTP** | ✓ Required |
| **ICE** | ✓ Required |
| **RTCP-mux** | ✓ Required |
| **Codecs** | OPUS preferred |

> [!NOTE]
> WebRTC clients connect via `wss://domain/ws` on port 443. Nginx terminates TLS and forwards plain WebSocket to Telephony Server on `127.0.0.1:5066`. No separate WSS port is needed on Telephony Server.

### Security Levels

| Level | TLS | SRTP | Use Case |
|-------|-----|------|----------|
| **None** | ☐ | ☐ | LAN only |
| **Signaling** | ✓ | ☐ | Basic security |
| **Full** | ✓ | ✓ | Remote/WFH |
| **Maximum** | ✓ | Required | High security |

---

## 6. Common Scenarios & Examples

### Scenario 1: LAN Office Phones

1. Create new profile
2. Set Authentication ACL = LAN
3. Disable NAT settings
4. Set codecPrefs = PCMU,PCMA,G722
5. Save and assign to extensions

### Scenario 2: Remote Worker

1. Create new profile
2. Enable Aggressive NAT Detection
3. Enable Rewrite Contact, Force rport
4. Enable TLS and SRTP
5. Save and assign

### Scenario 3: WebRTC Softphone

1. Create new profile
2. Set Authentication ACL = ANY
3. Enable all NAT options
4. Enable WSS, DTLS, ICE, RTCP-mux
5. Set codecs to OPUS
6. DTMF = RFC2833

> [!NOTE]
> WebRTC connection flow: Browser → `wss://domain/ws` (Nginx, port 443) → `ws://127.0.0.1:5066` (Telephony Server). TLS is handled by Nginx.

### Scenario 4: Legacy ATA

1. Create new profile
2. Basic NAT settings
3. Set codecs = PCMU,PCMA only
4. Set DTMF = Inband or INFO
5. Longer timeouts

---

## 7. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **Profile Assignment**: Profiles are assigned to extensions/devices.

> [!NOTE]
> **Sofia Profile**: Must select base SIP profile (internal/external).

> [!WARNING]
> **Cannot Delete In-Use**: Profiles with assigned devices cannot be deleted.

### Best Practices

1. **Create Per Type**: Different profiles for different device types
2. **Test Thoroughly**: Test NAT settings before deployment
3. **Security First**: Use TLS/SRTP for remote devices
4. **Codec Matching**: Match codecs to device capabilities
5. **Document Profiles**: Note what each profile is for

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| Registration fails | Wrong ACL | Check Authentication ACL |
| One-way audio | NAT issues | Enable NAT options |
| No audio | Codec mismatch | Check codec preferences |
| WebRTC not working | Missing WSS/ICE | Enable WebRTC settings |
| DTMF not working | Wrong DTMF type | Change DTMF method |

### WebRTC Checklist

| Setting | Required |
|---------|----------|
| Enable WSS | ✓ |
| Enable DTLS-SRTP | ✓ |
| Enable ICE | ✓ |
| Enable RTCP-mux | ✓ |
| Secure RTP | Optional or Always |
| Codecs | Include OPUS |

### NAT Checklist

| Setting | Remote Devices |
|---------|----------------|
| Aggressive NAT Detection | ✓ |
| Rewrite Contact | ✓ |
| Force rport | ✓ |

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **Device Profile** | SIP settings template for devices |
| **NAT** | Network Address Translation |
| **SRTP** | Secure Real-time Transport Protocol |
| **DTLS** | Datagram TLS for media |
| **ICE** | Interactive Connectivity Establishment |
| **WSS** | WebSocket Secure |
| **RTCP-mux** | RTP/RTCP on same port |
| **OPUS** | High-quality audio codec |

---

## Model Context Protocol (MCP) AI Integration

The Ring2All PBX platform integrates deep AI assistance via the Model Context Protocol (MCP). The Device SIP Profiles module exposes intelligent tools allowing the PBX AI Copilot to query available device templates, analyze codec and NAT profiles, and recommend optimal settings for IP phones, softphones, and browser-based WebRTC endpoints.

### Available MCP Tools

| Tool Name | Operation Type | RBAC Risk Level | Description |
|-----------|----------------|-----------------|-------------|
| `list_device_sip_profiles` | Read / Query | `low` | Lists Directory / Device SIP Profiles (configuration templates for physical IP phones, softphones, and WebRTC clients) with domain isolation. |
| `diagnose_media_nat` | Diagnostic / Query | `low` | Performs deep operational diagnostic on VoIP media, RTP audio flow, and NAT traversal: checks Sofia profile IP parameters (`ext-rtp-ip`), detects RFC1918 private IP leaks in SDP, verifies UDP 16384-32768 port availability, and detects one-way audio/silence on live channels. |

### Tool Input Schemas & Parameters

#### 1. `list_device_sip_profiles`
```json
{
  "name": "list_device_sip_profiles",
  "description": "List Directory / Device SIP Profiles (configuration templates for physical IP phones, softphones, and WebRTC clients).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter by device profile name or description (e.g. 'WebRTC', 'Internal Phones')."
      }
    }
  }
}
```

#### 2. `diagnose_media_nat`
```json
{
  "name": "diagnose_media_nat",
  "description": "Perform deep diagnostic on VoIP media, RTP audio flow, and NAT traversal (Sofia ext-rtp-ip, RFC1918 SDP leaks, one-way audio detection).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "callUuid": {
        "type": "string",
        "description": "Optional active or recent call UUID to inspect live RTP packet counters."
      },
      "extension": {
        "type": "string",
        "description": "Optional extension number to inspect SIP registration NAT contact."
      }
    }
  }
}
```

### Natural Language Prompts

| User Request | Invoked MCP Tool | Expected AI Response |
|--------------|------------------|----------------------|
| *"List all device SIP profiles available for our extensions."* | `list_device_sip_profiles` | Returns profile list (`Default Internal`, `Default WebRTC`, `Default External`) with base profile mappings. |
| *"Do we have a device profile configured for WebRTC softphones?"* | `list_device_sip_profiles({ search: "WebRTC" })` | Locates and displays WebRTC profile details, verifying WSS, DTLS, and ICE status. |
| *"Which device profile should be assigned to remote teleworkers behind NAT?"* | `list_device_sip_profiles` | Recommends `Default External` with aggressive NAT detection and rewrite contact enabled. |

### Multi-Tenant & Security Safeguards

- **Strict Domain Isolation**: Device profiles are queried within the caller's active domain (`domain_id`) or global system defaults (`domain_id IS NULL`), ensuring complete tenant boundary separation.
- **Anti-Collision Protection**: Device profile names are uniquely enforced within their domain to avoid collision across extension assignments.
- **Secure Media Verification**: WebRTC profiles are validated for mandatory DTLS-SRTP and encryption compliance before activation.
- **Audit Logging**: All administrative profile views and updates are recorded in the central audit ledger.

---

*Documentation last updated: January 2026*