GuidesReference
BlogUpdatesSlackGitHubConsole

Push notifications

Handling push notifications when the Orb chat is not active in iOS and Android

Suggest Edits

Push Notifications

The Orb SDK supports handling push notifications when the Orb chat is not
active. This is especially useful when a bot escalates the conversation to a
human agent, but the agent takes a while to respond.

To fully setup push notifications you will need to configure the following
three components:

  1. Android Firebase Cloud Messaging (FCM)

  2. Apple Push Notification service (APNs)

  3. Orb Mobile integration in your Meya app.

    Note, this is not the same as the standard Orb integration used for
    the web client. The Orb Mobile integration is identified by
    type: meya.orb.mobile.integration - here is an example configuration.
    You can still connect the Orb SDK to the Orb integration, but it will not
    handle any push notifications.

Android Setup

1. Setup Firebase Cloud Messaging (FCM) on Android

Follow these instructions to add FCM to your app:
Set up a Firebase Cloud Messaging client app on Android

2. Get your Firebase Service Account Key

  • Open your Firebase Console
  • Select the project you're using for FCM
  • Click gear icon next to Project Overview
  • Go to Project settings
  • Click on Generate new private key
  • This will download a .json file to your computer

3. Add the Service Account Key to your app's vault

  • Copy the JSON from the .json private key file you downloaded from the Firebase
    Console.
  • Open your app's vault in the Meya Console
  • Add the vault key named orb.mobile.service_account_key
  • Paste the JSON you copied
  • Click the ✓ button
  • Click Save

4. Add the Orb Mobile integration to your app

Add the following BFML to you app, we recommend you save this file in the
integration/orb/mobile/ folder, but you can save this anywhere.

id: integration.orb.mobile
type: meya.orb.mobile.integration
android:
  service_account_key: (@ vault.orb.mobile.service_account_key )

Note, the integration's ID is explicitly set in this example. If you do
not explicitly set the ID then Meya will use the folder path (using .
notation e.g. some/folder/file.yaml becomes some.folder.file ) as the
integration's ID.

5. Push your Meya app

If you're in the Meya Console then clicking Save will save the BFML and
push the changes to your app.

If you're using the Meya CLI then you'll need to do an explicit push:

meya push

6. Provide the FCM device token to the Orb SDK

Any activity can then be launched from the push notification when the Orb
Mobile integration's android.click_action setting is set, here is an
example BFML configuration for the Orb Demo app:

id: integration.orb.mobile
type: meya.orb.mobile.integration
# This is optional
collect:
  location: user
# This is optional
identity_verification: (@ vault.orb.identity_verification )
android:
  service_account_key: (@ vault.orb.mobile.service_account_key )
  # This is the name of the activity you would like to launch that contains the
  # Orb SDK
  click_action: .ChatActivity

7. Test your push notifications

The best way to test push notifications is to:

  • Escalate to an agent (e.g. Zendesk/Front), close the chat activity and send
    an agent message, or
  • Send a message via a webhook while the app is closed, see how to set up
    a Webhook integration.

8. Consider in-app notifications

The Orb Mobile integration will only send a push notification when it detects
that the Orb is no longer active (it uses an internal heartbeat to detect
inactivity). However, your app could be in a running state which means the
push notification will not appear, and you'll need to handle
the incoming notification explicitly in a FirebaseMessagingService class.

The Orb Demo app has an example implementation of a FirebaseMessagingService
class here.

The example implementation does not do anything special other than
log the received payloads. However, it's important to note that the Orb Mobile
integration always adds the meya_integration_id key to the push notification
data payload which allows you to identify Meya notifications and handle them
separately from your own app notifications.

If you would like to still show a notification while the app is running, you
can create a notification manually as shown in the FCM quick start app
here

Note, advanced in-app push notification handling is on the Orb SDK roadmap
which will also provide features such as quick replies, buttons etc.

iOS Setup

