Broadcast Primitive

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

The URL recipients will be directed to when interacting with the broadcast.

max length: 2048
category
nullable string

The label used to group broadcasts.

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

The body content delivered with the broadcast.

max length: 10485760
created_at
string

The timestamp when the broadcast was created.

format: date-time
custom_attributes
nullable object

Arbitrary custom data associated with the broadcast.

id
string

The unique id for this broadcast.

format: uuid
overrides
nullable object

Channel- or provider-specific values that override the defaults.

Show child attributes
providers
object

Overrides that are scoped to specific providers for a channel.

Show child attributes
sendgrid
object

Provider-specific overrides for Sendgrid.

twilio
object

Provider-specific overrides for Twilio.

mailgun
object

Provider-specific overrides for Mailgun.

fcm
object

Provider-specific overrides for Firebase Cloud Messaging.

apns
object

Provider-specific overrides for Apple Push Notification service.

web_push
object

Provider-specific overrides for the web push provider.

teams
object

Provider-specific overrides for Microsoft Teams.

ses
object

Provider-specific overrides for AWS SES.

expo
object

Provider-specific overrides for Expo push notifications.

slack
object

Provider-specific overrides for Slack.

channels
object

Overrides that are scoped to individual delivery channels.

Show child attributes
sms
object

Overrides for SMS notifications.

Show child attributes
title
string

The channel-specific title.

min length: 1
max length: 255
content
string

The channel-specific content.

max length: 1048576
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
in_app
object

Overrides for in-app notifications.

Show child attributes
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
title
string

The channel-specific title.

min length: 1
max length: 255
content
string

The channel-specific content.

max length: 1048576
mobile_push
object

Overrides for mobile push notifications.

Show child attributes
title
string

The channel-specific title.

min length: 1
max length: 255
content
string

The channel-specific content.

max length: 1048576
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
email
object

Overrides for email notifications.

Show child attributes
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
title
string

The channel-specific title.

min length: 1
max length: 255
content
string

The channel-specific content.

max length: 1048576
recipients
nullable array required

A collection of users or filters that determine who receives the broadcast.

min items: 1
max items: 1000
Show child attributes
(array item)

The recipient specification for the broadcast.

status
object

The runtime state of the broadcast execution.

Show child attributes
status
string required

The overall processing status of the broadcast.

Possible enum values:
enqueued
processing
processed
summary
object required

The summary counts for total recipients and failures.

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

A list of errors encountered while processing the broadcast.

Show child attributes
(array item)
object
Show child attributes
message
string

The details about the processing error.

title
string required

The subject or headline that will be shown to recipients.

min length: 1
max length: 255
topic
nullable string

The topic that further classifies the broadcast.

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": {}
}