Widget Integration
Embed the Ding! widget on any third-party website to display a real-time notification feed for one of your channels. Subscribers see new messages live without leaving the host site.
Integration is two short steps, both server-side:
- Authenticate as the channel owner and mint a short-lived widget token for one of your subscribers.
- Embed the widget script on your page, passing only the widget token — your channel API key never leaves your server.
Base URL
Authenticate
Two tokens, both server-side only — never embed either in the browser:
- Owner JWT — your Ding! account session token. Obtained once via Login.
- Widget token — a short-lived token bundling
channel_id+user_id. Mint one per page-load on your server using the owner JWT, then pass it to the widget. See Mint Widget Token.
Your channel API key never leaves your server — the widget authenticates entirely with the widget token.
Login
Authenticates the channel owner with their Ding! account credentials and returns the owner JWT.
Response
{
"token": "owner-jwt-string"
}
Mint Widget Token
Mint a widget JWT scoped to one (channel, subscriber) pair. The owner JWT must be presented in the Authorization header. The caller must own the channel; otherwise the request is rejected.
Tokens expire after 7 days. Mint a fresh one per page-load on your server.
Authorization: Bearer <owner-jwt> Content-Type: application/json
{
"user_id": "subscriber-uuid"
}
Response
{
"token": "widget-jwt-string",
"expires_at": "2026-05-11T08:00:00Z"
}
Pass the returned token directly to the widget script tag — see Embed & Receive.
Embed & Receive
The embeddable widget displays a real-time notification feed for a channel on any third-party website. The widget authenticates via a short-lived widget token that bundles the channel ID and user ID — your channel API key never leaves your server.
Embed Widget
Include the following <script> tag in any HTML page. Mint the token server-side via Mint Widget Token — never embed the channel API key in the page. The widget renders a floating bell launcher button (bottom-right) by default, or attaches to an existing element via tag_id.
<script src="https://qwikbroad.app/widget.js ?token=WIDGET_TOKEN"></script>
| Parameter | Required | Description |
|---|---|---|
| token | Yes | A widget JWT minted from POST /api/channels/:id/widget-token. Encodes channel_id + user_id; valid for 7 days. |
| tag_id | No | DOM element ID to use as the launcher instead of the default floating button. |
Widget Messages
Retrieve messages for the widget view. Authenticated by the widget token.
Widget Polling for New Messages
The widget polls /api/widget/messages with a since=<RFC3339Nano> cursor every few seconds to pick up new messages. No persistent connection is required.