Last modified July 12, 2023 by Shelly Wolfe

Swrve Push API

Send push notifications to a single Swrve user via a web API call with the Swrve Push API. While Swrve’s scheduled push notification service allows you to target a behavioral group of users at a predefined schedule from within Swrve, the Swrve Push API lets you send push notifications to individual users in response to events external to Swrve.

To use the Push API, you must first create a Push API Campaign in Swrve. (For more information, see 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 Push API Campaign and generate 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 or your own external 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.


External user IDs

As noted above, Swrve’s 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 push notification using an external user ID, instead of providing the Swrve user ID in your URL parameters, provide the following:

  • external_user_id – The external user ID.
  • identity_secret_key – The Identity secret key.

Error codes

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

Code Text Description
400 No such external ID The external user ID does not exist.
403 Invalid identity secret key The system does not recognize your Identity secret key, check that the key you’ve provided is correct.
403 Identity secret key does not match campaign key The secret key belongs to a different app than the campaign.
403 No user ID found for external ID The system does not recognize the external user ID, check that the ID you’ve provided is correct.
429 Resolution capacity limit exceeded The app is trying to perform too many alias resolutions. Try resending the request later and reducing the rate of requests.

Request method

POST

URL

This article references Swrve’s URLs for all data and content stored in both our US and EU data centers. Select 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

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

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'message=Your%20order%20ID%20is%2012345' 
  https://service.swrve.com/push

EU

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'message=Your%20order%20ID%20is%2012345' 
  https://eu-service.swrve.com/push

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

US

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'message=Your%20order%20ID%20is%2012345' 
  -d 'custom=orderID%3D12345' 
  -d 'custom=uid2%3Djackjones@gmail.com' 
  https://service.swrve.com/push

EU

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'message=Your%20order%20ID%20is%2012345' 
  -d 'custom=orderID%3D12345' 
  -d 'custom=uid2%3Djackjones@gmail.com' 
  https://eu-service.swrve.com/push

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

US

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'message=Your%20order%20ID%20is%2012345' 
  -d 'buttons=[{"title":"Open App","action_type":"open_app","action":""},{"title":"Open Url","action_type":"open_url","action":"https://www.swrve.com"},{"title":"Dismiss","action_type":"dismiss","action":""}]' 
  https://service.swrve.com/push

EU

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'message=Your%20order%20ID%20is%2012345' 
  -d 'buttons=[{"title":"Open App","action_type":"open_app","action":""},{"title":"Open Url","action_type":"open_url","action":"https://www.swrve.com"},{"title":"Dismiss","action_type":"dismiss","action":""}]' 
  https://eu-service.swrve.com/push

Call to Swrve Push API to send a similar message that includes personalization with realtime user properties:

US

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'message=Come%20watch%20%24%7Buser.favorite_team%5D%20at%20%24%7Buser.favorite_team_stadium%7D%20tonight!' 
  https://service.swrve.com/push

EU

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'message=Come%20watch%20%24%7Buser.favorite_team%5D%20at%20%24%7Buser.favorite_team_stadium%7D%20tonight!' 
  https://eu-service.swrve.com/push

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
external_user_id
Required Identifies the user who should receive the push notification, whether using the Swrve-generated user ID or your own external user ID.
identity_secret_key Required The Identity secret key for your app. If you’re using an external ID to identify your users, you must also send the Identity key.
platforms Optional Comma separated list of platforms to send the push notification to.

Supported platforms: ios, android, amazon, huawei, and web.

Specified platforms(s) must be enabled for the campaign.

If key is omitted, push notification is sent to all platforms enabled for the campaign.

device_reach Optional last_active_device – notification is only sent to most recently used device.

last_active_per_platform – notification is only sent to most recently used device on each platform.

message Optional The push message text. This overrides the default message, if provided when creating the campaign in the Push API workflow.

Note: If a message includes rich media, the message uses the rich_media_message parameter instead if the media is successfully shown.

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 short notification title, used for Apple Watch Short-Look 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 Push API Campaigns workflow.

Note: If a message includes rich media, the message uses the rich_media_title parameter instead if the media is successfully shown.

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 The action that is executed when a user engages with the notification.
<platform>_deeplink Optional The action that is executed when a user engages with the notification on a specific platform. If provided, overrides the deeplink value for the specified <platform>.

If no deeplink value or <platform>_deeplink value for a given platform is included, engaging with the push action results in an app open. If the campaign targets web, then a deeplink or web_deeplink value is required.

Supported platforms: ios, amazon, android, huawei, and web.

target_in_app_campaign_id Optional The ID of the in-app message or embedded campaign that should be displayed when a user engages with the push notification. For more information, see Push to in-app campaigns.
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 a specific number. This overwrites any previous value set. Use 0 to clear the current badge count.
subtitle Optional For iOS10+ devices, text that is displayed as the subtitle in push notifications.

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

Note: If a message includes rich media, the message uses the rich_media_subtitle parameter instead if the media is successfully shown.

rich_media_url Optional 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 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.

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

ios_rich_media_url Optional Link to the media that is displayed in the push notification on iOS devices. If not provided, the rich_media_url media is displayed. See ios_rich_media_type for the types of media supported.

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

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

audio – Displays a media player in the push notification.

gif – Will display the given animation as an image in the push notification.

rich_media_title Optional Same as title but is only displayed if media is successfully shown.
rich_media_subtitle Optional Same as subtitle but is only displayed if media is successfully shown.
rich_media_message Optional Same as message but is only displayed if media is successfully shown.
rich_media_thumbnail_url Optional Used as the thumbnail for the media content.

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

rich_media_icon_url Optional Android only: Used as the notification icon when the notification is displayed in banner view.

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

rich_media_expanded_title Optional Android only: The notification title when displayed in expanded view.
rich_media_expanded_body Optional Android only: The message content when the notification is displayed in expanded view.
rich_media_expanded_icon_url Optional Android only: Used as the notification icon when the notification is displayed in expanded view.

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

android_visibility Optional Determines how the notification appears on the Android device’s lock screen. Requires that sensitive notifications are disabled for the device’s lock screen. For more information, see Control notifications on Android.

public (default) – The notification’s contents are fully visible on secure lock screens.

private – The notification is shown, but its content is hidden.

secret – The notification is not shown on the lock screen.

android_lock_screen_message Optional Replaces the message value in the collapsed notification. Unlike the message content, the lock screen message is displayed when android_visibility is set to private.
buttons Optional 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. (See example above)

For a complete reference on the schema supported, see Rich Notifications Buttons JSON Schema below.

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_channel_id Optional The Android Channel ID the notification is sent in.
android_delivery_priority Optional high – Delivers the notification immediately, even if the device is in Doze mode. Used for time-sensitive messages.

normal (default) – Delivers the notification immediately when the app is in the foreground. For backgrounded apps, delivery may be delayed. Used for less time-sensitive messages.

ios_delivery_priority Optional high (default) – Delivers the notification immediately.low – Delivers the notification based on the device’s power considerations.
ios_interruption_level Optional Determines the importance and delivery timing of the push notification delivered to iOS devices.

active (default) – The notification’s contents are fully visible on secure lock screens.

passive – Delivers quietly without lighting up the screen.

time_sensitive – Bypasses focus modes. Requires adding the Time Sensitive Notifications capability to your app in Xcode.

critical – Bypasses focus and do not disturb modes. Requires special entitlement from Apple.

ios_relavance_score Optional Number between 0.0 and 1.0. Ranks the importance of this push notification against others. The highest score gets featured in the notification summary or appears at the top of grouped notifications.
language_tag Optional Used primarily for QA testing, the language_tag overrides the device’s swrve.language user property value to display the matching campaign language variant. To GET a full list of language_tag values and their associated language names, use Swrve’s List all Languages API.

Note: If no matching language variant exists, then the API call returns the default language variant content.

Use the message, sound, and custom parameters to override the defaults set when creating 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. If the action type is open_url, the action is the associated deeplink URL you want to direct the customer to.

Optionally, define platform specific actions by including <platform>_action values in the request. Supported platforms include: “ios”, “amazon”, “android”, and “huawei”. Platform specific action values override the platform agnostic action value.

If the request does not contain a  <platform>_action value for one or more platforms targeted by the campaign, then the request must also include an action value.

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "type" : ["array", "nil"],
  "items": {
    "type" : "object",
    "additionalProperties": true,
    "properties": {
      "title" : { "type" : "string" },
      "action_type" : { "type" : "string", "enum": ["open_app", "open_url", "dismiss"] },
      "ios_action" : { "type" : ["string", "nil"] },
      "android_action" : { "type" : ["string", "nil"] },
      "amazon_action" : { "type" : ["string", "nil"] },
      "huawei_action" : { "type" : ["string", "nil"] },
      "ios_type" : {
        "type": "array",
        "items": {
          "type": "string", "enum": ["destructive", "auth-required", "foreground"]
        },
        "uniqueItems": true
      }
    },
  "required" : ["title", "action_type", "action"],
  "maxItems": 3
  }
}
If your notification includes custom buttons that require the app to come to the foreground, use the ios_type of "foreground", otherwise the deeplink URL will not open correctly.

