Permissions & Intents
Understand how endpoint permissions and event intents control what your bot can do.
Endpoint Permissions
Some Bot API endpoints require a permission. The permission is checked against the
bot's archetype (role) in the target space. If the bot's role does not include the required permission, the request
returns 403.
Permissions are shown on each endpoint's documentation page as a badge. Endpoints without a permission badge are accessible to any authenticated bot.
Common Permissions
Privileged Endpoints
Endpoints marked Privileged require the bot to be verified. These endpoints access sensitive data or perform actions that require higher trust.
Unverified bots calling a privileged endpoint receive 403
with error code not_verified.
Event Intents
When connecting to the SSE event stream, you specify which event categories to receive via a bitmask. Each bit corresponds to an intent.
Pass the intent bitmask as the intents query parameter
when connecting to /api/bot/IEvents/v1/Stream.
Standard Intents
Available to all bots.
Privileged Intents
Require bot verification. Unverified bots requesting these intents will not receive the corresponding events.
Calculating the Bitmask
Combine intents using bitwise OR. For example, to subscribe to Messages + Channels + Voice:
Messages = 1 << 0 = 1 Channels = 1 << 1 = 2 Voice = 1 << 11 = 2048 ───────────────────────── intents = 2051
Tip: Use intents=0 to receive
only connection lifecycle events (Ready, Heartbeat, Resumed) without any space events.