Adding a bot to a guild¶

A bot joins a guild through an OAuth2 authorization with the bot scope. A person who has Manage Server (or Administrator) in the guild opens an authorization link, picks the guild, reviews the requested permissions and confirms. TEBHOS then adds the bot as a member and, if permissions were requested, gives it a role that carries exactly those permissions.

Build the authorization link¶

https://tebhos.com/oauth2/authorize?client_id={application_id}&scope=bot&permissions={permissions}

Parameter	Required	Description
client_id	Yes	The application ID
scope	Yes	`bot`. Other OAuth2 scopes can be added, separated by spaces (URL-encoded as `+` or `%20`)
permissions	No	Permission bit set for the bot's role, as a decimal integer string. Omit it, or use `0`, to add the bot without a role
guild_id	No	Pre-selects a guild in the authorization screen
redirect_uri	Only when required	Needed when the scope is not just `bot`, or when the application has `bot_require_code_grant` enabled. Must match one of the application's registered redirect URIs
response_type	With `redirect_uri`	`code`
state	No	Opaque value returned to your `redirect_uri`

The OAuth2 URL builder on the application page in the TEBHOS app (User Settings, Developer, Applications) builds this link for you: tick bot, choose the permissions, and copy the URL.

Choose permissions¶

permissions is the sum of the permission bits the bot needs. A typical chat bot needs:

Permission	Bit	Value
View Channel	`1 << 10`	1024
Send Messages	`1 << 11`	2048
Embed Links	`1 << 14`	16384
Attach Files	`1 << 15`	32768
Read Message History	`1 << 16`	65536
Add Reactions	`1 << 6`	64

View Channel + Send Messages + Read Message History = 68608:

https://tebhos.com/oauth2/authorize?client_id=1290847135893127168&scope=bot&permissions=68608

The full list of bits is in Permissions. Request only what the bot needs; unknown or reserved bits are dropped.

What the person adding the bot needs¶

A signed-in TEBHOS account with Manage Server or Administrator in the target guild. Without either, the request fails with 403.
Unless they are an Administrator, they can only grant permissions they have themselves. Requesting a permission they lack fails with 403.
If the application has bot_public set to false, only the application's owner can add the bot. Anyone else gets 403.

A bot that is already a member of the guild cannot be added again (409).

What happens when the bot is added¶

The bot user becomes a member of the guild. Member-count limits and bans are not checked for bot invites.
If permissions is non-zero, TEBHOS creates a role named after the application, holding exactly those permissions (nothing inherited), places it at the top of the role list, and assigns it to the bot.
Guild members receive GUILD_MEMBER_ADD for the bot.
If the bot is connected to the gateway, its session is attached to the guild and it receives GUILD_CREATE, then the guild's events. No reconnect is needed.

Afterwards the bot's access is ordinary role-based access: guild administrators can edit or delete its role, and channel permission overwrites apply to it like to any member. See Permissions.

Add a bot to a group DM¶

The same flow can add a bot to a group DM instead of a guild. Pass channel_id={group_dm_id} instead of guild_id (never both). The person authorizing must be a member of that group DM, and the group must have room for another member. Adding a bot that is already a recipient succeeds without changes.

The authorization screen confirms with this request, which you can also make yourself with a user session:

POST /oauth2/authorize/consent

Requires Authorization: Bearer {session_token}. Rate limit: 60 per minute per IP address.

Field	Type	Description
client_id	string	Application ID
scope	string	`bot`, optionally with other scopes
guild_id?	string	Guild to add the bot to
channel_id?	string	Group DM to add the bot to. Cannot be combined with `guild_id`
permissions?	string	Permission bit set as a decimal string. A negative or non-integer value returns 400
redirect_uri?	string	Required when the scope is not only `bot`, or when the application requires a code grant
response_type?	string	`code`. Only needed when other scopes are present
state?	string	Returned with the redirect

{ "redirect_to": "https://tebhos.com/?code=..." }

If adding the bot fails, the whole request fails and the authorization code in redirect_to is never issued as valid. See OAuth2 for the rest of the OAuth2 flow.

Removing a bot¶

A member with Kick Members can remove the bot from the member list like any other member. The bot can also leave on its own with DELETE /users/@me/guilds/{guild_id}. Deleting the application removes its bot from every guild, see Creating a bot.