Choosing permissions
A permission is the unit of consent a bot asks a DJ for. You can only request the permissions registered on your app, and only the ones the DJ approves actually work.
The Spec column takes you straight to the endpoint each permission opens. Use this page to decide what to ask for.
The eleven permissions
| Scope | Name the DJ sees | What it grants | Spec |
|---|---|---|---|
live.read | View my broadcast info | Title, start and end times, listener count, greeting, categories, chat-frozen state | Read the current broadcast |
listeners.read | View my broadcast's listener list | The id and nickname of listeners in the room | List listeners |
fans.read | View my broadcast's fan ranking | Listeners ranked by donation | Read the fan ranking |
events.chat | View my broadcast's chat | Listener chat and DJ quick messages, in real time | Event stream · chat |
events.presence | See who joins my broadcast | Listener joins, in real time | Event stream · presence |
events.like | View my broadcast's hearts | Hearts listeners send, in real time | Event stream · like |
events.donation | View my broadcast's donations | Donor, total spoons, and note, in real time | Event stream · donation |
chat.send | Send chat to my broadcast as the bot | Posting under the bot account's name | Send chat |
Which combination do you need
Request only what your bot actually uses. The more permissions on the consent screen, the more DJs hesitate to approve.
| The bot you are building | Permissions needed |
|---|---|
| Replies to chat | events.chat · chat.send |
| Announces broadcast start and end | live.read · chat.send |
| Welcomes listeners who join | events.presence · chat.send (requires the DJ's manager appointment) |
| Thanks people for donations | events.donation · chat.send |
| Tallies hearts toward a goal | events.like · chat.send |
| Draws a raffle from the listeners | listeners.read · chat.send |
| Reads out the fan ranking | fans.read · chat.send |
| Tallies attendance and rankings | events.chat · events.presence · live.read |
How to request them
List them in the scope parameter of
Getting a DJ's consent, separated by spaces.
Encode the spaces as %20 in the URL.
&scope=events.chat%20events.presence%20chat.send
Consent accumulates. To add a permission later, show the consent screen again with the expanded set, and the DJ sees only the newly requested permissions.
The scope on an issued token reflects the DJ's consent at that moment. Check it on
every refresh — see Tokens for the details.
Two things to know
Event permissions share one connection
The four permissions starting with events. share a single connection.
- The event stream opens if any one of them is granted.
- Events you did not get consent for are filtered out. The connection is healthy while that event type never arrives.
- With none of them, you get a
403.
Some permissions need more than consent
events.presence only works once the DJ appoints the bot as a manager.
With consent but no appointment it does not fail at all. The stream opens with 200
and chat arrives normally, while presence never does, which makes it hard to
diagnose. The broadcast server publishes join notifications at manager level.
The procedure is in Event stream.
Related documents
- Endpoint list — which endpoint each permission opens.
- Getting a DJ's consent — ask for the permissions you picked.
- Build a bot — a minimal end-to-end example.
- Tokens — issuing, refreshing, and revoking.
- Error codes — what to check when you get a
403.