Skip to main content

Broadcast with topics

Section ID: Guide/jbquvgrj1j#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 ID: Guide/jbquvgrj1j#create-a-topic

Request example: Create a notification topic · Request fields.

See Create a notification topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • topicKey: text weekly-updates.
  • name: text Weekly Updates.

Response:

Response example: Create a notification topic · Response fields.

See Create a notification topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • topicKey: text weekly-updates.
  • topicId: text 6512f0a1c3d4e5f60718293c.

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

2. Show the user’s current subscription​

Section ID: Guide/jbquvgrj1j#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.

See Check if a user is subscribed to a topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • topicKey: text weekly-updates.
  • userId: text user-1.

Response:

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

See Check if a user is subscribed to a topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • isSubscribed: boolean true.

Render the follow button using the subscription result.

3. Apply follow and unfollow choices​

Section ID: Guide/jbquvgrj1j#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.

See Add subscribers to a topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • topicKey: text weekly-updates.
  • userIds[0]: text user-1.
  • userIds[1]: text user-2.

Response:

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

See Add subscribers to a topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • result.totalCount: number 2.
  • result.successful: number 2.
  • result.failed: number 0.

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

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

See Add subscribers to a topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • result.totalCount: number 2.
  • result.successful: number 1.
  • result.failed: number 1.
  • result.errors[0].subscriberId: text user-2.
  • result.errors[0].code: text not_found.
  • result.errors[0].message: text subscriber does not exist.

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

See Remove subscribers from a topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • topicKey: text weekly-updates.
  • userIds[0]: text user-1.

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

4. Inspect membership when enrollment is incomplete​

Section ID: Guide/jbquvgrj1j#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.

See List subscribers of a topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • topicKey: text weekly-updates.
  • page: number 1.
  • pageSize: number 50.

Response:

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

See List subscribers of a topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • userIds[0]: text user-1.
  • userIds[1]: text user-2.
  • totalCount: number 2.
  • hasMore: boolean false.

5. Deliver an update to the subscribed group​

Section ID: Guide/jbquvgrj1j#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.

See Send a notification to all topic subscribers for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • workflowId: text push-notification.
  • topicKey: text weekly-updates.
  • payload.title: text Weekly Update.
  • payload.body: text Your weekly health summary is ready.
  • excludeUserId: text user-admin.

Response:

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

See Send a notification to all topic subscribers for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • acknowledged: boolean true.
  • status: text processed.
  • transactionId: text 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 ID: Guide/jbquvgrj1j#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.

See Delete a notification topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • topicKey: text weekly-updates.

Response:

Response example: Delete a notification topic · Response fields.

See Delete a notification topic for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • status.acknowledged: boolean true.
  • status.status: text done.

Read the retirement result before confirming the group was removed.

Document ID: Guide/jbquvgrj1j