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.

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.

Request method

POST

URL

Examples

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

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

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:

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

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:

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

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:

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

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

Call to Swrve Push API that includes an inbox message.

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802' 
  -d 'message=Black Friday Sales' 
  -d 'push_inbox_content={"subject": "Black Friday!", "message": "Check out the great deals!", "thumbnail": "https://bit.ly/3TcneEG", "action_type": "deeplink", "action_value": "myapp://sales?id=black_friday", "advancedOptions": { "internal_id": "black_friday2024" }}'
  https://service.swrve.com/push

curl -d 'push_key=ba96db5f-19db-4e50-844e-de4b86aca478' 
  -d 'user=3294802'
  -d 'message=Black Friday Sales' 
  -d 'push_inbox_content={"subject": "Black Friday!", "message": "Check out the great deals!", "thumbnail": "https://bit.ly/3TcneEG", "action_type": "deeplink", "action_value": "myapp://sales?id=black_friday", "advancedOptions": { "internal_id": "black_friday2024" }}'
  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.

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
  }
}

Push inbox content JSON schema

Use the push_inbox_content parameter to override the campaign’s inbox message details. Only Push via API campaigns that include Inbox notifications support this parameter.

If the campaign does not have a default inbox message value, then the request must include the push_inbox_content parameter with a message property. All other push_inbox_content properties are optional.

The advancedOptions property supports individual or nested groups of JSON key/value pairs.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "subject": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "thumbnail": {
      "type": "string"
    },
    "action_type": {
      "type": "string"
    },
    "action_value": {
      "type": "string"
    },
    "advancedOptions": {
      "type": "object"
    }
  },
  "required": [
    "message"
  ]
}

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:

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

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!”

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:

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

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:

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

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.

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

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.