Skip to content

Building bots

A TEBHOS bot is an automated account that belongs to an application. You create the application, TEBHOS creates its bot user and a bot token, and your program uses that token to call the HTTP API and to connect to the gateway, just like a client does.

Every application has:

  • a bot user, with its own username, avatar and profile, whose user ID is the same as the application ID;
  • a bot token, in the form {application_id}.{secret}, which authenticates the bot on the REST API and the gateway;
  • a client secret, used only for OAuth2 flows (for example "Sign in with TEBHOS" on your own website).

A person with Manage Server permission adds the bot to a guild through an OAuth2 authorization link. The bot then appears in the member list with a role that carries the permissions you asked for.

A bot token is a password

Anyone holding the token can act as your bot. Keep it on your server, never ship it in a web page, a mobile app or a public repository, and regenerate it immediately if it leaks.

What a bot can do

A bot reaches most of the API that a regular account can, limited by the permissions its role grants in each guild:

  • receive real-time events over the gateway, including the full content of every message in channels it can view (there are no privileged intents to request);
  • send, edit, delete and pin messages, reply to messages, add reactions, show the typing indicator, and upload attachments;
  • read guild, channel and member information, search members, search messages in a guild or channel it can read, and read user profiles;
  • manage channels, roles, bans and invites when its role grants the matching permission;
  • create and use webhooks;
  • open direct messages and be added to group DMs.

A few account-level endpoints are reserved for human users. Calling one of them with a valid bot token returns 403 with code set to ACCESS_DENIED. Managing applications, for example, always needs a signed-in user.

Not supported on TEBHOS

TEBHOS has no application commands (slash commands), interactions, message components or modals. Bots react to regular messages instead, see Responding to messages.

Authentication at a glance

Where How to send the bot token
REST API Authorization: Bot {application_id}.{secret} header
Gateway The token {application_id}.{secret} in the token field of Identify (op 2). Send it bare; a leading Bot is also accepted

Human users authenticate with Authorization: Bearer {session_token} instead. See Authentication.

Flow

Step What happens Endpoint Page
1 Create an application and its bot POST /oauth2/applications or the TEBHOS app Creating a bot
2 Add the bot to a guild https://tebhos.com/oauth2/authorize?client_id=...&scope=bot&permissions=... Adding a bot to a guild
3 Find the gateway GET /gateway/bot Gateway connection
4 Connect, identify, heartbeat wss://tebhos.com/ws?v=1&encoding=json Gateway connection
5 React to MESSAGE_CREATE and reply POST /channels/{channel_id}/messages Responding to messages

Complete, runnable programs are in Examples. If you only need to post messages into one channel, a webhook is simpler than a bot.

All REST paths on these pages are relative to https://tebhos.com/api/v1.