Push API | Richie Dev

Richie Push API is a server-to-server REST API which can be used by the publishers to send push notifications to Richie apps running on iOS and Android devices.

Request

Method: POST
URL:

https://data.richie.app/push/v2/admin/task

Headers:

Authorization: Basic <credentials>
Content-Type: application/json

HTTP Basic auth credentials will be provided to Richie Push API integrators by Richie.

Body

{
  "app_id": "your-app-id",
  "topics": [
    "breaking-news",
    "sports",
    "culture"
  ],
  "payloads": {
    "ios": {
      "aps": {
        "alert": {
          "title": "Push Notification Title for iOS",
          "body": "Push Notification Body Text for iOS",
          "publisher-item-id": "100200",
        },
        "content-available": 1
        "issue-guid": "2258b0e6-6748-46c2-8e67-0893c0542fbb",
        "issue-page": 10
      }
    },
    "android": {
      "data": {
        "title": "Push Notification Title for Android",
        "body": "Push Notification Body Text for Android",
        "external-browser-url": "https://example.com/news/article/1",
        "issue-guid": "2258b0e6-6748-46c2-8e67-0893c0542fbb",
        "issue-page": 10
      }
    }
  }
}

app_id

The client app identifier. This value will be provided to Richie Push API integrators by Richie.

With topics you can target specific groups of app clients. Client apps can register to a set of topics and push notifications can then be sent to those topics. Topics are app-specific, and are configured separately from Push API.

To send push notification to all client apps regardless of their topic subscriptions, use the special topic all_users.

payloads

The following keys can be used to specify the contents of a notification:

title
body
publisher-item-id
external-browser-url
issue-guid
issue-page
issue-title
issue-product-tag
tab-id

These keys can be sent to either iOS clients, Android clients or all clients.

For iOS, place these keys in ios { aps { alert { … } } } object
For Android, place these keys in android { data { alert { … } } } object

Max size for each payload (ios and android) is 4 KB.

title

The notification's title. Optional, string.

body

The notification's body text. Required, string.

publisher-item-id

Publisher's identifier for the news item related to current notification. Client apps will use this identifier for opening related news item if user taps on the notification. This value must be present in the news feed consumed by the client apps.

If this key is omitted, tapping on the notification will bring the app to the foreground without any navigation action. Optional, string.

If this value is provided, external-browser-url should be omitted.

external-browser-url

A full HTTPS URL which should be opened in an external mobile browser when user taps on the current notification. If this value is provided, publisher-item-id should be omitted.

Optional, HTTPS URL string.

issue-guid and issue-page

If specified, this must be the uuid string value of an Richie Editions Issue (https://richie.dev/docs/editions/indexes) and an optional page number, an integer, to open the issue to. If the page number is not specified, the issue will be opened to the first page.

issue-title, issue-product-tag and issue-page

If you don't have access to Richie Editions identifiers but know the titles of the editions, you can use title search with issue-title and issue-product-tag. An optional issue-page integer is supported.

tab-id

You can send the user to a specific application tab with the tab-id field. The value is an internal tab identifier Richie uses when configuring an app, so coordinate with developers to find out the values.

tab-id was added in late 2024. If there's a chance some of your users might be on a version that does not support it, it can be a good idea to use external-browser-url as a fallback. Both can be specified in the same push but tab-id is parsed first, so users on new apps will get tab selection and users on older apps will get the external URL.

content-available

This flag is relevant for iOS only, and should be placed directly under the aps object (NOT under alert). If content-available is set to 1, the operating system is asked to launch the app in the background when push notification is received, even if user does not tap on it. This gives the app a chance to update and cache the latest news feeds, so they are readily available when user opens the app the next time.

Response

HTTP 201

Returned when push notification payload was accepted for delivery to the mobile clients. The delivery is asyncronous. In most cases, it takes less than 60 seconds to reach all end user devices.

HTTP 401

Returned if HTTP Basic auth credentials were invalid. Please contact Richie to get valid credentials for your app.

User-specific request

Target a single or several clients by using external_user_ids instead of topics.

Method: POST
URL:

https://data.richie.app/push/v2/admin/task

Headers:

Authorization: Basic <credentials>
Content-Type: application/json

HTTP Basic auth credentials will be provided to Richie Push API integrators by Richie.

Body

{
  "app_id": "your-app-id",
  "external_user_ids": [
    "abcde...",
    "12345..."
  ],
  "payloads": {
    "ios": {
      "aps": {
        "alert": {
          "title": "Push Notification Title for iOS",
          "body": "Push Notification Body Text for iOS",
          "publisher-item-id": "100200",
        },
        "content-available": 1
      }
    },
    "android": {
      "data": {
        "title": "Push Notification Title for Android",
        "body": "Push Notification Body Text for Android",
        "external-browser-url": "https://example.com/news/article/1"
      }
    }
  }
}

Content analytics

Push payload may contain additional fields which can be used in content analytics. For example, if push notification refers to a news item using the publisher-item-id key, the analytics event which is posted when that news item is opened can refer to the values included in the push payload. The configuration of analytics events themselves is done separately by Richie team and it may target various analytics backends.

An example push payload with extra keys for content analytics:

  [...],
  "payloads": {
    "ios": {
      "aps": {
        "alert": {
          "title": "Push Notification Title for iOS",
          "body": "Push Notification Body Text for iOS",
          "publisher-item-id": "100200",
          "custom_key": "custom_value"
        },
        "content-available": 1
      }
    },
    "android": {
      "data": {
        "title": "Push Notification Title for Android",
        "body": "Push Notification Body Text for Android",
        "publisher-item-id": "100200",
        "custom_key": "custom_value"
      }
    }
  }

Limitations

Additional keys used in analytics cannot contain dash characters (-) due to internal platform limitations
Nested keys are not supported. All additional keys must be on the same level as the default payload keys (such as title, body, etc)

Push delivery analytics

Optional push delivery analytics can be configured, where each push task will be reported to a desired endpoint. The endpoint must authenticate the analytics data request and decode a JSON body.

An example POST request body which will be sent to the configured endpoint:

{
  "app_id": "an-app",
  "completion_time_ms": 765,
  "deletions": 0,
  "failures": 17,
  "payloads": {
    "android": {
      "data": {
        "alert": {
          "body": "Push Notification Body Text for Android",
          "external-browser-url": "https://example.com/news/article/1",
          "title": "Push Notification Title for Android"
        },
        "task_id": "00f5c216-ee53-4e29-af13-f109d5563a9e"
      }
    },
    "ios": {
      "aps": {
        "alert": {
          "body": "Push Notification Body Text for iOS",
          "publisher-item-id": "100201",
          "title": "Push Notification Title for iOS"
        },
        "content-available": 1,
        "task_id": "00f5c216-ee53-4e29-af13-f109d5563a9e"
      }
    }
  },
  "successes": 14400,
  "topics": [
    "all_users",
    "food"
  ]
}