Broadcast

A broadcast captures a noteworthy change that you want to notify your users about. It can be anything from a new message in a chat app to a new order in an e-commerce platform. MagicBell provides a simple API to create broadcasts and specify recipients.

Broadcasts have the following characteristics:

  • They target specific recipients, which can be individual users or topics with subscribers.
  • They contain title and optional content that gets delivered to recipients.
  • They can include custom attributes for application-specific data.
  • They support channel-specific overrides to customize the content for different delivery channels.
  • They provide status tracking to monitor delivery progress and failures.

Lifecycle

  1. You create a broadcast with recipients and content.
  2. MagicBell processes the broadcast, creating notifications for each recipient.
  3. Notifications are delivered through configured channels based on user preferences.
  4. Status information tracks the progress and any delivery failures.

Best Practices

  • Keep broadcast titles concise and descriptive.
  • Use categories and topics to organize broadcasts for better user preference management.
  • Leverage channel-specific overrides when content needs to be formatted differently for various channels.
  • Monitor broadcast status to identify and address delivery issues.
  • Use custom attributes to add contextual information that might be useful in your application.

Schema

POST
/broadcasts
Schema Type: "object"
Required Fields:
titlerecipients

Properties

overrides ["object","null"]
title "string"
required
content ["null","string"]
created_at "string" readonly

The timestamp when the broadcast was created.

category ["string","null"]
status ["object","null"]
id "string"

The unique id for this broadcast.

action_url ["null","string"]
topic ["string","null"]
custom_attributes ["null","object"]
recipients ["null","array"]
required

Example Request

{
  "id": "d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "title": "Hello, World!",
  "content": "Hello, World!",
  "action_url": "https://example.com",
  "category": "example",
  "topic": "example",
  "custom_attributes": {},
  "recipients": [
    {
      "external_id": "83d987a-83fd034",
      "email": "test@example.com",
      "first_name": "Person",
      "last_name": "Doe",
      "custom_attributes": {
        "plan": "enterprise",
        "pricing_version": "v10",
        "preferred_pronoun": "They"
      },
      "phone_numbers": [
        "+1 5005550001"
      ]
    }
  ],
  "overrides": {}
}

Example

Broadcast{
  "id": "d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "title": "Hello, World!",
  "content": "Hello, World!",
  "action_url": "https://example.com",
  "category": "example",
  "topic": "example",
  "custom_attributes": {},
  "recipients": [
    {
      "external_id": "83d987a-83fd034",
      "email": "test@example.com",
      "first_name": "Person",
      "last_name": "Doe",
      "custom_attributes": {
        "plan": "enterprise",
        "pricing_version": "v10",
        "preferred_pronoun": "They"
      },
      "phone_numbers": ["+1 5005550001"]
    }
  ],
  "overrides": {}
}