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
- You create a broadcast with recipients and content.
- MagicBell processes the broadcast, creating notifications for each recipient.
- Notifications are delivered through configured channels based on user preferences.
- 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
id
"string"
The unique id for this broadcast.
title
required"string"
action_url
["null","string"]
created_at
"string"
readonlyThe timestamp when the broadcast was created.
custom_attributes
["null","object"]
recipients
required["null","array"]
status
["object","null"]
content
["null","string"]
category
["string","null"]
topic
["string","null"]
overrides
["object","null"]
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": {}
}