Last modified November 14, 2018 by Shelly Wolfe

Swrve Batch Push API

The Swrve Batch Push API lets you send push notifications to a group of Swrve users via a web API call. While Swrve’s standard push notification service lets you target a behavioral group of users at a predefined schedule from within Swrve, the Batch Push API lets you to send push notifications to groups of users or a custom message to individual users in response to events external to Swrve.
The Swrve Batch Push API is currently only available as part of our Early Access program. If you would like to have this feature enabled for your app, contact your Customer Success Manager at support@swrve.com.

To use the Batch Push API, you must first create a Push API Campaign in Swrve. (For more information, see Push API campaigns.) Each campaign generates a unique API key that you must include with all requests to this API that you want to associate with that campaign. The API requests are authenticated using this Push API Key. Each campaign collects and reports on all users that engage with push notifications sent with the corresponding API key.

The Batch Push API key is different than the app-specific API key used with other Swrve APIs. It is important to generate and test a campaign-specific Push API key for each separate campaign.

After you create a Push API campaign and get the Push API key, you are ready to use the Batch Push API. In addition to the API key, you need to provide the Swrve user IDs or your own external IDs that you want to send the push notification to. You can also provide optional parameters to override some of the defaults set in the campaign. If you’re using a third-party service (for example, Marketo), take the associated HTTP POST URL and insert the Swrve user IDs and message content in place. In the case of Marketo and most other marketing platforms, use the Push API as a webhook.


External user IDs

As noted above, Swrve’s Batch Push API supports using your own external user ID to identify your users when sending a push notification. To use this functionality, you must also generate an Identity-specific API key on your app’s Integration Settings screen that you then send with the external user ID when making the API call. The Identity key must remain secret—do not use the Identity key in your SDK integration or expose it to end users.

To send a batch push notification using an external user ID:

  1.  In the request to the Batch Push API, provide identity_secret_key="identity_secret_key" where identity_secret_key is the Identity secret key for the app.
  2. In the JSON sent to the Batch Push API, provide an additional parameter "external_user_id", giving the external user ID. Omit the "swrve_user_id" parameter.

Error codes

If an error occurs while processing a request that references an external user ID, you may receive one or more of the following error codes.

Code Text Description
404 Invalid identity key The system does not recognize your Identity secret key, check that the key you’ve provided is correct.
404 Identity key and campaign key refer to different apps The secret key belongs to a different app than the campaign.

Additionally, if there is an error when Swrve processes the batch, one of the following error messages may appear in the batch error report:

  • Attempted to send batch push using external ids, but no identity key provided
  • No user mapping found for external user id ‘[external user ID value]’

Send a batch push notification

Send this API call to Swrve to send a notification to a group of users or to personalize the notification for individual users in a group.

Request method

POST

URL

This article references Swrve’s URLs for all data and content stored in both our US and EU data centers. Click the relevant tab based on your app configuration. For more information, see How do I configure the Swrve SDK for EU data storage?

US

https://service.swrve.com/push_batch

EU

https://eu-service.swrve.com/push_batch

Examples

Call to Swrve Batch Push API to send the same message (for example, “Hello there!”), to user-1 and user-2 of your app:

US

EU

Call to Swrve Batch Push API to send a different message, including custom parameters, to user-1 and user-2 of your app:

US

EU

You can also have common or default parameters that apply to the batch, but include personalized parameters that override the default parameters for specified individual users. For example:

US

EU

URL parameters

The following parameter should appear in the URL line (GET-style).

Parameter Presence Description
push_key Required The Push API key used to identify and authenticate your campaign.

Encoding

POST bodies must be UTF-8 encoded.

Batch specification (JSON)

The batch specification is very flexible in terms of how to specify the target audience and is designed to satisfy a wide range of customer needs. You can include parameters in the specification that are common (applied to the whole group), personalized (customized for each individual user), or both. You can specify the audience as a collection of user IDs and as a JSON object that defines any personalized parameters.

The structure of the batch specification provided in the request body may be expressed as follows:

The following parameters should appear in the post body (POST-style) as JSON and can be applied to all users in the batch as common parameters or to individual users as personalized parameters.

The POST body should use a Content-Type of “application/json”.

