Channel
Channels represent the medium through which users receive notifications (email, mobile & web push). They simplify delivery management and allow you to:
- Decouple delivery logic: Configure and update delivery mechanisms with ease.
- Support multiple mediums: Ensure consistent delivery across various methods.
- Adapt to preferences: Respect user choices via notification preferences.
- Control delivery: Use the Delivery Planner to decide which channels a notification is delivered on and in what order.
By allowing notifications to be managed independently of the delivery channel, MagicBell ensures your notifications reach users on their preferred medium.
Channel Token
Tokens are unique identifiers used to deliver notifications to specific users through certain channels. They ensure notification routing and act as a bridge between MagicBell and external platforms.
Channel tokens have these key characteristics:
- Linked to specific users in your system.
- Can be simple strings or structured data objects.
- Enable delivery to specific accounts and devices.
- Support multiple tokens per channel for different devices.
Tokens are managed via the API or SDKs and you can use the dashboard to see tokens for a user.
For example, to register a token, send a POST request. For example, to save an APNs token:
curl --request POST \
--url 'https://api.magicbell.com/v2/channels/mobile_push/apns/tokens' \
--header 'authorization: Bearer {token}' \
--data '{"device_token":"eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt","installation_id":"development"}'
Lifecycle
- Registration: Once a token is registered for a user, MagicBell uses it for the next notification (unless otherwise specified in the delivery planner).
- Rejection Handling: If a token is rejected by the external platform, MagicBell logs the error and marks the token as discarded.
- Reactivation: If the same token is re-registered, it will be reactivated and used for future deliveries.
Best Practices
-
Register on Sign-In: Register a token when a user signs in to your application. At this point, you can identify the user and access their token.
-
Discard on Sign-Out: Discard tokens when a user signs out by sending a
DELETE
request to the token endpoint. For example:curl --request DELETE \ --url 'https://api.magicbell.com/v2/channels/mobile_push/apns/tokens/{token_id}' \ --header 'authorization: Bearer {token}' \ --data '{}'
-
Keep Tokens Updated: Re-register the token regularly, such as during every application launch or user sign-in. This ensures the latest token is always on file, enabling seamless notification delivery. Registering tokens is idempotent.