Reference

Events, actions, errors, configuration and routes, as the runtime defines them. Names below are the Rust ones; the Python SDK uses upper-case nested names (BotEvent.MESSAGE_CREATED) and the Node SDK uses lower-case types (message, dm_message, member_joined, see types.ts in the SDK).

Ids and times

Ids (servers, channels, users, roles, DMs) are hyphenated lowercase UUID strings. 32 bare hex digits are accepted as input. A message is addressed by its channel id and timestamp_ms, the server’s timestamp for it. Times are milliseconds since the epoch.

Intents

Config names are lower case. Unknown names are an error. Connected, Disconnected, WaitingForInstall, Fatal and Error are delivered whatever the intents.

Events

Runtime (always delivered)

Lifecycle

Messages, reactions, DMs

Members, channels, voice

Interactions

Interaction carries interaction: a BotInteraction.

Records

Actions

Every action is one runtime call, answered at once: either a local refusal (nothing was sent) or “handed to the socket”. A refusal by the server comes back later as an Error event. In Python they are awaitable, in Node they return promises; names are snake_case in Python and camelCase in Node.

Rust also has next_event(timeout_ms) (waits up to the timeout, None on timeout or when the runtime has stopped) and is_finished(). The Python and Node layers turn those into events() and run_forever() / bot.on(...). A bot socket may only call the requests the server allows bots (messaging, reactions, DMs, roles, channels, voice, the encryption calls, moderation, leaving a server, its own profile and devices); it can never join a server or create an invite.

Errors

An action that fails locally returns or raises one of these. Nothing was sent.

Python raises BotError.<Variant> for these and BotFatalError from run() after a Fatal event. Node throws BotError with a code, and emits server refusals as a runtime_error event (not error, which throws in an event emitter with no listener).

Configuration

The TOML file given to hexis-bot run, python -m hexis_bot.echo and bot_config_from_file. Unknown keys are an error.

The Node constructor takes the same values as token, stateDir, endpoint, botUserId, intents. The echo bots default to the intents lifecycle, interactions, messages and dms.

Environment variables

These variables are conveniences of the examples, not part of the runtime’s API; your own bot reads its settings however it likes.

HTTP routes

App management lives on the regional gateway (https://us-east-1.hexis.chat) under /api/v1. These routes need a signed-in account session (the same cookie the account portal uses), not the bot token. Create, update and reset ask for a fresh second factor when the account has one.

The App object

is_public_client means an OAuth PKCE client (no client secret); it has nothing to do with a public bot. The fields are public_id, name, description, homepage_url, redirect_uris, allowed_scopes, is_public_client, approved, approved_at, created_at, has_bot_token, bot_user_id, bot_token_issued_at, suspended (an operator killed the bot). It never holds the token or its hash. client_id appears on the create answer. A privileged_intents field is arriving with the event gateway arriving.

Route errors

Status and close codes on the bot socket

The bot socket is a WebSocket on the endpoint above. The token goes in the x-api-key header of the upgrade request.

What you see for a dead token, then, is almost always a Disconnected event, a short wait, and Fatal with TokenRefused. For a suspended owner the token works again once the suspension ends; start the bot again.

Request-level refusals on an open socket: a call a bot may not make is refused as not accessible; a rate-limited send is refused with a “Rate limit: wait Ns.” message; a direct message to someone who shares no server with the bot is refused with “Bots can only message people in a server they share.” Both show up as Error events.