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

action_url
nullable string
max length: 2048
category
nullable string
max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
content
nullable string
max length: 10485760
created_at
string

The timestamp when the broadcast was created.

format: date-time
custom_attributes
nullable object
id
string

The unique id for this broadcast.

format: uuid
overrides
nullable object
Show child attributes
channels
object
Show child attributes
in_app
object
Show child attributes
content
string
max length: 1048576
action_url
nullable string
max length: 2048
title
string
min length: 1
max length: 255
mobile_push
object
Show child attributes
action_url
nullable string
max length: 2048
title
string
min length: 1
max length: 255
content
string
max length: 1048576
email
object
Show child attributes
content
string
max length: 1048576
action_url
nullable string
max length: 2048
title
string
min length: 1
max length: 255
sms
object
Show child attributes
content
string
max length: 1048576
action_url
nullable string
max length: 2048
title
string
min length: 1
max length: 255
providers
object
Show child attributes
mailgun
object
fcm
object
expo
object
apns
object
web_push
object
sendgrid
object
twilio
object
ses
object
slack
object
teams
object
recipients
nullable array required
min items: 1
max items: 1000
Show child attributes
(array item)
status
object
Show child attributes
status
string required
Possible enum values:
enqueued
processing
processed
summary
object required
Show child attributes
total
integer required

The number of recipients that the broadcast was sent to.

failures
integer required

The number of failures while processing the broadcast.

errors
nullable array required
Show child attributes
(array item)
object
Show child attributes
message
string
title
string required
min length: 1
max length: 255
topic
nullable string
max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$

Example

Broadcast
{
  "id": "d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "title": "Hello, World!",
  "content": "I come from broadcast",
  "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": {}
}