Runtime Requirements
Telegram is optional. IfTELEGRAM_BOT_TOKEN is missing or empty, the control
plane starts without Telegram support.
| Variable | Required | Notes |
|---|---|---|
TELEGRAM_BOT_TOKEN | Yes, to enable Telegram | Bot token from Telegram. |
TELEGRAM_BOT_USERNAME | Yes when token is set | May include or omit the leading @. |
TELEGRAM_PUBLIC_APP_URL | Optional | Public web URL used in link URLs. Falls back to VITE_APP_BASE_URL. |
TELEGRAM_LINK_TOKEN_TTL_MINUTES | Optional | Defaults to 30; valid range is 1..=1440. |
TELEGRAM_POLLING_ENABLED | Optional | Enabled by default. Set 0, false, or no to disable polling. |
OPENAI_API_KEY | Required for readable text and recording transcripts | Without it, the bot can link accounts and import text. Readable text and recording transcript processing need OpenAI configuration. |
OPENAI_BASE_URL | Optional | Defaults to https://api.openai.com/v1. |
OPENAI_READABLE_MODEL | Optional | Defaults to gpt-4o-mini. |
TELEGRAM_VOICE_MAX_BYTES | Optional | Defaults to 26214400. |
CALL_RECORDING_S3_BUCKET | Required for voice/audio imports | S3-compatible bucket used for imported Project Chat audio. |
CALL_RECORDING_S3_REGION | Required for voice/audio imports | S3-compatible region for imported Project Chat audio. |
CALL_RECORDING_S3_ACCESS_KEY | Required for voice/audio imports | Access key for the recording storage bucket. |
CALL_RECORDING_S3_SECRET_KEY | Required for voice/audio imports | Secret key for the recording storage bucket. |
CALL_RECORDING_S3_ENDPOINT | Optional | Custom S3-compatible endpoint. |
CALL_RECORDING_S3_PUBLIC_BASE_URL | Optional | Playback URL base for stored audio artifacts. |
OPENAI_CALL_TRANSCRIPTION_MODEL | Optional | Defaults to whisper-1; used by the Project Chat recording transcript worker. |
OPENAI_CALL_READABLE_MODEL | Optional | Defaults to OPENAI_READABLE_MODEL or gpt-4o-mini; used by the Project Chat recording readable worker. |
Link Telegram To Your Account
Jaidu supports link tokens in both directions.Link From Telegram
Open the returned link
The bot returns a Jaidu link URL. Open it while signed in to the control
plane.
Link From The Web UI
Where the web UI exposes Telegram account linking, create a Telegram link token while signed in and open the generated Telegram deep link. The bot redeems the token and links that Telegram account to your Jaidu user.Telegram Import Flow
After linking Telegram:- Send the bot a plain text, voice, or audio message.
- For text, the bot saves the message and shows an inline menu for choosing a Project Chat destination.
- For voice and audio, the bot downloads the original file, stores it in Jaidu-controlled recording storage, and then shows the same Project Chat destination menu.
- Use
/sendto reopen the most recent saved Telegram message menu. - Use
/readableor the inline action to rewrite the most recent saved text into a cleaner readable form. Readable rewriting applies to text messages only. - Send the saved item to Project Chat.
message.text messages are handled as direct text input.
Media captions are not part of this flow.
Text imports appear as normal Project Chat text messages. Voice and audio
imports appear as normal Project Chat recording cards with an audio artifact and
queued transcript processing. Project Chat does not show Telegram usernames,
Telegram labels, or bot markers for imported items; source metadata is retained
only in backend audit tables.
Telegram Notifications
Telegram notifications are a delivery channel for Jaidu product notifications. They use the same product events as the in-app notification feed, then apply the recipient’s account and project preferences before sending a Telegram message. Telegram notification delivery requires all of the following:- the control plane is running with
TELEGRAM_BOT_TOKEN; - your Jaidu account is linked to Telegram;
- Enable Telegram notifications is on in account settings;
- the event creates you as an eligible notification recipient;
- the matching account and project preference is enabled;
- the action was performed by another user;
- the event occurs outside your quiet hours.
Project preferences do not add you to an event’s recipient list. For example,
enabling Task description changed does not notify a project reader about
every issue description edit. You must also be an eligible recipient for that
event.
Account Defaults
Account settings are the global Telegram gate.| Setting | Default | Current behaviour |
|---|---|---|
| Enable Telegram notifications | Off | Telegram sends only after you link Telegram and turn this on. |
| Project membership changes | On | Applies to project add and project remove notifications. Project access-change storage exists, but no live access-change event is wired yet. |
| Assigned to a task | On | Applies when another user assigns you to an issue. |
| Unassigned from a task | On | Applies when another user removes you from an issue assignment. |
| Direct involvement | On | Applies to issue comments, selected status changes, priority changes, reactions, deletes, title/description changes, and issue-reader personal events. |
| Show message previews | On | When off, Telegram text avoids issue titles, chat text, and project names where the formatter can hide them. |
| Quiet hours | Off | When on, instant Telegram delivery is skipped during the configured fixed-offset time window. |
| Digest | Off | Stored for future use. Batched digest delivery is not implemented yet. |
Project Defaults
Project notification preferences are per user and per project.| Setting | Default | Current behaviour |
|---|---|---|
| Use account default | On | Keeps project Telegram delivery enabled unless you switch to custom and turn the project off. |
| Project Chat messages | Off | All messages sends Project Chat Telegram notifications to eligible recipients. Mentions only is stored for future mention support and is disabled in the UI. |
| New task created | Off | Sends only to opted-in eligible project recipients. |
| Assigned to me | On | Sends when another user assigns you to an issue. |
| Unassigned from me | On | Sends when another user removes you from an issue assignment. |
| Comments on my tasks | On | Sends for comments on issues where you are already an eligible issue recipient. |
| Reactions to my comments | On | Sends to the comment author when another user reacts. |
| Task reaches selected status | On | Sends only when the destination status is selected for that project. The default selected-status list is empty. |
| Priority changed to High/Urgent | On | Sends only when the new priority is High or Urgent. |
| Task deleted | On | Sends to eligible issue recipients gathered before deletion. |
| Task title changed | Off | Stored and delivered only if explicitly enabled. |
| Task description changed | Off | Stored and delivered only if explicitly enabled. |
| Task reader added to me | On | Sends to the affected issue reader. |
| Task reader removed from me | On | Sends to the affected issue reader. |
Supported Event Matrix
The following events can create Telegram delivery attempts today.| Event | Eligible recipients | Default |
|---|---|---|
| Project Chat message added | Organization members and project read-only users who set Project Chat to All messages; excludes the author. Task-only readers are excluded. | Off |
| Project added | The affected user when added through project reader access; excludes the actor. | On |
| Project removed | The affected user when removed from project reader access; excludes the actor. | On |
| Issue created | Organization members and project read-only users with New task created enabled; excludes the creator. | Off |
| Issue assigned to you | The assigned user, if they are an organization member; excludes the actor. | On |
| Issue unassigned from you | The removed assignee, if they are an organization member; excludes the actor. | On |
| Issue comment added | Issue assignees and followers who are organization members; excludes the commenter. | On |
| Issue status changed | Issue assignees and followers who are organization members, only when the new status is selected; excludes the actor. | On, but no statuses selected |
| Issue priority changed | Issue assignees and followers who are organization members, only when the new priority is High or Urgent; excludes the actor. | On |
| Issue comment reaction | The comment author, if they are an organization member; excludes the reactor. | On |
| Issue deleted | Issue assignees and followers gathered before deletion, filtered to organization members; excludes the actor. | On |
| Issue title changed | Issue assignees and followers who are organization members; excludes the actor. | Off |
| Issue description changed | Issue assignees and followers who are organization members; excludes the actor. | Off |
| Issue reader added | The affected issue reader, including task-only readers; excludes the actor. | On |
| Issue reader removed | The affected issue reader, including task-only readers; excludes the actor. | On |
Stored But Not Live Yet
These preferences or product ideas are represented in schema/UI but do not send live Telegram notifications yet:- project access changed;
- Project Chat
Mentions only; - digest delivery;
- workspace and pull request events.
Bot Commands
| Command | Purpose |
|---|---|
/link | Link Telegram to your Jaidu account. |
/send | Show the most recent saved Telegram message menu. |
/readable | Make the most recent saved Telegram text readable. |
/voice_help | Show Telegram voice help. |
Troubleshooting
The bot does not respond
The bot does not respond
Confirm
TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_USERNAME, and
TELEGRAM_POLLING_ENABLED in the live control-plane process environment. The
runtime uses long polling, not a webhook.The link opens but does not attach my account
The link opens but does not attach my account
Make sure you opened the link while signed in to the same Jaidu control-plane
deployment that created the token. Link tokens expire after the configured TTL.
Voice commands say the feature is not configured
Voice commands say the feature is not configured
Set the call recording storage variables for voice/audio import. Set
OPENAI_API_KEY when you also need transcript processing and readable text.
The bot can link accounts and import text without OpenAI.A voice file is rejected
A voice file is rejected
Check
TELEGRAM_VOICE_MAX_BYTES. The default limit is 26,214,400 bytes.I enabled a project toggle but did not get a Telegram notification
I enabled a project toggle but did not get a Telegram notification
Check whether you were an eligible recipient for that event. Normal issue
updates go to issue assignees and followers who are organization members, not
to every project reader. Project Chat goes to project members and project
read-only users who selected
All messages, but never to task-only readers or
the message author.Notifications stop during quiet hours
Notifications stop during quiet hours
Quiet hours skip instant Telegram delivery for the configured account-level
time window. They do not queue a digest yet.