Migrating to POST /broadcasts

Introduction

MagicBell has tweaked their vocabulary to provide clarity about functionality we offer, and about the way you communicate with your users. Part of this evolution is the distinction between notifications and broadcasts. This guide walks you through the migration from creating notifications to creating broadcasts, improving the way you send messages to one or multiple recipients.

Why Migrate to Broadcasts?

Broadcasts separate the concept of sending a message (a broadcast) from the resulting message received by a specific user (a notification). This distinction not only clarifies the messaging process but also paves the way for more flexible and scalable communication strategies in the future.

Migrating REST API Endpoints

The endpoint for creating notifications has been updated to support broadcasts. Here’s how you migrate from the old endpoint to the new one.

The endpoint changes from /notifications to /broadcasts. The structure of the request body remains largely the same, with the key difference being the use of "broadcast" instead of "notifications" in your JSON payload.

diff
- POST https://api.magicbell.com/notifications
+ POST https://api.magicbell.com/broadcasts

{
- "notification": {
+ "broadcast": {
    "title": "Thank you for your order!",
    "content": "We'll notify you when these items are ready.",
    "category": "order_created",
    "topic": "order:33098",
    "recipients": [
      { "email": "dan@example.com" }
    ]
  }
}

For comprehensive details on using the new endpoint to create broadcasts, refer to our REST API reference.

Migrating CLI Commands

If you're using the MagicBell CLI, the command to create a notification has been updated to create a broadcast. Only the command name has changed, with all other parameters remaining the same.

diff
- magicbell notifications create \
+ magicbell broadcasts create \
  --title "Thank you for your order" \
  --content "We'll notify you when these items are ready." \
  --category "order_created" \
  --recipients "person@example.com"

For more details on CLI commands for creating broadcasts, visit our CLI documentation.

Wildcard recipients

With broadcasts, it's no longer possible to send notifications to all users by using the SQL-like "matches". Instead, we recommend using topics to target multiple users.

Summary

This migration streamlines the process of sending messages to your users, ensuring a more organized and effective communication strategy. By updating your CLI commands and REST API calls as outlined, you can take full advantage of MagicBell’s enhanced messaging capabilities.

For any further questions or to explore more features, feel free to dive into our documentation or join our community discussions for support.