Telegram Bot pattern — LOCKED conventions for internal AI agents
Context
Aspire deploys multiple AI agents that need 1:1 Telegram comms with team members. Without a locked pattern, each new agent re-invents naming, pairing flow, and message format — leading to bot-name collisions, confused users, and inconsistent UX.
Detail
Decision (locked)
| Convention | Value | Rule |
|---|---|---|
| Bot username pattern | @adg_<name>_bot | All Aspire bots prefixed adg_ (Aspire Digital Group). <name> is the agent's short slug, lowercase, underscore-separated. |
| Bot display name | <Name> AI | Title case + "AI" suffix. E.g. Zac AI, Praew AI, Pom AI. |
| Pairing flow | Pairing DM | First message from a user is captured as a pairing event. Agent stores chat_id against the user's identity in Aspire Hub (or Odoo for staff). Subsequent messages flow via that captured chat_id. |
| No public discovery | All bots locked to invite-only | Don't post @adg_*_bot usernames publicly. Pairing happens via Aspire Hub OR a direct link from another internal channel. |
| Message style | Lowercase-ish, terse | Like Slack DM, not corporate email. |
Why these specifics
adg_prefix: prevents collision with any third-party bot. Also makes provenance obvious in Telegram's bot search.<Name> AIdisplay name: human-readable in chat lists; the "AI" suffix sets expectations (vs a real person).- Pairing DM: avoids OAuth-style flows (overkill for internal use). The first DM IS the auth event.
Implementations following this pattern (per graphify audit 2026-05-20)
sendTelegramMessage() had 15 edges in the aspire-digital-group monorepo audit — Telegram is the primary comms primitive for internal agents. Implementations include morning briefs, daily-brief deliveries, deploy notifications, and ad-hoc agent comms.
Constraints we accepted
- Bots can't be discovered by external users (no SEO/marketing reach via Telegram) — fine for internal-only.
- Pairing-DM means a malicious user who guesses the bot username can attempt to pair. Mitigation: agents require user identity verification against Aspire Hub on first DM.
Revisit trigger
- Aspire's user count exceeds Telegram's per-bot DM rate limits (currently ~30 msg/sec — generous)
- A bot needs to broadcast to a group rather than 1:1
- Aspire builds a customer-facing AI requiring public Telegram presence (Telegram becomes a channel, not the pattern — would need its own design)
Actions
- [x] All bots created since 2026-04 follow
@adg_<name>_bot+<Name> AIconvention - [x]
sendTelegramMessage()helper exists inaspire-digital-groupmonorepo (15 call sites per graphify audit) - [ ] Future: extract
sendTelegramMessage()into apackages/notifications/package (low-priority refactor surfaced by graphify 2026-05-20)
Related
- aspire-hub — bots authenticate users against Hub
- graphify-trial-2026-05-20 — quantifies Telegram dominance (would be referenced once that audit page exists)
🔗 Relationships
graph LR
telegram_bot_pattern["telegram-bot-pattern"]:::self
telegram_bot_pattern --> aspire_hub["aspire-hub"]
telegram_bot_pattern --> graphify_trial_2026_05_20["graphify-trial-2026-05-20"]
classDef self fill:#715EE3,color:#fff,stroke:#291F50;