VoIP push notifications

• Registering VoIP tokens in your app using Apple PushKit
• Creating a dedicated OneSignal app with a VoIP Services Certificate
• Registering tokens and sending pushes through the OneSignal REST API

​

Platform differences

​

iOS: send VoIP push notifications

1

Register a VoIP token using PushKit

Use Apple’s PushKit framework to register for VoIP notifications and receive a VoIP token.

• Implement PushKit in your app
• Store and refresh the VoIP token as Apple rotates it
• Follow Apple’s VoIP policies closely

Example: PushKit delegate implementation

import PushKit

class AppDelegate: NSObject, PKPushRegistryDelegate {
    func registerForVoIPPushes() {
        let registry = PKPushRegistry(queue: .main)
        registry.delegate = self
        registry.desiredPushTypes = [.voIP]
    }

    func pushRegistry(_ registry: PKPushRegistry, didUpdatePushCredentials credentials: PKPushCredentials, for type: PKPushType) {
        let token = credentials.token.map { String(format: "%02x", $0) }.joined()
        // Pass this token to OneSignal — see Step 4
    }
}

This is standard Apple PushKit code. OneSignal does not provide a PushKit SDK — you register the token yourself and pass it to OneSignal in Step 4.

Apple resources:

• PushKit documentation
• Responding to VoIP pushes
• Apple’s VoIP best practices

2

Create a separate OneSignal app for VoIP

Apple VoIP pushes require a different certificate type than standard push notifications. A single OneSignal app can only use one certificate type, so you must create two separate OneSignal apps:

• Main Push App: Uses your APNs certificate for standard push notifications
• VoIP Push App: Uses a VoIP Services Certificate for VoIP-only notifications

Both apps must use the same iOS bundle ID and be associated with the same native iOS app. You do not need to initialize the OneSignal SDK twice — the VoIP app is only used server-side to send VoIP pushes via the API.

The bundle ID (e.g., com.yourcompany.appname) is found in Xcode under your target’s General tab.

3

Upload a VoIP Services Certificate

In your VoIP OneSignal app, upload a VoIP Services Certificate (.p12). This is a different certificate type than the standard APNs push certificate you use for regular notifications.To create one:

1. Go to the Apple Developer Portal
2. Select VoIP Services Certificate
3. Follow the prompts to generate and download the certificate
4. Open it in Keychain Access and export it as a .p12 file
5. Upload the .p12 file to your VoIP OneSignal app’s iOS settings

Do not upload your standard APNs push certificate to the VoIP app. If you use the wrong certificate type, the API will accept your push request but Apple will reject it and the notification will never arrive.

4

Register the VoIP token with OneSignal

Use the Create User API to register the VoIP token with your VoIP OneSignal app.

Sandbox/development builds require "test_type": 1. If you omit this field, the API call succeeds and returns no error, but Apple treats the token as production and silently rejects every push sent to it.

curl --request POST \
     --url https://api.onesignal.com/apps/YOUR_VOIP_APP_ID/users \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "subscriptions": [
    {
      "type": "iOSPush",
      "token": "YOUR_VOIP_TOKEN",
      "test_type": 1
    }
  ]
}
'

A valid VoIP token is a 64-character lowercase hex string (e.g., a1b2c3d4e5f6...). PushKit does not work on the iOS Simulator — you must use a real device to obtain a valid token.

To update the token later, use the Update Subscription API.

5

Send VoIP notifications

Use the Create Notification API with the following parameters:

• "apns_push_type_override": "voip" — tells Apple this is a VoIP push
• app_id — your VoIP app ID
• include_subscription_ids — the VoIP subscription ID you registered
• Either contents or content_available is required

curl --include \
     --request POST \
     --header "Content-Type: application/json; charset=utf-8" \
     --header "Authorization: key YOUR_REST_API_KEY" \
     --data-binary '{
  "app_id": "YOUR_VOIP_APP_ID",
  "content_available": true,
  "data": {
    "your_custom_data": "your_custom_value"
  },
  "apns_push_type_override": "voip",
  "include_subscription_ids": ["YOUR_VOIP_SUBSCRIPTION_ID"]
}' \
https://api.onesignal.com/notifications

VoIP pushes allow a larger payload than standard push. APNs permits up to 5,120 bytes for a VoIP notification, compared to 4,096 bytes for standard push. The data field (Additional Data) still supports up to 2,048 bytes, and payloads over the limit are rejected by APNs. See Maximum push payload size.

6

Verify your VoIP setup

Your iOS VoIP integration is working correctly if:

1. The VoIP token appears as an iOS push subscription in your VoIP app
2. A VoIP push triggers pushRegistry(_:didReceiveIncomingPushWith:for:completion:) in your app
3. The app wakes even when it is terminated or backgrounded

​

Android: simulate VoIP-style behavior

• Data-only push notifications
• Foreground services
• Custom call-style UI

• Send data-only notifications
• Handle them in your app to:
  • Start a foreground service
  • Launch a call UI activity
  • Display a custom incoming call notification

• Android calling app guide
• Incoming call UI example

​

FAQ

​

Do confirmed deliveries work with VoIP?

pushRegistry(_:didReceiveIncomingPushWith:for:completion:)

​

Can I send VoIP notifications from the OneSignal dashboard?

​

Why is my VoIP push silently failing?

1. Are you using a sandbox/development build? You must include "test_type": 1 when registering the token via the Create User API. Without it, the token registers as production, Apple rejects the push, and it silently fails.
2. Did you upload the correct certificate? The VoIP OneSignal app must use a VoIP Services Certificate (.p12), not a standard APNs push certificate. Both look similar in Keychain Access — verify the certificate name starts with “VoIP Services”.
3. Are you sending to the right OneSignal app? The app_id in your send request must be your VoIP app, not your main push app. The REST API Key must also come from the VoIP app.
4. Is the VoIP token valid? Tokens expire when the app is reinstalled or the device is restored. Check that the token is a 64-character lowercase hex string and was recently registered.
5. Does your app call reportNewIncomingVoIPPushPayload? Starting in iOS 13, Apple terminates apps that receive a VoIP push but do not report a call to CallKit. This is an Apple requirement, not a OneSignal limitation.

​

Related pages