Skip to main content

Broadcast with topics

Section: DOC-CP-notifications-topics#broadcast-with-topics.

Build an opt-in “Weekly Updates” group: users join or leave it in your app, and your backend sends each update to the current subscribers. Prepare the notification workflow and subscriber records first. The topic stores membership; it does not create users or prepare message content.

Follow the recipe in order: create one stable topic, show the current user’s subscription, save follow/unfollow changes, check partial failures, then send the update. Use the returned transaction to investigate delivery.

A topic is a named group of subscribers you can send to as one. Use it when the recipient list is a property of the content — everyone following a coach, everyone in a challenge — rather than something you can compute per send.

Use the topic operations below for an explicitly selected subscriber group. For a recipient list supplied with each send, use bulk sending.

Keep topic management in your backend. The API accepts a verified key or configured JWT but does not check an admin role simply because a route contains /manage/. Your application must authorize who can change membership or send to the topic. See management authentication.

1. Create the weekly-updates audience​

Section: DOC-CP-notifications-topics#create-a-topic.

Request example: Create a notification topic · Request fields.

{
  "topicKey": "weekly-updates",
  "name": "Weekly Updates"
}

Response:

Response example: Create a notification topic · Response fields.

{
  "topicKey": "weekly-updates",
  "topicId": "6512f0a1c3d4e5f60718293c"
}

Keep your chosen audience key for later actions; see topic identifiers.

2. Show the user’s current subscription​

Section: DOC-CP-notifications-topics#check-one-subscription.

Cheaper than paging the whole list when you only need to render a follow/unfollow button.

Request example: Check if a user is subscribed to a topic · Request fields.

{
  "topicKey": "weekly-updates",
  "userId": "user-1"
}

Response:

Response example: Check if a user is subscribed to a topic · Response fields.

{
  "isSubscribed": true
}

Render the follow button using the subscription result.

3. Apply follow and unfollow choices​

Section: DOC-CP-notifications-topics#add-and-remove-subscribers.

When a person opts in, add their existing subscriber identity. When they opt out, remove it. For an import, batch up to the limit below and check every failure; one missing subscriber must not be shown as enrolled just because another succeeded.

Up to 100 users per call.

Request example: Add subscribers to a topic · Request fields.

{
  "topicKey": "weekly-updates",
  "userIds": ["user-1", "user-2"]
}

Response:

Response example: Add subscribers to a topic · Response fields.

{
  "result": {
    "totalCount": 2,
    "successful": 2,
    "failed": 0
  }
}

Inspect per-user membership results and show failed enrollments separately:

Response example: Add subscribers to a topic · Response fields.

{
  "result": {
    "totalCount": 2,
    "successful": 1,
    "failed": 1,
    "errors": [
      {
        "subscriberId": "user-2",
        "code": "not_found",
        "message": "subscriber does not exist"
      }
    ]
  }
}

Request example: Remove subscribers from a topic · Request fields.

{
  "topicKey": "weekly-updates",
  "userIds": ["user-1"]
}

Response: a result object containing the same totalCount / successful / failed / errors shape.

4. Inspect membership when enrollment is incomplete​

Section: DOC-CP-notifications-topics#list-subscribers.

Use the membership list to investigate a failed import or unexpected recipient. Compare identities with the intended audience and follow pagination; use the single-subscription check for the current user’s follow button.

Request example: List subscribers of a topic · Request fields.

{
  "topicKey": "weekly-updates",
  "page": 1,
  "pageSize": 50
}

Response:

Response example: List subscribers of a topic · Response fields.

{
  "userIds": ["user-1", "user-2"],
  "totalCount": 2,
  "hasMore": false
}

5. Deliver an update to the subscribed group​

Section: DOC-CP-notifications-topics#send-to-a-topic.

Send only after the update is ready and your backend authorizes the sender. Select the workflow and current topic key. If the initiating user should not receive a notice about their own action, use the documented exclusion below.

Request example: Send a notification to all topic subscribers · Request fields.

{
  "workflowId": "push-notification",
  "topicKey": "weekly-updates",
  "payload": {
    "title": "Weekly Update",
    "body": "Your weekly health summary is ready"
  },
  "excludeUserId": "user-admin"
}

Response:

Response example: Send a notification to all topic subscribers · Response fields.

{
  "acknowledged": true,
  "status": "processed",
  "transactionId": "txn_def456"
}

Use the sender-exclusion option when the person should not receive their own update.

The result acknowledges the topic send. Follow its transaction through delivery status when a subscriber reports a missing message. Check their current membership, channel registration and preferences before sending an individual replacement.

Retire the group without deleting its users​

Section: DOC-CP-notifications-topics#delete-a-topic.

Removes the topic and every subscriber association with it. Subscribers themselves are untouched, and notifications already in flight are not cancelled.

Request example: Delete a notification topic · Request fields.

{
  "topicKey": "weekly-updates"
}

Response:

Response example: Delete a notification topic · Response fields.

{
  "status": {
    "acknowledged": true,
    "status": "done"
  }
}

Read the retirement result before confirming the group was removed.

Document ID: DOC-CP-notifications-topics. Section identities and revisions.