3CX Mobile Push Notification Architecture: Managing Apple APNs and Google FCM Integration

Overview

Key takeaways

• Understand how 3CX relies on cloud push proxies to wake mobile clients without maintaining active background SIP registrations.
• Identify the call flow mechanics from initial SIP INVITE through APNs/FCM payload delivery to client re-registration.
• Configure necessary outbound firewall rules (Port 443, 5228-5230, 2197) to allow unimpeded communication between PBX, push gateways, and handsets.
• Diagnose push delivery failures using 3CX Activity Logs, licensing status, and device-level push token verifications.

Prerequisites

• Basic understanding of SIP signaling (REGISTER, INVITE) and mobile OS background processing constraints.
• Administrative access to a 3CX Management Console running v18 or v20 with active maintenance or subscription.
• Firewall access to modify outbound security rules for the 3CX PBX host.

Guide

1. section #1

   Architectural Need for Push in Mobile VoIP

   Background SIP Limitations

   Standard SIP REGISTER mechanisms require persistent TCP or TLS socket connections. Mobile operating systems aggressively terminate long-running background sockets to preserve battery life and optimize system memory.

   OS-Level Background Restrictions

   Both Apple iOS (via PushKit) and Google Android (via Doze Mode and App Standby) restrict unprivileged background processes from maintaining continuous network listeners.

   The Push Gateway Solution

   By offloading client monitoring to cloud notification networks, 3CX eliminates the need for constant background polling:

   • Eliminates excess mobile battery consumption
   • Ensures reliable wake-up triggers even during deep sleep
   • Simplifies NAT traversal across changing cellular networks
2. section #2

   3CX Push Architecture and Gateway Relay

   Centralized Gateway Routing

   3CX uses a centralized cloud gateway (3CX Push Proxy) to bridge local PBX instances with official push networks. This design avoids requiring every PBX instance to maintain direct developer credentials with Apple and Google.

   Payload Generation

   When an inbound call targets an offline or backgrounded extension, the local PBX sends an API call to the 3CX Push Gateway containing:

   • Target device push token
   • Encrypted call metadata (Caller ID, Call-ID)
   • Application bundle identifier

   APNs and FCM Relay

   The 3CX Push Gateway authenticates with Apple APNs and Google FCM, converting the PBX payload into platform-native push notifications for immediate delivery.

   jsoncopy

   {
     "push_gateway": "https://push.3cx.com/v1/notify",
     "recipient_token": "f7a8b9c0d1e2...",
     "platform": "apns",
     "payload": {
       "aps": {
         "apns-push-type": "voip",
         "alert": { "loc-key": "INCOMING_CALL", "loc-args": ["Sales Queue"] }
       },
       "call_id": "987654321@pbx.example.com"
     }
   }

3. section #3

   Call Flow Sequence from SIP INVITE to App Wake-Up

   Initial Signaling and Hold State

   When a call arrives at the 3CX PBX targeting a mobile extension:

   • The PBX places the inbound SIP INVITE in a temporary waiting queue.
   • The PBX issues an asynchronous HTTP payload to the 3CX Push Service.

   Operating System Reaction

   Upon receiving the push payload from APNs or FCM, the mobile OS wakes the app:

   • iOS: PushKit wakes the 3CX app and immediately triggers CallKit to present the native call screen.
   • Android: FCM High-Priority message wakes the 3CX background service to bring up the incoming call interface.

   Re-Registration and Handshake

   Once awakened, the 3CX app executes a rapid re-connection sequence:

   • Establishes a TLS session to the 3CX Tunnel/SIP port
   • Issues a SIP REGISTER
   • Sends a SIP 200 OK response to accept the queued SIP INVITE
4. section #4

   Network and Firewall Requirements for Push Services

   Outbound PBX Requirements

   For push dispatch to function, the 3CX PBX server must have unrestricted outbound access to 3CX Cloud Infrastructure and public push endpoints.

   Network Port Requirements

   Ensure the external firewall permits the following outbound destinations:

   • Port 443 (HTTPS): Communication between PBX and push.3cx.com, as well as Google FCM REST APIs.
   • Ports 5228-5230 (TCP): Utilized by Android devices to maintain connection with Google Play Services.
   • Port 2197 (TCP): Used for APNs outbound communication.

   Mobile Client Transport

   After wake-up, the mobile app must quickly connect back to the PBX:

   • Port 5090 (TCP/UDP): 3CX Tunnel Protocol (combines SIP and RTP traffic)
   • Port 5061 (TCP): Direct SIP over TLS (if Tunnel is disabled)
5. section #5

   Diagnosing and Troubleshooting Push Failures

   Token Registration Verification

   Verify that the target mobile client has successfully registered its push token with the PBX:

   • In 3CX Admin Console, navigate to Users > Extension.
   • Check the Phone Provisioning or 3CX App tab to verify an active Push Token exists.

   Identifying Push Delivery Issues

   Common root causes for push failure include:

   • Expired Subscription: License expiration disables 3CX Push Gateway access.
   • Battery Optimization Override: Vendor-specific OS settings (e.g., Samsung, Xiaomi) killing background tasks.
   • Firewall Blocking: Outbound HTTPS requests to push.3cx.com dropped at the PBX perimeter.

   Reading 3CX Activity Logs

   Set logging to Verbose under Diagnostics and search for Push entries to track dispatch status codes returned by the gateway.

   textcopy

   10/24/2023 10:15:32.102 | [CM503025]: Call(v/1): Calling Push connection for extension 101 [Device: 3CX App iOS]
   10/24/2023 10:15:32.345 | Push request dispatched successfully to https://push.3cx.com/v1/notify (Status: 200 OK)
   10/24/2023 10:15:33.012 | Mobile App 101 registered dynamically from 192.0.2.45:5090 via 3CX Tunnel

Further reading

• https://www.3cx.com/docs/manual/net-configs/
• https://developer.apple.com/documentation/usernotifications/
• https://firebase.google.com/docs/cloud-messaging