Docs

Push notifications

Deliver operator replies and campaigns while the app is closed, with a deep link straight into the right conversation. Your app owns the push subsystem; the SDK registers tokens and opens conversations.

What Respondo sends#

  • Message pushes — an operator or AI reply in a conversation the visitor is part of.
  • Campaign pushes — outbound push campaigns, which also report an open beacon.

Message pushes always carry a deep link of the form respondo://conversation/<id>. Campaign pushes carry the deep link configured on the campaign — it is optional, and when not set the push contains no deep link.

Apple (APNs)#

iOS push runs on APNs directly — no Firebase dependency. From your Apple Developer account, obtain:

  • An APNs Auth Key (.p8 token key).
  • The Key ID of that key.
  • Your Team ID.
  • The app bundle id.

Google (FCM)#

Android push goes through Firebase Cloud Messaging. From your Firebase project, obtain:

  • A service account JSON with the Cloud Messaging role.
  • The Firebase project ID (Firebase console → Project settings) — entered as its own field in the dashboard push form alongside the service-account JSON.
  • The Android app package name, and connect the app to the same Firebase project (google-services.json).

Configure in Respondo#

Add the APNs key and the FCM service account with its project ID to your widget channel in the dashboard. That is all Respondo needs to send to both platforms.

Setting the credentials over the API and the full field reference are covered in the push setup guide delivered with your SDK access.

Payload format#

The payload always lives under a root respondo key — its presence is how the SDK tells its own push from others (on iOS in userInfo, on Android as a JSON string in data["respondo"]).

respondo payloadjson
{
  "respondo": {
    "type": "message",
    "conversation_id": "a1c4e7b2-5d38-4f6a-9e10-3b7c2d5f8a90",
    "message_id": "e9a3c1f6-4b8d-4e0a-b5f3-1d7b2a4e9c63",
    "deep_link": "respondo://conversation/a1c4e7b2-5d38-4f6a-9e10-3b7c2d5f8a90"
  }
}

All values are flat strings. The notification title and body are delivered by the platform transport — aps.alert on APNs and message.notification on FCM — not inside the respondo object.

Campaign pushes also include a delivery_id used to report the open beacon, and may carry extra flat string keys from the campaign's push data.

Handling taps & foreground#

On a notification tap, hand the raw payload to the SDK. It parses the payload and opens the right conversation, returning false if the push is not a Respondo push (handle it yourself in that case).

Handle a tap (per platform)text
Android:  RespondoPushPayload.from(data)?.let { Respondo.handlePush(it) }
iOS:      Respondo.handlePush(userInfo: userInfo)
Flutter:  Respondo.handlePushData(message.data)

Duplicates are collapsed by message_id, and while the same conversation is open in the foreground the system notification is suppressed — the SDK handles both automatically.

Registering device tokens#

Your app obtains the device token from its push subsystem and passes it to setPushToken. Call clearPushToken on logout.

Which token to pass. The backend routes each delivery by platform — iOS goes to APNs directly, Android goes to FCM — so you must register the token of the platform's native transport, not whatever your push library happens to hand back:
  • Android — the FCM registration token from FirebaseMessaging.getToken().
  • iOS (native) — the APNs device token (hex) from didRegisterForRemoteNotificationsWithDeviceToken.
  • iOS via Flutter (firebase_messaging) — use getAPNSToken(), not getToken(). Passing the FCM token on iOS sends it to APNs, where it is not a valid device token and pushes never arrive. getAPNSToken() can be null for the first moments after launch — retry after a short delay if so.
Android — FirebaseMessagingServicekotlin
override fun onNewToken(token: String) {
    Respondo.setPushToken(token)
}
iOS — AppDelegateswift
func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let token = deviceToken.map { String(format: "%02x", $0) }.joined()
    Respondo.setPushToken(token)
}
Flutter — firebase_messagingdart
// iOS needs the APNs token; Android needs the FCM token.
final token = Platform.isIOS
    ? await FirebaseMessaging.instance.getAPNSToken()
    : await FirebaseMessaging.instance.getToken();
if (token != null) Respondo.setPushToken(token);

// FCM rotates its registration token; keep Android in sync.
if (!Platform.isIOS) {
  FirebaseMessaging.instance.onTokenRefresh.listen(Respondo.setPushToken);
}