REST API reference

POST /notifications
Authorization: Key psk_…     (Basic / Bearer also accepted)
Content-Type: application/json
{
  "app_id": "<your project's App ID>",
  "target_channel": "push",
  "include_aliases": { "external_id": ["user-1"] },
  "headings": { "en": "Order delivered" },
  "contents": { "en": "Order #42 was delivered" },
  "data": { "screen": "order", "id": "42" },
  "big_picture": "https://…/img.jpg",
  "ios_badgeType": "SetTo", "ios_badgeCount": 1,
  "android_channel_id": "orders",
  "ttl": 86400, "collapse_id": "order-42"
}

200 → { "id": "…", "external_id": null }
200 → { "id": "", "errors": ["All included players are not subscribed"] }
400 → { "errors": ["…"] }      403 → wrong App ID / key

GET /notifications/{id}?app_id=…
→ { "id", "successful", "failed", "errored", "remaining",
    "queued_at", "completed_at", "headings", "contents", … }

POST /notifications
{
  "app_id": "<App ID>",
  "include_aliases": { "external_id": ["user-2"] },
  "call": {
    "action": "incoming",        // "incoming" | "ended"
    "id": "6f1c…-uuid",          // empty = auto-generated (incoming)
    "caller_name": "John Smith",
    "handle": "0901234567",
    "avatar": "https://…/a.jpg",
    "is_video": false,
    "timeout": 45                // ring seconds
  },
  "data": { "room": "abc" }      // extra data
}

When the call is answered / cancelled / times out: send again with "action": "ended" and the same id (optionally with headings/contents = "Missed call") so the other devices stop ringing.

Payload (both platforms, all values are strings): type (incoming_call / call_ended), call_id, caller_name, caller_handle, caller_avatar, is_video ("true"/"false"), timeout, plus data. Android also gets title/body if sent.

iOS devices without a voipToken count as failed. A dead VoIP token is only removed; the device still gets normal notifications. The APNs .p8 key works for VoIP; no separate certificate is needed.

iOS (Swift)

func application(_ app: UIApplication,
  didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let token = deviceToken.map { String(format: "%02x", $0) }.joined()
    #if DEBUG
    let isSandbox = true
    #else
    let isSandbox = false
    #endif
    // POST /api/v1/apps/{appId}/devices
}

// Calls: PushKit + CallKit (enable Background Modes → Voice over IP)
let registry = PKPushRegistry(queue: .main)
registry.delegate = self
registry.desiredPushTypes = [.voIP]

func pushRegistry(_ r: PKPushRegistry,
  didUpdate creds: PKPushCredentials, for type: PKPushType) {
    let voipToken = creds.token.map { String(format: "%02x", $0) }.joined()
    // POST …/devices with "voipToken": voipToken
}

func pushRegistry(_ r: PKPushRegistry,
  didReceiveIncomingPushWith payload: PKPushPayload,
  for type: PKPushType, completion: @escaping () -> Void) {
    let p = payload.dictionaryPayload
    let update = CXCallUpdate()
    update.remoteHandle = CXHandle(type: .generic,
        value: p["caller_handle"] as? String ?? "")
    update.localizedCallerName = p["caller_name"] as? String
    update.hasVideo = (p["is_video"] as? String) == "true"
    // MUST report to CallKit immediately or iOS kills the app
    provider.reportNewIncomingCall(
        with: UUID(uuidString: p["call_id"] as! String)!,
        update: update) { _ in completion() }
}

Android (Kotlin)

FirebaseMessaging.getInstance().token
    .addOnSuccessListener { token ->
        // POST /api/v1/apps/{appId}/devices
    }

class PushService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        // register again with the new token
    }

    override fun onMessageReceived(msg: RemoteMessage) {
        val d = msg.data
        when (d["type"]) {
            "incoming_call" -> // show the call screen: notification
                // CATEGORY_CALL + full-screen intent (permission
                // USE_FULL_SCREEN_INTENT) or ConnectionService
                showIncomingCall(d["call_id"], d["caller_name"],
                    d["is_video"] == "true")
            "call_ended" -> dismissCall(d["call_id"])
        }
    }
}