Connect Telegram

Outcome

You will install a project-specific Telegram bot, verify its webhook, pair Threadory users, and allow only intended chats.

Telegram notification delivery, including the weekly digest, is the workflow that runs in production today. The connector also exposes messaging and chat administration in the product, but Telegram is not a general knowledge-ingestion source. Do not promise Q&A or write-back workflows beyond the capabilities listed for Telegram in the integration matrix.

Before you begin

• You need Admin or Owner in the Threadory project.
• You need permission to create a bot with Telegram @BotFather.
• Threadory's webhook endpoint must be reachable by Telegram.
• Decide which private chats or groups are allowed before adding the bot.

Telegram bot tokens are unscoped credentials. Treat the token as a secret and never place it in a ticket, screenshot, Git, or chat message.

Connection profile

Item	Minimum or expected behavior
Credential	A dedicated Telegram bot token issued by @BotFather. The token is unscoped and controls the whole bot.
Minimum access	Telegram has no OAuth scopes for bot tokens. Limit access with bot privacy/group permissions, allowed chat types, and the per-project Allowed chat list.
Identity	Messages are sent as the configured bot, not as each Threadory user. Pairing links a Telegram account to a Threadory user for attribution.
Direction and entities	Incoming messages/callbacks can drive configured interactions; outbound actions send or edit bot messages. The connector creates no Knowledge entities.
Delivery mode	Webhook only. Telegram events are verified with the per-installation secret-token header; there is no polling fallback.

Create and probe the bot

1. Open @BotFather in Telegram.
2. Send /newbot and follow the prompts for a name and username.
3. Copy the API token into an approved temporary secret buffer.
4. In Threadory, select the project and open Connectors → Telegram.
5. Paste the token into Telegram bot token.
6. Select Probe connection.
7. Verify the bot name, username, and group/privacy capability badges.

Stop if the identity shown by Threadory is not the bot you intended to connect.

Install the connector

1. Keep Auto-generate webhook secret enabled. This creates the verification token server-side.
2. Keep Register now enabled when the Threadory API is reachable from the internet.
3. Select the install button and wait for the connector drawer to close.
4. Open Settings → Telegram.
5. Under Bot identity, confirm the username and group capabilities.
6. Under Webhook health, check the webhook path and Last delivery after the first test event.

Use a manually supplied webhook secret or delayed registration only with the platform operator; both change the deployment prerequisites.

Pair a user

1. In Settings → Telegram, select Generate code.
2. Share the code or generated bot link privately with the intended signed-in Threadory user.
3. In a direct message to the bot, the user sends /start <code>.
4. Return to Linked Telegram accounts and verify the Telegram identity and Threadory email.

The code expires after 24 hours. Use Unlink when the mapping is wrong or the user is offboarded.

Allow a chat

1. Add the bot to the intended private chat or group.
2. Send a harmless test message so the chat appears under Known chats.
3. Confirm the chat title and type.
4. Turn Allowed on only for the intended chat.
5. Leave unknown chats disabled.

Forget deletes the stored conversation history for that chat and makes the bot treat it as new. It is destructive; export required records first.

Verify the result

• Bot identity shows the expected @username.
• Webhook health shows a recent Last delivery.
• The expected user is present under Linked Telegram accounts.
• Only approved chats have Allowed enabled.
• A configured low-risk notification or digest reaches the intended chat once.

Common problems

Symptom	Likely cause	What to do
Probe returns 401	The bot token is invalid or was revoked	Generate or copy the current token from @BotFather and probe again
Telegram settings say to install the connector	The project installation did not complete	Return to Connectors → Telegram and repeat the probe/install
No webhook delivery appears	The public webhook is unreachable or registration failed	Ask the platform operator to verify routing before rotating secrets
Pairing code fails	It expired, was mistyped, or the wrong Threadory user used it	Generate a new code and share it privately with the intended user
Group messages are missing	Bot privacy mode or group permissions prevent delivery	Review the capability badges and @BotFather settings before broadening access
Bot ignores a known chat	Allowed is off	Verify the chat identity, then enable it deliberately
A bot token may have leaked	The token was copied into an unsafe place	Revoke it in @BotFather, update the connector, and inspect audit/activity evidence

Safe disconnection

Disconnecting stops new bot messages, callbacks, and paired-user interactions. It does not recall messages already delivered to Telegram or automatically delete project audit records. Forget removes stored chat history and has no product rollback; export required records before using it.

1. Disable notifications and workflows that target the bot.
2. Review pending approvals and required Telegram records.
3. Export required project data.
4. Unlink users and disable or forget chats according to the retention policy.
5. Disconnect the connector in Threadory.
6. Revoke the bot token with @BotFather when the bot will not be reused.

Verify that Telegram settings show no installed connector, the webhook is removed or no longer receives deliveries, and a low-risk test notification is not sent. To recover, install a new token, pair users again, and explicitly allow only the reviewed chats.

Next step

Configure audit and Telegram retention, and keep the integration matrix as the source of each connector's status and what it can do.