1. Add APNs notifications to your app

  • First enable the Push Notifications Capability in your app
  • You'll need to implement the various application hooks to register the app
    for push notifications and receive the APNs device token.
  • Example Orb Demo AppDelegate
  • You need to set the orb.deviceToken property before your call
    orb.connect(). This can be done in the application lifecycle hook as
    shown here in the Orb Demo
    , or you can store it in your app state and use it later in your view
    hierarchy.

Note, currently the Orb does not use method swizzling
to autoconfigure these hooks for you (this might be added in a future release), so
if you're using the Firebase SDK for iOS you'll need to disable Firebase's method
swizzling and implement these methods manually.

2. Create your APNs auth key

  • Open the Apple Developer Member Center
  • Go to Certificates Identifiers & Profiles
  • Go to Keys in the menu to the left
  • Click + icon next to the Keys title
  • Give your new key a name
  • Select Apple Push Notifications service (APNs)
  • Click Continue
  • Click Register
  • Click Download to download the file
  • Note the Key ID, you'll need this for the Orb Mobile integration config

3. Add the auth APNs credentials to your app's vault

  • Copy the private key from the auth key file that you downloaded.
  • Open your app's vault in the Meya Console
  • Add the vault key named orb.mobile.auth_key
  • Paste the auth key you copied
  • Click the ✓ button
  • Copy the Key ID from the key you created, Apple Developer Member Center / Keys
  • Add the vault key named orb.mobile.auth_key_id
  • Paste the auth key id you copied
  • Click the ✓ button
  • Copy you Apple Team ID, this is at the top right of the page, under your
    login name
  • Add the vault key named orb.mobile.team_id
  • Paste the team id you copied
  • Click the ✓ button
  • Click Save

4. Add the Orb Mobile integration to your app

Add the following BFML to you app, we recommend you save this file in the
integration/orb/mobile/ folder, but you can save this anywhere.

id: integration.orb.mobile
type: meya.orb.mobile.integration
ios:
  auth_key: (@ vault.orb.mobile.auth_key )
  auth_key_id: (@ vault.orb.mobile.auth_key_id )
  team_id: (@ vault.orb.mobile.team_id )
  topic: YOUR APP BUNDLE ID
  apns_mode: dev

📘

Note

The integration's ID is explicitly set in this example. If you do
not explicitly set the ID then Meya will use the folder path (using .
notation e.g. some/folder/file.yaml becomes some.folder.file ) as the
integration's ID.

🚧

APNs Mode

The apns_mode property must be set to prod for production iOS
apps. The default apns_mode is dev, which uses the development APNs URL.

5. Push your Meya app

If you're in the Meya Console then clicking Save will save the BFML and
push the changes to the app.

If you're using the Meya CLI then you'll need to do an explicit push

meya push

6. Test your push notifications

The best way to test push notifications is to:

  • Escalate to an agent (e.g. Zendesk/Front), close the chat activity and send
    an agent message, or
  • Send a message via a webhook while the app is closed, see how to set up
    a Webhook integration.

7. Consider in-app push notifications

As is the case with Android, the Orb Mobile integration will only send a
push notification when it detects that the Orb is no longer active
(it uses an internal heartbeat to detect inactivity). However, your app could
be in a running state which means the push notification will not appear,
and you'll need to handle the incoming notification explicitly in your
application hook with the didReceiveNotification parameter.

The Orb Demo app has an example implementation of this hook.

The example implementation does not do anything special other than
log the received payloads. However, it's important to note that the Orb Mobile
integration always adds the meya_integration_id key to the push notification
data payload which allows you to identify Meya notifications and handle them
separately from your own app notifications.

Note, advanced in-app push notification handling is on the Orb SDK roadmap
which will also provide features such as quick replies, buttons etc.

Flutter setup

To set up push notifications, follow both the Android and iOS instructions above (implement using native code).

Updated over 2 years ago