Categories and custom data

Group notifications into categories, attach links and images, and carry arbitrary JSON for your own UI.

Besides its text, a notification can carry a category, a link, an image and a free-form data object. All of them are shared by every locale and delivered unchanged in each feed item.

{
  "audience": { "type": "users", "userIds": ["user_123"] },
  "contents": { "en": { "title": "Ada commented on “Q3 roadmap”", "body": "Looks great, ship it!", "actionLabel": "Reply" } },
  "category": "comments",
  "actionUrl": "/docs/q3-roadmap#comment-881",
  "imageUrl": "https://cdn.example.com/avatars/ada.png",
  "data": { "documentId": "doc_42", "commentId": 881, "screen": "Comment" }
}

Category

A free-form grouping key of 1 to 64 characters, such as billing, comments or product. Use the same small set of values consistently.

• The feed can be filtered by category: GET /v1/client/feed?category=billing (the SDKs expose this as a filter), which makes per-category tabs easy.
• The filter is an exact, case-sensitive match. Counts (unreadCount, unseenCount) always cover the whole feed (its newest 100 notifications), not just the filtered category.
• category is also returned on each item, so you can pick an icon or color per category in a custom item renderer.

Action URL

actionUrl is where a click takes the user. It must be an http(s) URL or a path starting with /, up to 2,048 characters. The SDK UIs record a click, mark the item read and then navigate, unless your click handler takes over (for example to use your router or a mobile deep link). On the web a path is resolved against your app's origin; React Native only opens absolute URLs, so route paths yourself in the click handler.

actionLabel (per locale) adds an explicit button such as "View invoice". The whole item is clickable either way.

Image

imageUrl (same format rules as actionUrl) is shown as the item's picture, typically an avatar or a product thumbnail. Without it, the SDK UIs show an initial-letter avatar.

Custom data

data is any JSON object. Typical uses:

• ids your UI needs (documentId, orderId);
• mobile navigation targets ({ "screen": "Order", "params": { "id": "o_1" } });
• values for templates: {{data.documentId}}.

data is limited to 8 KB of serialized JSON (larger payloads get 400 bad_request). Keep it small anyway: it is part of every feed response that contains the item. It is visible to every user who receives the notification, so don't include secrets or other users' private data.

Reading them in your app

Every feed item has category, actionUrl, imageUrl and data (each null when not set). Use them in the SDKs' click handlers and custom renderers; see the SDK pages.