Telegram for executives
Connect a Telegram bot so executives can query the assistant, pull reports, approve transactions and upload documents from a phone.
What this enables
Each executive opens Telegram, asks the assistant questions, pulls reports, approves transactions and uploads documents — from a phone, with no web app needed.
There are two parts. Part A is a one-time technical setup done by whoever has server access. Part B is done by the CEO in the web app.
Part A — one-time technical setup (administrator)
Watch
Administrator only
This part needs access to environment variables and the deployed URL. If you are a CEO or CFO, skip to Part B — your administrator completes Part A.
- A1
Create the Telegram bot
Open Telegram, start a chat with @BotFather and send /newbot. Give the bot a display name and a username ending in bot. BotFather replies with a bot token — treat it like a password.
- A2
Add the environment variables
Set TELEGRAM_BOT_TOKEN to the token, and TELEGRAM_WEBHOOK_SECRET to a long random string. The secret is optional in code but strongly recommended: it signs every webhook request, and without it the webhook refuses all requests.
- A3
Deploy the app
The webhook route lives at /api/telegram/webhook. Deploy to production and note the public URL; for local testing expose a tunnel to your machine.
- A4
Register the webhook
Open https://your-domain/api/telegram/webhook?secret=YOUR_WEBHOOK_SECRET&url=https://your-domain/api/telegram/webhook. The expected response is {"ok": true, "url": "…"}.
- A5
Verify it is live
Open the same route with only the secret parameter. The response should show your webhook url and pending_update_count 0. If last_error_message appears, the URL is not reachable — fix that first.
Note
Once is enough
You will not need to repeat Part A unless the bot token or the webhook URL changes.
Part B — the CEO maps the chats
- B1
Ask each executive for their chat ID
Send them these steps: open Telegram, search for your bot, press Start or send /start, and the bot replies with a numeric chat ID to send back to you. If no reply arrives, the fallback is @userinfobot, which replies with the numeric ID.
- B2
Open Telegram Setup
Sign in as CEO and open Settings → Telegram Setup. The page is restricted to the CEO and platform SuperAdmins; other roles are redirected away.
Administration → Telegram/dashboard/admin/settings/telegram - B3
Map each chat ID
For each executive, select their name in Member, paste the chat ID in Telegram chat ID and click Map chat. The page confirms 'Chat ID mapped. The member can now use the bot.', and the mapping appears under Active mappings with status Linked.
- B4
Verify access
Ask each executive to send a message and confirm the bot responds — for example a cash-position question, /org, a PDF upload, or an approval request.
- B5
Remove a mapping when needed
In Active mappings, click the trash icon next to a member. The bot immediately stops accepting messages from that chat.
Rule
Chat IDs are the allowlist
A chat ID can be mapped to only one member, cannot be mapped to someone outside your workspace, and unmapped chats are ignored by the bot and reach no data. Approvals from Telegram run the exact same transaction as web approvals — one journal entry, one audit entry.
Verifying each executive's access
| Test | Expected reply |
|---|---|
| Send 'what is our cash position?' | A cash summary covering bank, petty cash, receivables and payables |
| Send /org | Organization ID and your role |
| Send a PDF or image | Confirmation that the document was ingested |
| Ask to approve a pending transaction | The match and a YES/NO prompt; approvals require a second confirmation message |
Executive command reference
| Command | What it does |
|---|---|
| /start | Shows help; before mapping, replies with your chat ID |
| /help | Shows help |
| /approve | Lists transactions awaiting your approval |
| /cancel | Cancels the current YES/NO confirmation |
| /org | Shows your organisation and role |
| Plain text | Ask anything — cash, inventory, sales, trips |
| Any file | PDF, image or Excel — sent to the AI pipeline |
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Bot does not reply to /start during setup | Webhook not registered or URL unreachable — redo steps A4 and A5 |
| Webhook shows last_error_message | The URL must be HTTPS and publicly reachable — check the deployment or tunnel |
| TELEGRAM_BOT_TOKEN is not configured | The environment variable is missing in the environment the app runs in |
| This chat ID is already mapped to a member | The ID is bound to someone else — ask for the exact number the bot replied with |
| Executive gets no reply after mapping | Confirm the mapping exists, the member is active, and the chat is private rather than a group |
| Duplicate messages when asking a question | Expected safety net — the system deduplicates on Telegram's message ID |