RFC: Telegram as a PGR notification + interaction channel — feasibility, blockers & approach

[ChakshuGautam]

TL;DR

Can we add Telegram as a channel for PGR complaint notifications — and possibly as a two-way channel where citizens file/track complaints in chat? Short answer: yes, it's feasible, but not through our self-hosted Novu, and the real cost depends entirely on one decision — outbound-only vs bidirectional. This RFC lays out what we found (grounded in the live Bomet stack + the Telegram Bot API) and the decisions we need to make before building.

This is a sibling to the config-driven notification work (flattened RAINMAKER-PGR.NotificationRouting/NotificationTemplate, novu-bridge pass-through, SMS→Twilio / Email→Gmail-SMTP via Novu, WhatsApp→Baileys direct). It also feeds the separate effort to refactor how we manage notification configuration (channels are currently a closed enum + per-tenant MDMS rows; adding channels like Telegram is the pressure test for that model).

---

1. How notifications work today (context)

• MDMS RAINMAKER-PGR.NotificationRouting is flattened: one row per (businessService, action, toState, audience{CITIZEN|EMPLOYEE}, channel{SMS|WHATSAPP|EMAIL}), joining 1:1 with NotificationTemplate.
• pgr-services resolves the recipient (CITIZEN→citizen, EMPLOYEE→assignee), renders + localizes the body from MDMS, and publishes one pre-rendered per-recipient event to Kafka complaints.domain.events. The event's Contact carries {userId, type, name, phone, email, locale} — no chatId.
• novu-bridge is a thin pass-through: SMS/Email → identify Novu subscriber + trigger the per-channel Novu workflow (Twilio / Gmail-SMTP); WhatsApp → POST directly to a self-hosted baileys-send-service (because Novu has no usable WhatsApp provider).

So the channel set is a closed enum and adding one touches: the MDMS schema enum, routing+template rows, the recipient→contact resolver, and the novu-bridge dispatch switch.

---

2. Can Novu deliver Telegram? Not on our version.

Telegram is a first-class Novu chat provider upstream — but it was added on 2026-05-18, ~11 months after our pinned release. Our self-hosted Novu Community Edition v2.3.0 (Bomet) ships no Telegram provider (verified: the novu-worker:2.3.0 image bundles slack, whatsapp-business, discord, msTeams, rocket-chat, mattermost, zulip, … and no telegram; ChatProviderIdEnum at the v2.3.0 tag has no Telegram member; the live org has only in_app/sms/email integrations).

⚠️ Phantom-201 trap: our CE integrations API does not validate providerId — POSTing a fake telegram integration returns HTTP 201 and creates a record, but no worker handler backs it, so nothing ever delivers. Don't trust the 201.

Conclusion: Telegram on our stack = a direct bot service (a "Baileys-mirror" holding the @Botfather token), not Novu — unless/until we do a major Novu upgrade. Going direct means Telegram also gets none of Novu's delivery logs / retries / tracking for free.

---

3. The Telegram constraints that shape the design

