Handle push notifications (Webhook API)

This is the developer guide for the Support SDK v1 for iOS. For Support SDK v2, see Support SDK v2 iOS.

This feature is only available on the Team, Professional, and Enterprise plans.

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, register the devices again. Otherwise the push notifications will not be 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.

Push Notifications Webhook Configuration

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

Apple Push Notification Service (APNS) will let you know if a user unregistered from push notifications. You need to let us know.

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

Application Integration

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

You must also enable Background fetch and Remote notifications in the Background Modes section of your apps Capabilities in your project configuration.

Push Notifications Setup Background Modes

Device registration

First, you need to ask the user for permission, as per the iOS docs.

Swift 3

if #available (iOS 8.0, *) {
  let settings = UIUserNotificationSettings(types: [.alert, .badge, .sound],
                                            categories: nil)
  application.registerUserNotificationSettings(settings)
  application.registerForRemoteNotifications()
} else {
  application.registerForRemoteNotifications(matching:[.alert, .badge, .sound])
}

Objective-C

// Register the app for remote notifications in application:didFinishLaunchingWithOptions:
if ([UIApplication instancesRespondToSelector:@selector(registerForRemoteNotifications)]) {

    UIUserNotificationType types = UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound;

    UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:types categories:nil];
    [application registerUserNotificationSettings:settings];
    [application registerForRemoteNotifications];

} else if ([UIApplication instancesRespondToSelector:@selector(registerForRemoteNotificationTypes:)]) {

    UIRemoteNotificationType types = UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound;

    [application registerForRemoteNotificationTypes:types];
}

This should result in a call to the app delegates didRegisterForRemoteNotificationsWithDeviceToken method. The device token returned by this method is what you'll pass as the identifier parameter to the following Support SDK method:

Swift 3

ZDKConfig.instance().enablePush(withDeviceID: identifier) { pushResponse, error in
  if let error = error {
    print("Couldn't register device: \(identifier). Error: \(error)")
  } else {
    print("Successfully registered device: \(identifier)")
  }
}

Objective-C

[[ZDKConfig instance] enablePushWithDeviceID:identifier callback:^(ZDKPushRegistrationResponse *registrationResponse, NSError *error) {
    if (error) {
        [ZDKLogger log:@"Couldn't register device: %@. Error: %@", identifier, error];
    } else if (registrationResponse) {
        [ZDKLogger log:@"Successfully registered device: %@", identifier];
    }
}];
...

Note: We have a category on NSData which parses the identifier returned in the above delegate method. Feel free to use this method from our sample app, NSData+ZDKSampleApp.m.

To register for push notifications with Zendesk Support, a valid identity must be set in the Support SDK. Depending on how your app is configured, you probably won't have an identity ready in the AppDelegate. We suggest you store the device identifier returned by Apple and register for push notifications with Zendesk Support once an identity becomes available, such as when the user signs into your app.

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:

Swift 3

ZDKConfig.instance().disablePush(identifier) { status, error in
  if let error = error {
    print("Couldn't unregistered device: \(identifier). Error: \(error)")
  } else {
    print("Successfully unregistered device: \(identifier)")
  }
}

Objective-C

[[ZDKConfig instance] disablePush:identifier callback:^(NSNumber *responseCode, NSError *error) {
    if (error) {
        [ZDKLogger log:@"Couldn't unregister device: %@. Error: %@", identifier, error];
    } else if (responseCode) {
        [ZDKLogger log:@"Successfully unregistered device: %@", identifier];
    }
}];
Notification payload handling

Set up the delegate methods to handle the payload received as described in the iOS Notification Programming Guide on the Apple site.

Swift 2

func application(application: UIApplication, didReceiveRemoteNotification
  userInfo: [NSObject : AnyObject], fetchCompletionHandler
  completionHandler: (UIBackgroundFetchResult) -> Void) {

  ...
  ZDKPushUtil.handlePush(
    userInfo,
    for: application,
    presentationStyle: .formSheet,
    layoutGuide: ZDKLayoutRespectTop,
    withAppId: "<your-app-id>",
    zendeskUrl: "<your-zendesk-url>",
    clientId: "<your-client-id>")
    ...
}

Objective-C

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
 {
    ....
    [ZDKPushUtil handlePush:userInfo
             forApplication:application
          presentationStyle:UIModalPresentationFormSheet
                layoutGuide:ZDKLayoutRespectTop
                  withAppId:<your-app-id>
                 zendeskUrl:<your-zendesk-url>
                   clientId:<your-client-id>
     fetchCompletionHandler:completionHandler];
    ....
}
Ticket deep-linking

You can use the Support SDK's deep linking functionality to show the ticket in a direct way in response to a notification tap. We implemented a push handler that takes the userInfo dictionary from the application:didReceiveRemoteNotification:fetchCompletionHandler: with the expectation that the zendesk_sdk_request_id key is present. When the key is present, the handler attempts to do one of three things depending on the state of the application:

  • If the app is currently on the request for which a push was received, the push handler refreshes the comment stream
  • If the app is on the request list view, the push handler displays an alert giving the user the option to view the update. The user can ignore or open the request, in which case the handler pushes a comments view on the view stack
  • If the app is on any other screen, the push handler displays an alert giving the user the option to view the update. The user can ignore or open the request, in which case the handler presents a comments view modally

To handle instances when your app is not running and a push notification is received, the push handler requires parameters from the init method. If required, these parameters are used to init the Support SDK.

Make sure your service is sending the zendesk_sdk_request_id parameter to the application in the extra section of the message you send to APNS. It should look something like this:

{
    aps = {
        ...
        alert = "There has been a reply to your message.";
        ...
    };
    ...
    "zendesk_sdk_request_id" = <the-request-id>;
    ...
}