Personalization

Use Swrve’s realtime user properties to include dynamic, personalized content in your Push via API campaign. For example, insert the favorite_team custom property into your push notification’s title with fallback team:

  -d 'notification_title=${user.favorite_team|fallback="team"}'

For more information on how to personalize your campaign content, see Campaign personalization.

Data injection

Use template keys to inject dynamic values from the Push API request into your default notification content.

For example, your order management system might know the specific item a customer ordered and how long it will take to deliver the item to the customer. To notify a user about the current status of their order, you might configure your push notification’s default message body: “Your ${template.item_name|fallback=”order”} will arrive in ${template.delivery_minutes_away}!”

The order management system would include the data_template object and the associated template keys item_name and delivery_minutes_away in the push notification request:

US

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'data_template={"delivery_minutes_away":"12 minutes","item_name":"Pepperoni Pizza"}'
  https://service.swrve.com/push

EU

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'data_template={"delivery_minutes_away":"12 minutes","item_name":"Pepperoni Pizza"}'
  https://eu-service.swrve.com/push

This request results in the push notification: “Your Pepperoni Pizza will arrive in 12 minutes!”

Swrve rejects push notification requests that do not contain a value for one or more template keys if no fallback value is provided in the default message.

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:

{
"code": 200,
"message": "OK"
}

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

