Tài liệu REST API

POST /notifications
Authorization: Key psk_…     (nhận cả Basic / Bearer)
Content-Type: application/json
{
  "app_id": "<App ID của dự án>",
  "target_channel": "push",
  "include_aliases": { "external_id": ["user-1"] },
  "headings": { "en": "Đơn hàng đã giao" },
  "contents": { "en": "Đơn #42 đã giao thành công" },
  "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 → sai 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",          // bỏ trống = tự sinh (incoming)
    "caller_name": "Nguyễn Văn A",
    "handle": "0901234567",
    "avatar": "https://…/a.jpg",
    "is_video": false,
    "timeout": 45                // giây đổ chuông
  },
  "data": { "room": "abc" }      // gửi kèm
}

Khi người nhận bắt máy / người gọi huỷ / hết giờ: gửi lại với "action": "ended" cùng id (có thể kèm headings/contents = "Cuộc gọi nhỡ") để các máy khác tắt chuông.

Payload (cả 2 nền tảng, mọi giá trị là chuỗi): type (incoming_call / call_ended), call_id, caller_name, caller_handle, caller_avatar, is_video ("true"/"false"), timeout, cộng với data. Android có thêm title/body nếu gửi kèm.

Thiết bị iOS chưa đăng ký voipToken sẽ bị tính lỗi. VoIP token chết chỉ bị xoá, thiết bị vẫn nhận thông báo thường. Key .p8 của APNs dùng được cho VoIP, không cần certificate riêng.

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
}

// Cuộc gọi: PushKit + CallKit (bật 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 với "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"
    // BẮT BUỘC báo CallKit ngay, nếu không iOS sẽ tắt 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) {
        // đăng ký lại với token mới
    }

    override fun onMessageReceived(msg: RemoteMessage) {
        val d = msg.data
        when (d["type"]) {
            "incoming_call" -> // hiện màn hình cuộc gọi: notification
                // CATEGORY_CALL + full-screen intent (quyền
                // USE_FULL_SCREEN_INTENT) hoặc ConnectionService
                showIncomingCall(d["call_id"], d["caller_name"],
                    d["is_video"] == "true")
            "call_ended" -> dismissCall(d["call_id"])
        }
    }
}