Telegram Bot

The EmbedHub Telegram bot links a group chat to a project, so the team's working channel becomes a control surface for that project. Photos and PDFs shared in the group are auto-uploaded to the project; commands let you manage todos and check recent activity; and project events (uploads, role changes, todo state changes, etc.) are pushed back into the group as notifications.

Setup

1. Add the bot to your group as an administrator.

   The bot starts a setup wizard automatically the moment it joins.

2. Answer the wizard's three prompts:

   • Org slug — e.g. anuj
   • Project slug — e.g. firmware
   • API token — a key from your EmbedHub settings. The token must belong to the organization owner.

3. The bot validates the token against the EmbedHub API and confirms once the group is linked. From then on, photos shared in the group auto-upload to the project's photos/ folder, and PDFs to documents/.

To re-link the group later (different project, rotated key, etc.), an admin can run /configure to restart the wizard. /status shows the current configuration.

Commands

Command	Where	What it does
/start	Private chat	Show help (same content as /help).
/help	Anywhere	Show command reference.
/configure	Group, admins only	(Re)run the setup wizard.
/status	Group	Show the linked org/project.
/activity [n]	Group	Show the last n activity events for the linked project (default 5, max 25).
/todos	Group	List current todos with status icons.
/newtodo	Group	Multi-step wizard to create a new todo (title → notes → inline-keyboard assignee picker).
/canceltodo	Group	Abort an in-progress /newtodo wizard.

See the Todos page for details on /todos and /newtodo.

Automatic notifications

When something happens in the linked project — from anywhere (web UI, CLI, the bot itself, GitHub Actions, etc.) — the group receives a short notification. The first character is an emoji indicating the event type:

Emoji	Event type	Meaning
📤	file.upload	A file was uploaded to the project.
📥	file.download	A file was downloaded.
🗑️	file.delete	A file was deleted.
✨	project.create	A new project was created.
⚙️	project.update	The project was updated.
❌	project.delete	The project was deleted.
👤	member.role_assigned	Someone was assigned a project role.
🚫	member.role_removed	A project role was removed from someone.
🛡️	role.create / update / delete	A project role definition changed.
📱	device.access_granted / revoked	A HAL device's project access changed.
📊	statemachine.save	A state machine diagram was saved.
📝	todo.create	A new todo was created.
🔁	todo.update	A todo's status, assignee, title, or notes changed.
🗑️	todo.delete	A todo was deleted.

Activity events are always recorded for /activity even if a Telegram delivery doesn't reach the group.

Auto-uploads

Photos and documents shared in a configured group are auto-uploaded:

• Photos — the largest size variant is uploaded to the project's photos/ folder as photos/<ISO-datetime>_<file_unique_id>.jpg.
• PDFs — uploaded to documents/ with the original filename preserved.
• Other images sent as files — uploaded to photos/ with the original filename preserved.

Other file types (zips, archives, code, etc.) are silently ignored.

Each successful upload posts a confirmation in the chat (✅ Photo uploaded → photos/2026-04-26T11:42:01_AgADBAADxxx.jpg) and records a telegram.upload activity event.

Permissions

The bot uses the API key supplied during setup. That key must belong to the organization owner (this is enforced by the backend). All activity emitted by the bot — uploads, todo creation, etc. — is attributed to the API key owner with source: telegram.