docs: add bot platform support matrix - #4787
Draft
ying-hua wants to merge 4 commits into
Draft
Conversation
Document the eight IM bot channels registered in BOT_PROVIDERS: their transports, credential fields, capability parity, message limits, known limitations and security posture. Every claim is derived from the bridge implementations rather than from prose, and is cited by symbol name rather than line number so the references survive refactors. Setup instructions per platform are deliberately left as marked placeholders. The issue requires them to be tested against real developer accounts, and untested setup steps are worse than none. Refs apache#3894 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Walked the Feishu channel end-to-end against a real custom app and documented what the runtime actually requires: bot capability, the im:message.p2p_msg:readonly scope, im.message.receive_v1 delivered over a long connection rather than a webhook, and a released version whose availability range covers the intended users. Both directions were exercised: an outbound bot DM, and an inbound user reply received over the WebSocket long connection. Also corrects the Feishu row of the credential table. The bridge reads `appSecret` or, when empty, falls back to `token` — the two are interchangeable and only one is needed. The table previously implied Feishu takes three distinct credentials. Records the failure mode the walkthrough surfaced: the handshake succeeds on app credentials alone, so an unreleased app yields a channel that reports a healthy connection while no user can find the bot to message it. Refs apache#3894 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Walked the WeCom channel end-to-end against a real AI bot. Both directions were exercised with the same SDK version the runtime pins (@wecom/aibot-node-sdk 1.0.7), mirroring WeComBotBridge.start(): the WebSocket handshake authenticated, an inbound single-chat frame arrived, and an outbound markdown send returned a req_id. Records the decision that governs every other step: the channel is the 智能机器人 in API mode, not a custom app, not a group webhook, and not 普通模式 — the latter answers messages with WeCom's own hosted models, so nothing reaches the long connection. Documents the addressing consequence observed in the inbound frame. A single-chat frame carries no chatid at all, which is why the bridge falls back to the sender's userid, and why a WeCom conversation cannot be addressed until the bot has received a message in it. Also notes that private deployments cannot work, since the SDK endpoint is fixed and the bridge exposes no override. Clarifies globally that an empty matrix cell means Maka does not implement the capability, not that the platform lacks it: the WeCom SDK offers streaming replies, media upload and template cards that the bridge never wires up. Refs apache#3894 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Walked the QQ channel end-to-end against a real bot, mirroring QQBotBridge and the GatewayBridgeBase lifecycle it inherits. All three startup steps were exercised — app access token exchange, gateway URL fetch, and WebSocket IDENTIFY reaching READY — followed by an inbound C2C dispatch and an outbound send that returned a message id. Documents the failure taxonomy the code encodes but the console does not explain: 4014 and 4004 are fatal closes that stop the bridge, while every other code reconnects with backoff, so a channel that dies and stays dead is almost always a missing intent or bad credentials. Records the addressing scheme, since QQ is the only platform whose chat IDs carry a prefix. Four inbound dispatch types map to four prefixes and four REST routes, and an unprefixed chat ID is dropped before any network call. Notes three things the walkthrough surfaced: the console's Token field belongs to webhook mode and is never read; group and guild traffic only arrives when the bot is @-mentioned; and QQ supplies no display name for group or C2C senders, so the bridge uses the bot-scoped openid as the user name. Also flags that the API host is hardcoded to production, so a sandbox-confined bot cannot be exercised through this channel. Refs apache#3894 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
1 participant
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.
Refs #3894.
Adds
docs/bot-platforms.mdcovering the eight IM bot channels registered inBOT_PROVIDERS, plus an index entry indocs/README.md.What's in it
feishuchannel and are separated by thedomainsetting rather than by provider.BotReadinessStateenum instead of inventing a parallel vocabulary, and notes that readiness is per-install runtime state rather than a static grade of the code.Claims are cited by symbol name rather than line number, so the references survive refactors.
Three things the matrix surfaced
These may deserve their own issues; flagging rather than fixing here since this PR is documentation only.
allowedUserIdsis enforced by three of eight bridges. Telegram, Feishu and WeCom check it. Discord, QQ, DingTalk, Slack and WeChat never read the field, so an allowlist configured on those channels silently does nothing.SendCapableis text-only. Telegram and WeChat classify inbound attachments; the other six surface no attachment metadata.BOT_DELIVERY_PROVIDERSand rejected by the coordinator.Why this is a draft
The per-platform Setup sections are left as explicit placeholders. The acceptance criteria require setup instructions to be tested and working, so I would rather land them after walking each platform end-to-end against a real developer account than ship steps I have not run. Everything else here is verifiable against the tree today.
I will fill the setup sections in and mark this ready. Happy to split them into a follow-up PR instead if reviewers would rather take the matrix now.
Verification
npm run check:asf-headerspasses.npm run format:check— the one failure is a pre-existing.claude/launch.jsonissue onmain, untouched by this branch.🤖 Generated with Claude Code