Parameter Presence Description
swrve_user_id Required The Swrve user ID of the user(s) who should receive the push notification.
message Optional The push message text. This overrides the default message, if provided when creating the Push API campaign in Swrve.
sound Optional The custom sound file name.
payload Optional This parameter carries a free JSON structure to create instructional parameters that are sent to your app when you send the push notification. For more information on defining custom key/value pairs, see Creating Push Notifications.
notification_category Optional The iOS 8 interactive notification category, if applicable. For other platforms, this is added as a category or ios_notification_category.
notification_title Optional For iOS devices, the iOS 8.0.2+ short notification title, used for Apple Watch Short-Look Notifications. For Windows devices, the title for Windows 10 Notifications. Additionally may be specified as title or ios_notification_title.

This overrides the default title, if provided when creating the campaign in the Push API Campaigns workflow.

deeplink
Optional Requires Swrve SDK 4.3+. The action that is executed when a user engages with the notification.
badge_number Optional Sets the iOS device’s badge icon to an specific number. This overwrites any previous value set. Use 0 to clear the current badge count. May also be provided with badge key.
subtitle Optional Requires Swrve SDK 4.11+

For iOS10+ devices, text that is displayed as the subtitle in push notifications.

For Android devices, text that is displayed after the title.

rich_media_url Optional Requires Swrve SDK 4.11+

Link to the media that is displayed in the push notification when supported by the device. See rich_media_type for the types of media supported.

Has to be valid and HTTPS URL, and include an extension.

rich_media_type Optional Requires Swrve SDK 4.11+

image – Displays the given link as an image in the push notification.

audio – Only supported on iOS. Displays a media player in the push notification.

video – In extended view, links a hosted video (for example, YouTube), and links to it from the thumbnail image.

gif – Only supported on iOS. Will display the given animation as an image in the push notification.

rich_media_title Optional Requires Swrve SDK 4.11+

Same as title but is only displayed if media is successfully shown.

rich_media_subtitle Optional Requires Swrve SDK 4.11+

Same as subtitle but is only displayed if media is successfully shown.

rich_media_message Optional Requires Swrve SDK 4.11+

Same as message but is only displayed if media is successfully shown.

rich_media_thumbnail_url Optional Requires Swrve SDK 4.11+

Used as the thumbnail for the media content.

Has to be valid and HTTPS URL, and include an extension.

buttons Optional Requires Swrve SDK 4.11+

Set of buttons that are displayed with the notification. Each button can have its own text and action.

Actions can be: open_app, open_url and dismiss.

For a complete reference on the schema supported, see the Swrve Push API Guide.

time_to_live Optional This parameter specifies how long (in seconds) the notification should be kept before being discarded (if the device is offline).

Min value: 0

Max value: 2419200 (4 weeks)

collapse_key Optional This parameter (passed as an integer) allows you to replace or update earlier notifications with the same identifier (provided they haven’t been read) with new message content.

Android requires Swrve SDK 4.11.3+

silent Optional Determines if the message should be sent to the app as a silent notification (background app update) or not.

Rich notifications buttons JSON schema

Each button requires a title, action type and action. The action is the URL to be opened when the button type is open_url. For more information, see the Swrve Push API guide.

Responses and error codes

The response text uses HTTP response codes to indicate the result of the operation. If the system successfully accepts the requested batch, it returns an HTTP response message of 202: Accepted back to the client, containing a Location header that includes the API URI to get the batch status, in order to track its progress and detect completion. The same location is also included in the response body. Otherwise, the message includes the corresponding HTTP error code that was returned, with the associated JSON description. For example success and failure responses, see below.

If an error occurs while processing the request, you need to make sure your integration is equipped to handle error conditions.

Code Text Description
202 Accepted The requested batch was accepted and scheduled for execution. You can check the status using the specified URI.
400 Unsupported HTTP method {method} The requested method is not supported. The API only supports POST requests.
403 Feature Not Available Your app is not enabled to use the Batch Push API. Contact your Customer Success Manager at support@swrve.com to have them enable the feature for your app. After the feature is enabled for your app, you can resend the request.
404 Not Found The requested resource is not found. Make sure you entered the correct URI.
404 Invalid Push API Key Check that your Push API key is correct.
413 Request Entity Too Large The provided batch specification is too large to process. Try splitting the batch into smaller parts and resending them. The maximum supported batch size is 256 KB.
429 Rate Limit Exceeded App is sending too many requests per minute. Try resending the request later and reducing the rate of requests.
500 Internal Server Error An error occurred on the Swrve server side. Try resending the request later, if possible.
503 Service Unavailable An error occurred on the Swrve server side. Try resending the request later, if possible.

