Telegram — Oshun System Docs

Primary operator interface for Matthew and Dr. Rockhead

What It Does

Telegram is the control channel for operators — not patients. Matthew and Dr. Rockhead receive all system alerts, briefings, and action prompts here. Patients never interact with Telegram; their channel is WhatsApp/IG/widget.

Content approval — generated social posts and campaign drafts are sent via inline buttons; operators approve or reject with one tap
System alerts — watchdog health alerts, billing events, failed webhook notifications, and escalations surface here
Procedure completion — operators mark procedures complete from Telegram, triggering the post-care sequence automatically
Daily briefings — morning summaries of overnight conversations, upcoming appointments, and pending actions delivered to the staff chat
Billing control — subscription status, upgrade/downgrade actions, and payment alerts managed via /billing slash command
Settings and configuration — feature toggles, persona updates, and integration health checks via slash commands
Inline button callbacks handle complex flows (onboarding steps, voice setup, storyboard approvals, ad campaign progression) without requiring any form input

External Service Details

Bot — registered via BotFather. Token stored in TELEGRAM_BOT_TOKEN. One bot per tenant in production.
Staff chat — the Telegram group or private chat where alerts and briefings are sent. ID stored in TELEGRAM_CHAT_ID.

Required environment variables:

TELEGRAM_BOT_TOKEN — bot authentication token from BotFather
TELEGRAM_CHAT_ID — staff group or private chat ID for proactive alerts and briefings

Journeys

Telegram is the operator notification and control surface for these journeys:

Key Source Files

src/telegram.js — Bot wiring, slash command registration (/voice, /billing, etc.). Key exports: startTelegramBot(), sendNotification(). Note: sendNotification is lazy-required in other modules to avoid circular dependencies.
src/telegram_message.js — Handles all inbound text and media messages from operators. Entry: handleTelegramMessage() at line 26. Dispatches to AI or direct action handlers.
src/telegram_callbacks.js — Inline button callback handler for core flows: onboarding, voice setup, storyboard, ad education. Entry: handleCallbackQuery().
src/telegram_callbacks_content.js — Inline button callbacks for content/campaign/Blotato/pipeline flows. Entry: handleContentCallback().
src/telegram_media.js — Processes document, voice note, photo, and video uploads sent by operators. Key exports: handleDocument(), handleVoice(), sendResponse().
src/telegram_actions/ — Action dispatcher directory. Seven domain handler files: voice_calendar.js, social_content.js, system_admin.js, media.js, care_analytics.js, crm_team.js, settings_links.js. Unified entry via index.js → executeAction().

Known Issues

Dr. Rockhead has not installed Telegram — briefings are pending. The daily briefing sequence and procedure-completion prompts are configured to send to the staff chat, but Dr. Rockhead has not yet joined. Until onboarded, all operator notifications go to Matthew only. Follow up with Dr. Rockhead to complete Telegram setup before going live with post-care automation.