Handling push notifications (Webhook API)

Handling push notifications (Webhook API)

This page shows you how to use push notifications with the Support SDK using the Webhook API.

The Zendesk Support SDK can be set up to notify the end user when an agent posts a public comment on their request.

Before you start

Before you start, the following information is useful to know:

• You can use either the Webhook API or Urban Airship to send push notifications.
• If you already have a push notifications service we recommend you to use the Webhook API option. On the other side, if you don't have your own push notifications service or you are not willing to develop one, you should use the Urban Airship alternative.
• You will only receive notifications on requests that were created through the Support SDK.
• The configuration of your app in Zendesk Support must include the push notification details for your chosen option.
• If you switch from one integration to another, or change identities, register the devices again. Otherwise the push notifications will not be delivered properly.
• If you register multiple devices with the same JWT identity, these are all added to the list of active devices for this identity so that you can send push notifications to multiple devices.
• If a device token becomes invalid, you will need to register the new device token for push notifications to continue being delivered properly.

Use the Webhook API for push notifications

Zendesk Support notifies an endpoint that you set up when a notification needs to be sent. After that, your service must handle sending the push notification for the end user's device.

You must set up a push notification service and then register an end user's interest in receiving push notifications on the app side.

When Zendesk Support sends a notification to the end user, it sends a POST request to the URI set in the app configuration.

For a full webhook integration, you need to do three things:

1. Configure your Support SDK App in your account
2. Set up your backend to handle our callback API
3. Set up your app to handle the push notification and ticket deep-linking

Account Configuration

In the Zendesk Support admin interface, select the "Webhook" option in the push notifications combo box in the Customization tab on the Mobile SDK page.

You'll be prompted to provide the webhook URI.

Server Integration

Webhook API

As explained above, Zendesk Support sends an HTTP POST request to the URI of your service. The payload looks like this:

POST [your_push_notification_callback_uri];
Content-Type: application/json
Accept: application/json

{
  "devices": [
    {
      "identifier": "oiuytrdsdfghjk",
      "type": "ios"
    },
    {
      "identifier": "iuytfrdcvbnmkl",
      "type": "android"
    }
  ],
  "notification": {
    "body": "Agent replied something something",
    "title": "Agent replied",
    "ticket_id": "5"
  }
}

The request body is a JSON object containing the following parameters:

Name	Type	Comment
devices	array	List of devices
notification	object	The details for the notification

devices

Parse the devices array to get the devices that need to receive a push notification.

Name	Type	Comment
identifier	string	The device identifier/token that was registered through the Support SDK
type	string	The device type. Possible values: "ios" or "android"

notification

Use the notification object to pass along the title or body of the message, or you can customize it yourself. If you want the client app to handle deep-linking, pass the ticket_id value in the push payload.

Name	Type	Comment
title	string	The short message of the notification
body	string	The long message of the notification
ticket_id	string	The identifier of the ticket that was updated. Pass this along as zendesk_sdk_request_id if you want ticket deep-linking in the app

Note: As a best practice, provide a callback URL that's not guessable and make sure you can easily change it.

Device Delete

Firebase Cloud Messaging (FCM) will let you know if a user unregistered from push notifications. You need to let us know too.

You can use the Push Notification Devices Bulk Unregister API to delete the devices of customers that deleted the app or are no longer registered.

Application Integration

You need to handle the following four scenarios in the app code:

• Device registration
• Device unregistration
• Notification payload handling
• Ticket deep-linking

Device registration

You need to register devices interested in receive push notifications with Zendesk Support.

First, go through the following guide from Google on implementing a FCM Client on Android: Implementing FCM Client on Android. The FCM API will issue an id after registration.

Second, send the id to your Zendesk Support instance through the Zendesk API to register the device:

Zendesk.INSTANCE.provider().pushRegistrationProvider().registerWithDeviceIdentifier(result, new ZendeskCallback<String>() {
    @Override
    public void onSuccess(String result) {

    }

    @Override
    public void onError(ErrorResponse errorResponse) {

    }
});

Device unregistration

When the user signs out or doesn't want push notifications anymore, call the following API to remove the device identifier from Zendesk Support:

Zendesk.INSTANCE.provider().pushRegistrationProvider().unregisterDevice(new ZendeskCallback<Void>() {
    @Override
    public void onSuccess(final Void response) {

    }

    @Override
    public void onError(ErrorResponse errorResponse) {

    }
});

Notification payload handling

Set up your BroadcastReceiver or IntentService to receive and handle push notifications. Extract the payload from the given intent and show a notification.

When a notification is received you have the option of using the Support SDK's deep-linking feature to handle the notification or handling it yourself. If you choose to handle it yourself, you can retrieve the ticket and fetch its comments using an API provider. See the following topics in the Support SDK JavaDocs:

• getRequest
• getComments

Ticket deep-linking

You can use the Support SDK's deep linking functionality to show the ticket directly in response to a notification tap.

Acquire an Intent

Use the RequestConfiguration builder to get a deep-link Intent for your notification's content Intent. Use one of the methods provided by ZendeskDeepLinking.INSTANCE to get an Intent.

final Intent mainActivity = new Intent(getApplicationContext(), MainActivity.class);
mainActivity.putExtra(MainActivity.EXTRA_VIEWPAGER_POSITION, MainActivity.VIEWPAGER_POS_HELP);

final ArrayList<Intent> backStackItems = new ArrayList<>();
backStackItems.add(mainActivity);

final Intent deepLinkIntent = new RequestConfiguration.Builder()
    .withRequestId(requestId)
    .deepLinkIntent(getApplicationContext(), backStackItems);

To preserve the navigation flow, you can specify a list of back stack intents. These activities will be shown if the user presses back. Ensure that provided Intents are explicit Intents.

Using the Intent

The returned Intent invokes a BroadcastReceiver that handles the further deep linking process.

1. Notifications

final Intent deepLinkIntent = new RequestConfiguration.Builder()
    .withRequestId(requestId)
    .deepLinkIntent(getApplicationContext(), backStackItems);

final PendingIntent contentIntent = PendingIntent.getBroadcast(
    context, {requestCode}, deepLinkIntent, {flags}
);

final Notification notification = new NotificationCompat.Builder(context)
    ...
    .setContentIntent(contentIntent)
    ...
    .build();

2. In an Activity/Fragment

final Intent deepLinkIntent = new RequestConfiguration.Builder()
    .withRequestId(requestId)
    .deepLinkIntent(getApplicationContext(), backStackItems);
context.sendBroadcast(deepLinkIntent);

Refresh comment stream

Another feature provided by Support.INSTANCE is the possibility of refreshing the comment stream if it's visible.

/**
 *
 * ...
 *
 * @param requestId the ID of the request to refresh
 * @param context the application Context
 * @return true if the conversation UI was refreshed on screen, false if not.
 */
public boolean refreshRequest(String requestId, Context context) {

Example:

if (Support.INSTANCE.refreshRequest(requestId, getApplicationContext())) {
    return;
} else {
    //e.g. show a notification
}