Last modified January 22, 2015 by Shelly Wolfe

Swrve Push API

The Swrve Push API enables you to send push notifications to a single Swrve user via a web API call from a third-party system. While Swrve’s standard push notification service allows you to target a behavioral group of users at a predefined schedule from within Swrve, this API allows you to send push notifications to individual users in response to events external to Swrve.

To use this API, you must first create a Transactional Push API Campaign in Swrve. (For more information, see Transactional Push API Campaigns.) Each campaign provides 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 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 Transactional Push API Campaign and access the Push API key, you are ready to use the API. In addition to the API key, you need to provide the Swrve user ID 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 ID and message content in place. In the case of Marketo and most other marketing platforms, use the Push API as a webhook.

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?

Request Method

POST

URL

US

https://service.swrve.com/push

EU

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

Examples

Call to Swrve Push API to send a message (for example, “Your order ID is 12345”), to user 3294802 of your app:

US

EU

Call to Swrve Push API to send a similar message that includes custom parameters:

US

EU

URL Parameters

The following parameters can appear in both the URL line (GET-style) as well as in the post body (POST-style), for ease of integration. The URL parameters take precedence over the post body.

Parameter Presence Description
push_key Required The Push API key used to authenticate your campaign.
user Required The Swrve user ID of the user who should receive the push notification.
message Optional The push message text. This overrides the default message, if provided when defining the campaign in the Transactional Push via API wizard.
sound Optional The custom sound file name.
custom Optional This parameter can appear multiple times – once for each custom key/value pair. Use custom key/value pairs 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.

Note: The custom parameter is not supported in silent push notifications (background app updates). Use the silent_payload_json parameter instead.

test Optional Flag to turn on “dry run” mode. This tests the Push API without sending the push notification to the user.
notification_category Optional The iOS 8 interactive notification category, if applicable. For other platforms, this is added as a custom key/value pair, using “category” as the key.
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. For Android devices, this is added as a custom key/value pair, using “title” as the key.
This overrides the default title, if provided when defining the campaign in the Transactional Push API Campaigns workflow.
title Optional Alias for notification_title, supported for backwards compatibility.
ios_notification_category Optional Alias for notification_category, supported for backwards compatibility.
ios_notification_title Optional Alias for notification_title, supported for backwards compatibility.
deeplink Optional Requires Swrve SDK 4.3+. The action that is executed when a user engages with the notification.
silent_payload_json Optional Contains the JSON object that is sent to the app using a silent push notification (background app update). This replaces the use of custom for regular Push with Message notifications. Unlike custom parameters, you can provide any valid JSON object here, with any level of nesting.
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.
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 Rich Notifications Buttons JSON Schema below.

The message, sound and custom parameters can be used to override the defaults set when defining the campaign in Swrve. For example, you could use the message parameter to send a personalized message to each user. If you wanted to track the user using an external ID, you might pass that via a custom parameter.

Each custom key/value pair contains a value of “key=value”, which is URL-encoded in the normal encoding (so “=” is represented as “%3D”, and so on).  They are further restricted in what they can contain:

  • The keys must be composed of characters in the range [a-zA-Z0-9_-.]
  • The values will be stored in the JSON payload as simple strings; nested JSON structures are not represented here.

If the test parameter is set to 1, then a “dry run” test mode is activated. In all respects, this acts the same as a real request, but a successful response will use “Test Passed” instead of “OK” in its response string, and the push notification will not be sent.

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.

UTF-8 Encoding

POST bodies must be UTF-8 encoded.

Responses

The response text is a JSON document (Content-Type: application/json), containing:

  • “code” – the numeric HTTP response code (for example,  200, 401)
  • “message” – a descriptive string describing the result

In the successful delivery case, this will look something like:

In the event of a rejection error from the Apple or Google Cloud Messaging (GCM) push service, the error response also includes a “reason” key containing the verbatim rejection string from Apple/GCM (when available). For example, you might receive the following response from GCM if the push token was invalid:

Example Responses

Successful request:

US

EU

Response:

Rejected request:

US

EU

Response:

Successful test push request:

The purpose of the push message is to validate all the parameters, however the message is not actually sent.

US

EU

Response:

Error Codes

If an error occurs while processing the request, you may receive one or more of the following error codes and need to make sure your integration is equipped to handle error conditions.

Code Text Description
400 Invalid Parameter The request included an invalid parameter, based on the specification.
400 Empty Message Message text is empty.
400 Rejected by Server, {reason} The Apple or GCM servers have rejected the push notification and the reason is included, if available; for example, if the push token is no longer valid.
400 Rejected, User Has Changed Token The Apple or GCM servers have rejected the push notification. This occurs when a user uninstalls and reinstalls an app, and the token corresponding to the uninstalled copy of the app is used.
403 Invalid API Key Check that your Push API key is correct.
403 Not Available The Transactional Push API feature is not available for this app.
404 No Push Token Registered for User No push device token exists for the user ID. This may because the user hasn’t been prompted to accept push notifications or they opted out of receiving push notifications from your app.
405 Method Not Allowed The API request was sent as a GET method. Resend the request as a POST method.
413 Request Entity Too Large The message text is too long (4 kilobytes limit).
429 Rate Limit Exceeded App is sending too many requests per second. Try resending the request later and reducing the rate of requests.
500 Internal Server Error An error occurred on the Swrve server side. Attempt to resend the request later, if possible.
503 Service Unavailable An error occurred on the Swrve server side. Attempt to resend the request later, if possible.