Build on Mnema Talk

Bots, integrations and tools for a community that runs on its own server. A bot gets exactly the access an admin gives it, nothing more, and everything here works against any Mnema Talk server from version 3.1.

What you can build

  • Bots are member-like accounts that cannot sign in. They read and post through the REST API, receive events over a WebSocket gateway, register slash commands, and answer with messages, buttons, select menus and modals.
  • Incoming webhooks give a channel a URL that scripts and CI systems post to, with no bot account at all.
  • Outgoing webhooks send a channel's events to your own service as signed JSON over HTTP.
  • Mnemo is a complete bot built on the TypeScript SDK, and a blueprint for your own.

How it fits together

PieceWhereAuthentication
REST APIhttps://<server>/api/bot/v1Authorization: Bot <token>
Gatewaywss://<server>/api/bot/v1/gatewaythe same header, or the token in IDENTIFY
Incoming webhookhttps://<server>/api/webhooks/<id>/<token>the secret in the URL
Outgoing webhookyour URLan HMAC signature you verify

Every server is its own world: a bot is created on one server, by its Owner or an admin with Manage bots, and its token works only there. Ids are UUIDs.

The rules a bot lives by

  • Nothing without a grant. A new bot sees and does nothing until an admin gives it a role and allows that role in channels. Bots do not inherit @everyone.
  • Never more than the person managing it. Nobody can give a bot a permission they do not hold themselves, and anything elevated (Administrator, the admin area) is the Owner's to give.
  • No direct messages. Bots and webhooks never see members' private conversations.
  • Stable contract. The bot API lives under its own versioned path, /api/bot/v1; a breaking change would get /v2 next to it.

Where to go next

Start with Your first bot, then read Concepts. The REST reference and the gateway reference are generated from the server's own API description at the release these docs are pinned to.

Something wrong on this page? Tell us.