{
"code": 400,
"message": "Rejected By Server, InvalidRegistration"
}

Example responses

Successful request:

US

POST /push HTTP/1.1
Host: service.swrve.com
Content-Type: application/x-www-form-urlencoded

push_key=ba96db5f-19db-4e50-844e-de4b86aca478&user=3294802&message=Test%20message

EU

POST /push HTTP/1.1
Host: eu-service.swrve.com
Content-Type: application/x-www-form-urlencoded

push_key=ba96db5f-19db-4e50-844e-de4b86aca478&user=3294802&message=Test%20message

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "code": 200, "message": "OK" }

Rejected request:

US

POST /push HTTP/1.1
Host: service.swrve.com
Content-Type: application/x-www-form-urlencoded

push_key=ba96db5f-19db-4e50-844e-de4b86aca478&user=93284&message=Test%20message

EU

POST /push HTTP/1.1
Host: eu-service.swrve.com
Content-Type: application/x-www-form-urlencoded

push_key=ba96db5f-19db-4e50-844e-de4b86aca478&user=93284&message=Test%20message

Response:

HTTP/1.1 404 No Push Token Registered For User
Content-Type: application/json

{ "code": 404, "message": "No Push Token Registered For User" }

Successful test push request:

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

US

POST /push HTTP/1.1
Host: service.swrve.com
Content-Type: application/x-www-form-urlencoded

push_key=ba96db5f-19db-4e50-844e-de4b86aca478&user=919239&message=Test%20message&test=1

EU

POST /push HTTP/1.1
Host: eu-service.swrve.com
Content-Type: application/x-www-form-urlencoded

push_key=ba96db5f-19db-4e50-844e-de4b86aca478&user=919239&message=Test%20message&test=1

Response:

HTTP/1.1 200 Test Passed
Content-Type: application/json

{ "code": 200, "message": "Test Passed" }

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 FCM 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 FCM 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.
400 No value for key user.<key> and no fallback provided No value for <key> user property exists for the user ID and no fallback value was provided to use in the absence of a key value.
400 No value for swrve.language No value for swrve.language user property exists for the user ID and no language_tag provided to use in the absence of value.
400 Invalid value {} for swrve.language The swrve.language user property value for the user ID is not a valid language.
400 Invalid value {} for language_tag The language_tag value provided is not a valid language
400 Invalid template properties in request {} Data template object contained invalid JSON.
400 No value for <key> and no fallback provided No value for <key> is included in the request and campaign does not contain fallback value to use in the absence of a key value.
400 Selected platform override not supported for this campaign One or more of the platforms specified in the request did not match the campaign’s supported platforms.
403 Invalid API Key Check that your Push API key is correct.
403 Not Available The 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.
503 Service Unavailable An error occurred on the Swrve server side. Attempt to resend the request later, if possible.