Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
13. Chat gateways: talk to your agent from Telegram and Discord
Read docs/prompts/README.md first.
The problem
Telegram is outbound only today (alerts, digests, the changelog push in api/cron/changelog-push.js, launch delivery in api/pump/[action].js). Discord appears only as embed card metadata. The one conversational bot in the tree, workers/okx-chat-bot/, is a partner lane, not a three.ws agent gateway. A user cannot open Telegram, message their agent, get a reply that used the agent's tools and wallet, and continue the same conversation on the web. The best agent platforms live where the user already is, from a single gateway process, with continuity across surfaces.
Build
Gateway worker
A new workers/agent-gateway/ (Node, Cloud Run, its own cloudbuild.yaml pinning the build and runtime service accounts, README) that runs Telegram (grammY or telegraf, whichever is already a dependency; otherwise grammY) and Discord (discord.js) adapters behind one Gateway interface: onMessage, sendText, sendMedia, sendChoice (buttons), editMessage, typing. Long polling for Telegram in development, webhooks in production (api/gateway/telegram.js, api/gateway/discord.js verify signatures and enqueue). Both tokens come from the Cloud Run env (TELEGRAM_BOT_TOKEN exists; add DISCORD_BOT_TOKEN, DISCORD_APP_ID, DISCORD_PUBLIC_KEY).
Pairing
/start on Telegram or /three link on Discord prints a code; the user redeems it with POST /me/link-code/redeem from prompt 05 (through the settings page /settings/connections, in data/pages.json) or pastes a code the site generated. A migration for gateway_links (platform, platform user id, chat id, account, default agent, created, revoked). /agents lists the account's agents; /use <agent> sets the default for that chat; /unlink revokes.
Conversation
- Every message runs through
POST /agents/:id/messagesfrom prompt 05 with achannelfield, so history is one thread across web, Telegram and Discord (three://agents/{id}/chatshows all of it with the channel tag). - Tool calls stream as a typing indicator plus a compact "working: swap_quote" status line edited in place; the final reply carries links to signatures and pages.
- Financial tools: the confirm flag is never set from chat text alone. The gateway renders the preview as a message with Approve and Cancel buttons; only the button press with the matching
preview_idsets the flag, and it expires with the preview. The prompt 03 policy applies unchanged, including the per-key tool tier. - Voice notes on Telegram are transcribed with the speech path already used by the assistant widget (
docs/assistant-widget.md); images go to the vision path (docs/3d-vision.md). - Slash commands on both platforms:
/balance,/portfolio,/runs,/launches,/help, plus/newto start a fresh thread. - Rate limits per link, and the gateway refuses to pair a chat to more than one account.
Outbound continuity
Notifications from api/_lib/notify-prefs.js gain telegram and discord channels that deliver to the linked chat: alerts, run completions, received bids, incoming mail, so the user can reply in place.
Docs and wiring
docs/chat-gateways.md (new) linked from docs/start-here.md: pairing, commands, what can and cannot be approved from chat, privacy. workers/agent-gateway/README.md. Cloud Scheduler is not needed; note the webhook URLs in docs/ops/gcp-production.md. STRUCTURE.md rows. data/changelog.json entry tagged feature.
Acceptance
- Pair a Telegram chat with the QA account, ask "what is my balance", and receive the same number the web wallet shows.
- Ask for a swap: receive a preview with buttons; Cancel leaves no transaction; Approve stops at the owner's confirmation table in your report (gate 1).
- The exchange appears in the web chat history with the channel tag.
- Same on Discord in a server the owner controls.
npm testgreen with adapter unit tests and webhook signature tests.