Create free account

Segments, topics and tags

How to choose who to send to.

Tags

Devices have up to 50 key/value tags that you define (plan, city, last_purchase…):

  • they're sent on registration: tags;
  • they're updated with PUT /v1/devices/{token}/tags, which merges;
  • null deletes a key;
  • replace: true replaces all tags.

Topics

Subjects the device subscribes to by the user's choice, for example "offers" or "news":

  • create it: POST /v1/topics;
  • subscribe: POST /v1/devices/{token}/topics/{topic};
  • send: target: { type: "topic", name: "offers" }.

Segments

Saved filters, with a visual builder in the panel and a live estimate of how many devices they reach. They're an AND/OR tree of up to 3 levels and 20 conditions on:

platform, language, country, timezone, external_user_id, app_version, last_seen (active in the last N days), tag (with its key), topic, notifications_enabled and capability.

"target": { "type": "filters", "rules": {
  "op": "and",
  "conditions": [
    { "field": "language", "operator": "in", "value": ["en"] },
    { "field": "tag", "key": "plan", "operator": "eq", "value": "gold" },
    { "field": "last_seen", "operator": "within_days", "value": 30 }
  ]
} }

To reuse it, save it as a segment in the panel and send with { "type": "segment", "segmentId": "…" }.

Users

If you identify devices with externalUserId, you can send per user, without handling tokens:

"target": { "type": "external_users", "ids": ["customer-123"] }

It reaches all their devices.