Engineering record — internal detail. The manual is authoritative for product behaviour.
Telegram integration
Replacing the WhatsApp gateway with a Telegram bot: chat-ID allowlist, secret-token webhook, approval parity with the web app, and media upload.
Scope
A Telegram bot in front of the shared chat core, so the same intents and handlers serve both the web assistant and the phone. Three tables carry the state: a user-to-chat mapping, a message log and a pending action. Approvals from Telegram run the identical transaction as web approvals — one journal entry, one audit entry.
Note
Why Telegram over WhatsApp
Chosen for lower friction in East Africa, where the target users already use Telegram heavily. The shared chat core meant the transport swap did not require rewriting the AI orchestration.
Security model
- Chat-ID allowlist: only mapped chats reach any data; everything else is ignored except /start.
- One chat ID maps to one member (unique constraint), and only within the same organisation.
- The webhook is signed with a secret token and fails closed when the secret is absent.
- Inbound messages deduplicate on Telegram's message ID, so retries never double-process.
- Approvals require a second YES/NO confirmation that expires after 15 minutes.
- Role and organisation scoping are applied to every tool call.
Implementation status
Recorded as operational: the webhook is live, a CEO chat is mapped, and dedupe is verified. The plan noted approval parity as the remaining item; the approvals manual now records the web and Telegram approval paths as sharing one handler, so this should be re-verified against the current build before it is treated as closed.
Source records
- Design
- docs/superpowers/specs/2026-08-01-telegram-integration-design.md
- Plan
- docs/superpowers/plans/2026-08-01-telegram-integration-plan.md