Push Notifications (RFC 8599)

Overview & Mobile Push Architecture
Business & Operational Significance
🎯 User Roles & Key Capabilities
Visual Interface & Layout
Field Reference & Provider Parameters
RFC 8599 SIP Signaling & Wake-up Flow
Apple APNs vs Google FCM v1 Requirements
Troubleshooting & Verification
Model Context Protocol (MCP) AI Integration
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

4.2 Provider Configuration Form

Configuration modal for provisioning credentials, keys, bundle identifiers, and wake-up timers.

Push Provider Configuration Form

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:

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:

It queries usrloc for the contact. If the device socket is closed or marked dormant, Kamailio executes t_suspend().

The SBC dispatches an HTTP/2 POST request to https://api.push.apple.com/3/device/8e71b2a9...:

{
  "aps": {
    "alert": "Incoming Call",
    "content-available": 1
  },
  "call_id": "8120391-ab12@sbc",
  "caller_name": "Support Queue",
  "caller_number": "+14155552671"
}

The mobile OS receives the VoIP push, invokes CallKit/Incoming Call UI, and immediately sends a fresh REGISTER.
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:

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:

grep -i "push_notification" /var/log/kamailio.log

Successful dispatch sample:

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

{
  "type": "object",
  "properties": {}
}

Output Payload Example

{
  "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

{
  "type": "object",
  "properties": {}
}

Output Payload Example

{
  "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

{
  "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

{
  "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

Secret Redaction: Private .p8 keys and Google Service Account credential secrets are never returned in MCP query responses.
Transaction Timer Guardrails: The ringTimeoutSec parameter is bounded between 3 and 15 seconds to avoid transaction memory bloat.
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.

Push Notifications (RFC 8599)

Table of Contents

1. Overview & Mobile Push Architecture

2. Business & Operational Significance

3. 🎯 User Roles & Key Capabilities

4. Visual Interface & Layout

4.1 Push Notification Providers List View

4.2 Provider Configuration Form

5. Field Reference & Provider Parameters

6. RFC 8599 SIP Signaling & Wake-up Flow

7. Apple APNs vs Google FCM v1 Requirements

Apple iOS VoIP Push (PushKit)

Google Firebase Cloud Messaging (FCM v1 API)

8. Troubleshooting & Verification

Validating Push Token Registration

Inspecting Push Notification Delivery Logs

9. Model Context Protocol (MCP) AI Integration

Available MCP Tools

Tool Schemas & Payloads

1. list_push_providers

Input Schema

Output Payload Example

2. get_push_settings

Input Schema

Output Payload Example

3. update_push_settings

Input Schema

Output Payload Example

Natural Language AI Prompts

English Examples

Spanish Examples (Español)

Enterprise Safeguards & Access Governance

10. Glossary

1. `list_push_providers`

2. `get_push_settings`

3. `update_push_settings`