Skip to content

Add a guide to building bots, with tested examples - #51

Merged
ssenerg merged 5 commits into
mainfrom
bots-guide
Nov 2, 2026
Merged

ssenerg merged 5 commits into
mainfrom
bots-guide

Conversation

@ssenerg

@ssenerg ssenerg commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner

A getting-started guide for people building bots, with examples that were run against a real server.

What changes

  • docs/bots.md: making a bot (Settings → Bots, a team, channels, keeping and resetting the token); the three ways to get updates and when to pick each (the socket through pkg/gochat, getUpdates with its offsets and 409, webhooks with https, public addresses, the secret, retries and ordering); commands and /cmd@bot, buttons and answering presses, privacy mode against sees_all, errors, limits, what a bot may not call; running one in production (systemd, a container, reconnecting, keeping pts).
  • examples/dicebot: a Python 3 bot over the HTTP Bot API with long polling and nothing but urllib and json: /roll, /roll@bot 20, and a Roll again button that edits its message.
  • examples/webhookbot: a Go webhook receiver that checks X-GoChat-Bot-Secret in constant time, answers 2xx, and answers /ping over the HTTP Bot API; it has a unit test.
  • examples/echobot writes its pts file atomically, as the guide advises.
  • The end-to-end bots test runs the Python example against the stack.
  • README.md and the Bots section of docs/protocol.md link the guide.

#50 merged while this was open, so the guide covers openDirect too: a section on writing to a person first, with a curl snippet, c.OpenDirect, echobot's /remindme, its rules and the 30-an-hour limit. The protocol.md conflict with #50 kept both sides.

Fixed in protocol.md

What the run showed to be wrong or missing:

  • error_code in the HTTP Bot API is the HTTP status (403), not the protocol's code (7).
  • ListMessages needs sees_all as ListThread does; in privacy mode GetMessage reads only what the bot was sent.
  • Bots also get TeamJoined and TeamLeft.
  • "More wait their turn" holds only under the frame limit: past 40 frames in a burst the server closes the socket.
  • Calls over the request budget answer an ApiError, not the ok envelope (see below).

How it was tested

On a throwaway stack: its own compose project for Scylla and MinIO (ports 19042, 29000), and the server and gateway binaries on 17070 and 18080. The running gochat-* stack was left alone.

  • Settings → Bots: create, add to a team, add to channels from Members, Manage → sees_all, Reset token, Delete.
  • Every shell block in the guide, verbatim except for the URL, token and channel id.
  • echobot over the socket: a command, its button, catching up from -state after downtime, exiting on a reset token.
  • dicebot: /roll, /roll@dice_bot 20, ignoring /roll@other_bot, replies in threads, the button's edit, 409 against a second poller, catching up after a restart, riding out 500s, exiting on a reset token; also in the guide's container.
  • webhookbot: 401 without the secret, /ping delivered and answered, retries delivered in order after downtime, last_error for a wrong secret, TLS with -cert/-key, a clean shutdown. On a server without allow_private_webhooks: http, loopback, private and credentialed URLs refused, and https://localhost refused at delivery.
  • Errors, the request budget (first 429 after 124 calls) and the post rate (429 after 20).
  • The systemd unit with systemd-analyze verify in a Debian container; it was not run under systemd.
  • The end-to-end suite against the stack: every bots step passes, the new one included. The voice tests fail there, for lack of a voice server.
  • After merging Let a bot open a direct conversation with a person #50, on a fresh stack: the openDirect snippet, posting in the conversation, opening it again, 404 for someone not in the team, 400 for another bot, 403 when blocked (opening and posting), echobot's /remindme 2s, and the end-to-end suite again (every bots step, Let a bot open a direct conversation with a person #50's and the Python one, passes).

Server issues found, not fixed here

  1. Over-budget Bot API calls lose the envelope. The throttle runs before botAPI, so a 429 answers {"code": 8, "message": "too many requests, slow down"} instead of {"ok": false, "error_code": 429, ...}. A client that reads ok and description sees neither. The guide and the spec describe it as it is.
  2. The frame limit is below the request budget on protocol sockets. gateway.frame_rate (10/s, burst 40) applies to /api/v2/socket and closes it with 1008, while the budget allows 30/s, burst 120. pkg/gochat sends each call as it is made, so 100 concurrent Calls close the socket and every one fails with ErrLost. The socket could queue or answer code 8, or the SDK could pace.
  3. A bot in town-square stays there. Bots are not added to it with the team, but once added, RemoveChannelMember and LeaveChannel refuse ("every team member stays in this channel"), so its sees_all mode there can never change. The guide says to choose before adding it.
  4. The end-to-end bots test assumes the admin owns no other bot. botIDRe takes the first bot on the settings page, so it fails on a reused stack where the admin owns a bot that sorts first. CI starts fresh, so it passes there.

@ssenerg
ssenerg enabled auto-merge (squash) November 2, 2026 11:17
@ssenerg
ssenerg merged commit adf7787 into main Nov 2, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant