Push Notifications (GCM)

GCM Deprecation

Google is deprecating GCM on April 11, 2019. We are no longer updating our GCM library, 5.1.6 will be the last version of our messenger with GCM support. We strongly recommend migrating your app to FCM and then migrating from Intercom GCM to Intercom FCM library

Intercom supports both GCM and FCM for setting up your app to receive push notifications. If you would like to use FCM you can follow the instructions here.

If you’d like to send push notifications and/or push messages to your customers, you’ll need to enable Google Cloud Messaging (GCM) in Intercom. Here’s how:

Step 1. Enable Google services for your app

If you already have a Google Developers project with GCM enabled you can skip to the next step. Otherwise go to the Google Developers page and create a new project following these steps:

Name the project and give it the package name of your Android app.

There are two important pieces of data to copy:

a) Your Server API key (to be entered in the Intercom dashboard settings)
b) Your Sender ID (to be embedded in the Android app).

Step 2. Add GCM API key to Intercom for Android settings

Open your app’s settings and select Intercom for Android. Then find the "Enable GCM" section. Here you'll be able to paste and save your Server API key (a).

Step 3. Enable client to receive push messages with Sender ID

In your apps res/values/strings.xml add the following line with your sender id (b):

<string name="intercom_gcm_sender_id">YOUR_SENDER_ID</string>

Step 4. Setting your GCM icon

If you want to add a custom icon for your notifications, just add an image named intercom_push_icon.png to each of your supported densities. Please note that vector drawables cannot be used here. For example:

/res/drawable-xxhdpi/intercom_push_icon.png 
/res/drawable-xhdpi/intercom_push_icon.png 
/res/drawable-hdpi/intercom_push_icon.png 
/res/drawable-mdpi/intercom_push_icon.png

Notifications icon design guidelines

We recommend following the material design guidelines for producing this icon.

Step 5. Open Intercom conversations from GCM

When a user taps on a push notification we hold onto data such as the URI in your message or the conversation to open. When you want Intercom to act on that data, just call:

Intercom.client().handlePushMessage();

Note

It’s important to wait for any splash screens or loading screens to finish before calling handlePushMessage() or your users might not have time to see the conversation we opened.

If you wish to create a custom back stack for this notification you can pass a TaskStackBuilder to the same method:

Intercom.client().handlePushMessage(TaskStackBuilder stackBuilder);

Step 6. Disable GCM on log out

To stop users from receiving messages when they have logged out of the app make sure Intercom.client().logout() is called.

Step 7. Using Intercom with other GCM setups (Optional)

This only applies to applications that also use GCM for their own content, or use a third party service for GCM. You’ll need to update the your GcmListenerService and the class where you generate your device token.

You should have a class that generates a push device token and sends it to your backend. In addition to sending the token to your backend you will need to forward it to Intercom, like this:

private final IntercomPushClient intercomPushClient = new IntercomPushClient();

public void onHandleIntent(Intent intent) {     
    InstanceID instanceId = InstanceID.getInstance(this);
    String senderId = "YOUR_SENDER_ID";
    String token = instanceId.getToken(senderId,
        GoogleCloudMessaging.INSTANCE_ID_SCOPE, null);
    intercomPushClient.sendTokenToIntercom(getApplication(), token);
}

You should have a class that extends GcmListenerService. That service will consume pushes intended for Intercom. To allow us to draw the Intercom push set up your GcmListenerService, like this:

private final IntercomPushClient intercomPushClient = new IntercomPushClient();

public void onMessageReceived(String from, Bundle message) {
    if (intercomPushClient.isIntercomPush(message)) {
        intercomPushClient.handlePush(getApplication(), message);
    } else {
        //DO HOST LOGIC HERE
    }
}

Troubleshooting tips

If you are having trouble getting GCM to work in your app, here's a list of things you should check:

  • Ensure you ticked the box 'Send a push notification' when you send a manual message.
  • Verify that the app’s notifications are not blocked. Settings > Sound & Notification > App notifications, this may differ depending on Android version.
  • Did you specify the correct GCM Server API key (a)?
  • Make sure you added the Sender ID (b) you got from the Google Developers site or from your google-services.json file in your strings.xml under the correct key intercom_gcm_sender_id

And as always, you can contact us via Intercom. We're always here to help 😀

Push Notifications (GCM)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.