Example responses

Successful request:

Rejected request:


Request batch status

Send this API call to get the status of a batch using the batch ID.

Request method

GET

URL

US

https://service.swrve.com/push_batch

EU

https://eu-service.swrve.com/push_batch

Examples

Call to the Swrve Batch Push API to get the status of batch ID ba96db5f-19db-4e50-844e-de4b86aca478:

US

EU

URL parameters

The following parameters should appear in the URL line (GET-style).

Parameter Presence Description
batch_id Required The Batch Push ID returned when a batch request is accepted (see POST method above).

Responses and error codes

Code Status Description
200 OK The current status of the requested batch.
400 Unsupported HTTP method {method} The requested method is not supported. The API only supports GET requests.
404 Not Found The requested resource is not found. Make sure you entered the correct URI.
404 Invalid Batch ID Check that your batch ID is correct.
500 Internal Server Error An error occurred on the Swrve server side. Try resending the request later, if possible.
503 Service Unavailable An error occurred on the Swrve server side. Try resending the request later, if possible.

If it wasn’t possible to deliver the notification to any users in the batch, the response body contains a report with the possible failure details for each affected user.

Possible failure or warning reasons are:

Failure Safe to resend Description
Parsing impossible. {Detailed description} yes It was not possible to parse the batch from the identified user onwards due to a syntax error. See details and amend the batch specification as needed.
Failure to parse request. {Detailed description} yes There was a problem parsing the batch specification for that particular user. See details about syntax error for this particular user (in case where the user is identified in the request.)

 

Warning Safe to resend Description
Invalid buttons, no more than 3 buttons are supported yes The rich push notification included more than maximum allowed of three buttons for this user. Revise the notification to include a maximum of three buttons.
Invalid time_to_live value, must be positive number less than 4 weeks yes The length of time a of notification should be kept before being discarded exceeds the allowed values (0 – 2419200 seconds). Adjust the value as needed.
Push Message should be not empty and less than {n} characters yes The message text exceeds the allowed limit of 4096 by n characters. Reduce the message text length.
No Push Token Registered For User yes Swrve does not have a device token for the associated user. A push token for the relevant platform is required to send a push notification. For iOS users, Apple only sends a device token after the user grants permission. Check if Swrve has a device token for the user or if they have granted push permission.
No Push Token Registered For User {platform} yes For platform agnostic push API campaigns (that is, you selected All for the campaign Platform), when a user has no any associated device tokens, Swrve is not able to identify the platform to use. Check if Swrve has a device token for the user or if they have granted push permission, or specify the platform in the push API campaign.
Invalid media type, must be one of {list} yes Rich media type requested is not supported by the chosen platform. Only the media types included in the {list} are allowed. Ensure the specified rich media type is supported by the related platform.
For wns platform, title is required yes The title is required for sending push notifications to Windows devices. Ensure you provide a title for the referenced user.
Silent push not supported for platform {platform} yes The requested platform does not support silent notifications (background updates). Only GCM, ADM and iOS support silent notifications. If required, remove the silent attribute included in the batch specification.
Failed to retrieve push certificate for app yes The push certificate is not available for the requested application. Check that you’ve uploaded a valid push certificate for the app that you’re using for the push notification campaign.
Failure to send message no Unable to send push message to a list of users that were part of the batch.
Failure due to: {reason} no Delivery of the requested push notification was rejected due to {reason} provided.
Rejected, User Has Changed Token no Warning for users whose push token has changed due to re-registration that causes a failure to deliver the push notification. Try to get a new push token for the user and then resending the request for this user.
Internal failure to send a Push message no No particular reason is provided, but the notification was not sent to the referenced user. Try resending the request later, if possible.
Failed to send a Push message no Unexpected internal failure occurred. Try resending the request later, if possible.
Exceeded time limit by {n} ms yes The batch execution exceeded allowed execution time by n milliseconds.

Example responses

Batch in progress:

Batch was processed successfully:

Batch was processed successfully, with some warnings:

Batch failed, possible to retry:

Batch done with warnings, not possible to retry: