---
title: "Push Notifications (RFC 8599)"
description: "Documentation for Push Notifications"
---

## Table of Contents
1. [Overview & Mobile Push Architecture](#1-overview--mobile-push-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Field Reference & Provider Parameters](#5-field-reference--provider-parameters)
6. [RFC 8599 SIP Signaling & Wake-up Flow](#6-rfc-8599-sip-signaling--wake-up-flow)
7. [Apple APNs vs Google FCM v1 Requirements](#7-apple-apns-vs-google-fcm-v1-requirements)
8. [Troubleshooting & Verification](#8-troubleshooting--verification)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & Mobile Push Architecture

In **Ring2All SBC**, the **Push Notifications** module implements standard **RFC 8599 (SIP Push Notification)** mechanics to deliver inbound voice and video calls to suspended or terminated mobile softphones on iOS and Android. By integrating directly with **Apple Push Notification service (APNs)** via HTTP/2 and **Google Firebase Cloud Messaging (FCM v1)** via Google OAuth2 service accounts, the SBC eliminates the need for mobile clients to maintain persistent, battery-draining background TCP sockets.

```
Mobile Softphone (iOS/Android)              Ring2All SBC                  Apple APNs / Google FCM
      │                                          │                                   │
      │─── REGISTER with RFC 8599 params ───────>│                                   │
      │    (+sip.pns, +sip.pns-prid="token")     │─── Store Push Token in usrloc ────│
      │<── 200 OK ───────────────────────────────│                                   │
      │                                          │                                   │
      │ [App goes to sleep / background]         │                                   │
      │                                          │                                   │
      │                                  Incoming SIP INVITE                         │
      │                                          │─── Dispatch Push Wake-up Payload ─>│
      │                                          │    (High-Priority VoIP)           │
      │                                          │                                   │
      │◄── Woken up via APNs VoIP / FCM ─────────┼───────────────────────────────────┘
      │─── Fresh REGISTER / Re-attach ──────────>│
      │<── 200 OK ───────────────────────────────│
      │<── Forwarded SIP INVITE ─────────────────│
      │─── 180 Ringing / 200 OK ────────────────>│
```

When an `INVITE` targets an inactive mobile subscriber, the SBC holds the incoming call in transaction memory (`t_suspend`), dispatches an immediate high-priority push notification payload, and forwards the call the moment the mobile softphone awakens and refreshes its SIP registration.

---

## 2. Business & Operational Significance

* **Guaranteed Mobile Call Delivery**: Ensures that field workers, executives, and remote call center agents never miss incoming calls due to aggressive mobile OS battery optimization (Doze mode, iOS suspension).
* **Massive Battery Life Savings**: Relieves client applications from sending 30-second SIP keepalive packets over cellular data, reducing device battery consumption by up to 80%.
* **Immediate Native Call Screen**: Triggers Apple CallKit or Android Telecom framework immediately upon push arrival, offering users a native incoming call interface.
* **Standards-Based Interoperability**: Implements RFC 8599 URI parameters (`pn-provider`, `pn-prid`, `pn-param`), providing plug-and-play compatibility with modern softphones (e.g., Linphone, Bria, Grandstream Wave, Acrobits, and Ring2All Mobile).

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **Mobile Solutions Architect** | Push Integration Design | Configure APNs and FCM authentication profiles, manage certificates, and align softphone bundle IDs. |
| **SBC Telephony Engineer** | Wake-up Timer Optimization | Tune transaction suspension delays (`t_suspend` timeout) to balance caller ring time with mobile network latency. |
| **Mobile App Developer** | Push Payload Validation | Verify push tokens received in SIP `REGISTER` Contact headers and validate JSON push notification structures. |
| **Enterprise Telecom Administrator** | Provider Health Monitoring | Audit push delivery success rates, monitor provider token expiration, and verify gateway connectivity. |
| **AI Mobile Telephony Copilot / NOC Agent** | Push Telemetry & Timeout Governance | Audit mobile push provider configurations, inspect RFC 8599 suspension timers, and tune wake-up ring limits via MCP. |

---

## 4. Visual Interface & Layout

The Push Notifications interface consists of a providers list displaying all configured push gateways, along with a modal configuration form for setting up APNs tokens and Google service account keys.

### 4.1 Push Notification Providers List View
Displays active push notification providers, supported platforms, environments, and registration statistics.

![Push Notification Providers List View](/screenshots/sbc/settings/technology/push-notifications/push-notifications-list.png)

### 4.2 Provider Configuration Form
Configuration modal for provisioning credentials, keys, bundle identifiers, and wake-up timers.

![Push Provider Configuration Form](/screenshots/sbc/settings/technology/push-notifications/push-provider-form.png)

---

## 5. Field Reference & Provider Parameters

| Field Name | Type | Options / Format | Description |
| :--- | :--- | :--- | :--- |
| **Provider Name** | String | Text (e.g., `Apple APNs VoIP Production`) | Friendly label for identifying this notification gateway profile. |
| **Push Platform** | Select | `Apple (APNs)` / `Google (FCM)` | Target notification ecosystem. |
| **Environment** | Select | `Production` / `Development / Sandbox` | Target gateway environment. APNs production uses `api.push.apple.com`. |
| **Authentication Type** | Select | `Token Key (.p8)` / `Service Account (.json)` | Modern JWT key authentication for APNs, or JSON private key credentials for Google FCM v1. |
| **Bundle ID / App ID** | String | `com.ring2all.softphone.voip` | Explicit application bundle identifier registered in Apple Developer or Google Play Console. |
| **Team ID / Project ID** | String | `10-digit Alphanumeric / String` | Apple Developer Team ID or Google Cloud Project ID. |
| **Key ID** | String | `10-digit Key Identifier` | APNs Signing Key ID associated with the uploaded `.p8` file. |
| **Private Key / Secret** | File / Text | PEM / JSON string | The actual `.p8` private key or Google Cloud Service Account JSON credentials. |
| **Wake-up Timeout (ms)** | Integer | `3000` to `8000` (Default `4000`) | Maximum duration the SBC will suspend an incoming `INVITE` waiting for the device to register. |

---

## 6. RFC 8599 SIP Signaling & Wake-up Flow

During initial registration, the mobile application provides push parameters in the SIP `Contact` header:

```text
REGISTER sip:sbc.ring2all.com SIP/2.0
Via: SIP/2.0/TLS 192.168.1.150:5061;branch=z9hG4bK-718291
From: <sip:2000@sbc.ring2all.com>;tag=981273912
To: <sip:2000@sbc.ring2all.com>
Contact: <sip:2000@192.168.1.150:5061;transport=tls>;
  +sip.pns="apns";
  +sip.pns-provider="apns";
  +sip.pns-prid="8e71b2a904128...c041";
  +sip.pns-param="com.ring2all.softphone.voip";
Expires: 3600
```

When Kamailio receives an `INVITE` for `sip:2000@sbc.ring2all.com`:
1. It queries `usrloc` for the contact. If the device socket is closed or marked dormant, Kamailio executes `t_suspend()`.
2. The SBC dispatches an HTTP/2 POST request to `https://api.push.apple.com/3/device/8e71b2a9...`:
   ```json
   {
     "aps": {
       "alert": "Incoming Call",
       "content-available": 1
     },
     "call_id": "8120391-ab12@sbc",
     "caller_name": "Support Queue",
     "caller_number": "+14155552671"
   }
   ```
3. The mobile OS receives the VoIP push, invokes CallKit/Incoming Call UI, and immediately sends a fresh `REGISTER`.
4. Kamailio matches the new registration with the suspended transaction via `t_continue()` and delivers the `INVITE`.

---

## 7. Apple APNs vs Google FCM v1 Requirements

### Apple iOS VoIP Push (PushKit)
* **HTTP/2 Connection**: All APNs communications mandate TLS 1.2+ over persistent HTTP/2 sockets using JWT authentication (`ES256` signed tokens).
* **Mandatory CallKit Reporting**: iOS requires that every VoIP push notification immediately reports an incoming call to `CXProvider` (`reportNewIncomingCall`). Failure to report within 5 seconds causes iOS to terminate the application.

### Google Firebase Cloud Messaging (FCM v1 API)
* **OAuth 2.0 Token Exchange**: The legacy FCM server key API is deprecated. Ring2All SBC natively implements FCM HTTP v1 using short-lived OAuth 2.0 access tokens generated via Google Service Account credentials.
* **High Priority Message Flag**: Voice wake-up payloads are marked with `android.priority: HIGH` to bypass Doze mode restrictions instantly.

---

## 8. Troubleshooting & Verification

### Validating Push Token Registration
Check that registered endpoints include RFC 8599 push attributes using the **RPC Console**:
```bash
ul.dump
```
Look for `+sip.pns` and `+sip.pns-prid` in the contact parameters list.

### Inspecting Push Notification Delivery Logs
View push dispatcher event logs in syslog:
```bash
grep -i "push_notification" /var/log/kamailio.log
```
Successful dispatch sample:
```text
INFO: <script>: [PUSH] APNs VoIP push sent successfully to token 8e71b2... (HTTP 200 OK, latency=84ms)
```

---

## 9. Model Context Protocol (MCP) AI Integration

The RFC 8599 Push Notification module integrates with the Model Context Protocol (MCP) to allow diagnostic agents to inspect push provider configurations, audit registration tokens, and safely tune wake-up ring timeouts.

### Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `list_push_providers` | Status Query | `read` | List all mobile push notification providers (Apple APNs VoIP & Google FCM v1) configured in the SBC. |
| `get_push_settings` | Status Query | `read` | Retrieve RFC 8599 push configuration including transaction suspension timeouts and auto-wake behavior. |
| `update_push_settings` | Configuration Mutation | `operational` | Adjust SIP transaction hold timeout or auto-wake behavior for incoming calls directed to mobile softphones. |

### Tool Schemas & Payloads

#### 1. `list_push_providers`

##### Input Schema
```json
{
  "type": "object",
  "properties": {}
}
```

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "totalProviders": 2,
    "providers": [
      {
        "id": 1,
        "type": "Apple APNs (VoIP Push)",
        "name": "Apple APNs Production",
        "bundleId": "com.ring2all.softphone.voip",
        "environment": "production",
        "status": "active",
        "createdAt": "2026-09-01T10:00:00.000Z"
      },
      {
        "id": 2,
        "type": "Google FCM v1",
        "name": "Google FCM Production",
        "bundleId": "com.ring2all.softphone",
        "environment": "production",
        "status": "active",
        "createdAt": "2026-09-01T10:05:00.000Z"
      }
    ]
  }
}
```

#### 2. `get_push_settings`

##### Input Schema
```json
{
  "type": "object",
  "properties": {}
}
```

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "enabled": true,
    "ringTimeoutSec": "8s",
    "autoWakeInbound": true,
    "sendCallerInfo": true,
    "standard": "RFC 8599 (SIP Push Notification Mechanism for Push-to-Talk and VoIP)"
  }
}
```

#### 3. `update_push_settings`

##### Input Schema
```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Enable or disable RFC 8599 push notification subsystem."
    },
    "ringTimeoutSec": {
      "type": "number",
      "description": "Seconds to hold SIP INVITE transaction while waiting for mobile device wakeup (default: 8)."
    },
    "autoWakeInbound": {
      "type": "boolean",
      "description": "Automatically send VoIP push notification when an incoming call arrives for a registered mobile softphone."
    }
  }
}
```

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "message": "SIP Push Notification settings updated successfully!"
  }
}
```

### Natural Language AI Prompts

#### English Examples
* *"List all configured mobile push notification providers and their environment status."*
* *"What is the current RFC 8599 SIP transaction hold timeout for mobile endpoints?"*
* *"Update the mobile push wake-up timeout to 6 seconds and ensure auto-wake is enabled."*

#### Spanish Examples (Español)
* *"Lista todos los proveedores de notificaciones push móviles configurados y su estado de entorno."*
* *"¿Cuál es el tiempo de retención de transacción SIP RFC 8599 actual para endpoints móviles?"*
* *"Actualiza el tiempo de espera de activación push móvil a 6 segundos y asegura que auto-wake esté habilitado."*

### Enterprise Safeguards & Access Governance
1. **Secret Redaction**: Private `.p8` keys and Google Service Account credential secrets are never returned in MCP query responses.
2. **Transaction Timer Guardrails**: The `ringTimeoutSec` parameter is bounded between 3 and 15 seconds to avoid transaction memory bloat.
3. **Non-Blocking Push Queuing**: Push payloads are dispatched via asynchronous HTTP/2 client threads without delaying core SIP worker routines.

---

## 10. Glossary

* **RFC 8599**: The IETF specification governing Push Notification Mechanisms for the Session Initiation Protocol (SIP).
* **PushKit / APNs VoIP**: Apple's dedicated push framework for voice applications that bypasses standard notification centers to wake up apps directly.
* **FCM v1**: Google’s current, secure REST API for delivering cloud-to-device push messages on Android.
* **Transaction Suspension (`t_suspend`)**: Freezing a SIP transaction in Kamailio memory without holding OS worker threads while waiting for an external wake-up event.