• A bot cannot initiate. It can only message a user who has already /started it (Telegram platform rule; Novu can't bypass it). Stakeholder has accepted the opt-in: citizens will be asked to initiate the chat.
• chat_id is a routing identifier, not an auth credential. A /start gives you a chat_id (+ first name, maybe username) — not the citizen's phone or DIGIT identity. Unlike a WhatsApp number, the chat_id proves nothing about who the person is.
• One bot token = one inbound consumer. getUpdates and setWebhook are mutually exclusive, and a second consumer gets 409 Conflict. This bites only the inbound (bidirectional) side — send-only is a plain HTTPS call that scales across replicas.
• 403 on blocked/never-started. sendMessage returns 403 Forbidden: bot was blocked by the user — needs a chat_id status + cleanup path.

---

4. The binding problem (and the good news)

The deepest issue with a citizen channel: after /start you must bind the chat_id to the right eg_user — both to address outbound and to authorize anything inbound. A wrong binding silently routes a citizen's notifications (and PII) to someone else.

Good news (verified against the Telegram API): the request_contact keyboard button sends the sender's own phone number — there is no address-book picker, so a user cannot share someone else's number through it. Therefore:

request_contact → match the shared phone to eg_user.mobilenumber is a trustworthy binding — the same trust level SMS already relies on. An OTP round-trip (reusing /user-otp) is optional defense-in-depth, not a hard requirement.

Bindings must be tenant-qualified and unique (mirroring eg_user's (id, tenantid) PK), with rebind-reverify and explicit unbind. The chat_id store does not exist today (eg_user has no Telegram column; the Contact model carries only phone/email) — it's a prerequisite for both directions.

---

5. The decision that sets the effort: outbound-only vs bidirectional

	Outbound-only (notify on Telegram)	Bidirectional (file/track in chat)
Effort	Contained — ~WhatsApp/Baileys parity	Large greenfield
Send	Plain HTTPS, scales across replicas	same
Inbound consumer	none	singleton per tenant (one-token-one-consumer), no HA replicas
Auth	none (send to a bound chat_id)	must re-implement citizen scoping off Keycloak/OTP
New machinery	send client + chat_id store + /start binding	all that + inbound router, command parsing, session, abuse/rate-limit defense, forged-webhook protection

PGR scopes a citizen to their own complaints purely from a validated Keycloak JWT (accountId = userInfo.uuid, search by mobileNumber). A chat_id gives you no such principal — so the bidirectional "track/file my complaint" path needs an explicit binding + authorization model, and the existing mobileNumber search is an enumeration primitive that must never be exposed to a user-typed number (only the uuid/mobile bound to this chat).

---

6. Gates, work-items, and governance

3 gates (must not skip):

1. Don't treat chat_id as auth — bidirectional actions act only on the identity bound to that chat.
2. Binding integrity is the PII firewall — unique, tenant-qualified, reverify-on-rebind.
3. Silent-SMS footgun: novu-bridge defaults unknown channels to complaints-sms/Twilio. A TELEGRAM routing row with no code change sends a Twilio SMS and logs it as channel=TELEGRAM, SENT. Add an explicit branch; make unknown channels throw, never fall back.

Serious work-items: rebuild delivery logging/retry/idempotency off-Novu (reuse the bridge's transactionId-keyed dedup from inside process()); 403-blocked chat_id cleanup (status field); Telegram rate limits (~1 msg/s per chat, 429 retry_after); MarkdownV2/HTML escaping of pre-rendered bodies; per-tenant token + webhook route + MDMS rows + secret custody (OpenBao); webhook forgery protection (X-Telegram-Bot-Api-Secret-Token, IP allow-list); citizen lifecycle (phone change, multiple chats, cross-tenant).

Governance calls: PII egress to Telegram cloud + Kenya DPA 2019 consent/residency (DPIA, minimize PII in messages → complaint id + status + link); coverage/cost-benefit (Telegram penetration in the counties is well below WhatsApp/SMS, so as reach it's weak — it pays off mainly if in-chat interaction is the actual product).

Verdict: with opt-in accepted, there is no true technical hard-blocker — it's solvable work-items + 3 must-not-skip gates + governance sign-offs. Governance could administratively stop it; nothing technical does.

---

7. Proposed approach (for discussion)

1. Phase 0 — 1-hour spike (no production writes): @Botfather → bot token → one person /starts → getUpdates reads chat.id → sendMessage confirms delivery. Proves the whole loop.
2. Phase 1 — Outbound-only, EMPLOYEE-first: add TELEGRAM to the MDMS enum (EMPLOYEE rows only, keep 1:1), build the per-tenant chat_id store, a /start+request_contact binding flow for staff, a TelegramSendClient branch in DispatchPipelineService (reusing existing idempotency/DLQ), and close the silent-SMS footgun. This is a contained Baileys-mirror build.
3. Phase 2 — Citizen outbound: add the citizen binding funnel (request_contact → eg_user match), citizen routing rows, consent capture at bind time.
4. Phase 3 (separate project) — Bidirectional: only if in-chat file/track is the goal. Singleton inbound consumer per tenant, citizen authorization model, command surface, abuse defense. Treat as its own RFC.

---

8. Open questions for the team

1. Scope: outbound-only, or is bidirectional file/track the actual product goal? (3× effort difference.)
2. Binding: is request_contact → mobile match acceptable, or do we mandate the OTP round-trip?
3. Delivery substrate: accept "direct bot service, no Novu tracking" now, or hold Telegram until a Novu upgrade gives us the native provider + delivery logs?
4. Governance: who signs off on PII egress to Telegram under DPA 2019, and what's the minimum-PII message policy?
5. Coverage: is Telegram worth it for the engaged minority, given WhatsApp/SMS dominate reach?

Decide first: (a) the scope fork (outbound vs bidirectional), and (b) the chat_id ↔ eg_user binding ceremony. Everything else follows from those two.