Repository navigation
Add a guide to building bots, with tested examples - #51
Merged
Merged
Conversation
# Conflicts: # docs/protocol.md
ssenerg
enabled auto-merge (squash)
November 2, 2026 11:17
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 throughpkg/gochat,getUpdateswith its offsets and 409, webhooks with https, public addresses, the secret, retries and ordering); commands and/cmd@bot, buttons and answering presses, privacy mode againstsees_all, errors, limits, what a bot may not call; running one in production (systemd, a container, reconnecting, keepingpts).examples/dicebot: a Python 3 bot over the HTTP Bot API with long polling and nothing buturllibandjson:/roll,/roll@bot 20, and a Roll again button that edits its message.examples/webhookbot: a Go webhook receiver that checksX-GoChat-Bot-Secretin constant time, answers 2xx, and answers/pingover the HTTP Bot API; it has a unit test.examples/echobotwrites itsptsfile atomically, as the guide advises.README.mdand the Bots section ofdocs/protocol.mdlink the guide.#50 merged while this was open, so the guide covers
openDirecttoo: 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. Theprotocol.mdconflict with #50 kept both sides.Fixed in protocol.md
What the run showed to be wrong or missing:
error_codein the HTTP Bot API is the HTTP status (403), not the protocol's code (7).ListMessagesneedssees_allasListThreaddoes; in privacy modeGetMessagereads only what the bot was sent.TeamJoinedandTeamLeft.ApiError, not theokenvelope (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.echobotover the socket: a command, its button, catching up from-stateafter 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,/pingdelivered and answered, retries delivered in order after downtime,last_errorfor a wrong secret, TLS with-cert/-key, a clean shutdown. On a server withoutallow_private_webhooks: http, loopback, private and credentialed URLs refused, andhttps://localhostrefused at delivery.systemd-analyze verifyin a Debian container; it was not run under systemd.openDirectsnippet, 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
botAPI, so a 429 answers{"code": 8, "message": "too many requests, slow down"}instead of{"ok": false, "error_code": 429, ...}. A client that readsokanddescriptionsees neither. The guide and the spec describe it as it is.gateway.frame_rate(10/s, burst 40) applies to/api/v2/socketand closes it with 1008, while the budget allows 30/s, burst 120.pkg/gochatsends each call as it is made, so 100 concurrentCalls close the socket and every one fails withErrLost. The socket could queue or answer code 8, or the SDK could pace.town-squarestays there. Bots are not added to it with the team, but once added,RemoveChannelMemberandLeaveChannelrefuse ("every team member stays in this channel"), so itssees_allmode there can never change. The guide says to choose before adding it.botIDRetakes 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.