Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agents.craft.do/docs/llms.txt

Use this file to discover all available pages before exploring further.

Telegram integration uses the standard Bot API via a bot token you create with @BotFather. There’s no account linking — you talk to your bot, and the bot drives a Craft Agent session.

​
Create a Bot

1

Open @BotFather in Telegram

Search for @BotFather and start a chat.
2

Create a new bot

Send /newbot and follow the prompts. Give it a display name and a username (must end in bot, e.g. my_craft_agent_bot).
3

Copy the token

BotFather replies with a line like:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-0123456789
This is your bot token. Treat it like a password — anyone with it can impersonate your bot.
4

(Optional) Disable privacy mode for group support

If you want your bot to work in groups, send /setprivacy → choose your bot → Disable. For 1-on-1 use (the supported and recommended mode), you can skip this.
Private chats only. The gateway rejects group and channel messages at the adapter boundary. Even if your bot is added to a group, only DMs with the bot can drive a session.

​
Connect in the App

1

Open Settings → Messaging

In Craft Agent, open Settings → Messaging. You’ll see a tile for each supported platform.
2

Click Connect on the Telegram tile

A dialog opens asking for the bot token.
3

Paste the token and click Test

Craft Agent calls Telegram’s getMe endpoint. On success you’ll see the bot’s name and username; on failure you’ll see Telegram’s error message verbatim.
4

Click Save

The token is persisted to your workspace keychain and the Telegram adapter starts listening.

​
First Conversation

1

Open your bot in Telegram

Tap the t.me/<your_bot_username> link BotFather sent you, or search for your bot’s username.
2

Send /new

This creates a new session in your active workspace and binds the chat to it. You’ll get a reply like:
Created "abc123" — you're connected. Just type to start.
3

Type anything

Your message is forwarded to the agent. Replies come back as messages in the chat according to your response mode (default: progress).

​
Attachments

Send a photo, document, voice message, video, or audio file and the gateway downloads the blob, wraps it as a FileAttachment, and forwards it to the session alongside your caption.
TypeForwarded as
PhotoImage attachment (original resolution)
DocumentFile attachment with original MIME type
VoiceAudio attachment (ogg/opus)
VideoVideo attachment
AudioAudio attachment
Hard cap: 20 MB per attachment. Oversize files or failed downloads trigger a user-visible reply in the chat instead of being silently dropped.

​
Inline Buttons

Telegram supports inline keyboard buttons, so flows like /bind render a tappable list of recent sessions instead of a numbered text list: 
Recent sessions:
[ Morning standup ]
[ Release v0.8.10 ]
[ Debug session  ]
Tap a button → bound. The gateway clears the keyboard on the posted message so stale buttons don’t pile up.

​
Webhook vs Long-Poll

  • In-app (desktop Electron): the adapter uses long-poll (grammY’s built-in updater). No public URL needed.
  • Headless server: the adapter uses webhook mode. You configure a public URL (e.g., https://your-server.tld/telegram/webhook), register it with setWebhook, and Telegram posts updates to it. The server verifies the X-Telegram-Bot-Api-Secret-Token header.
See Server → Headless for the webhook deployment path.

​
Troubleshooting

This is expected on the first message to a fresh bot. Send /new to create and bind a session, or /pair <code> to redeem a pairing code from the app.
The bot token is wrong or was revoked in BotFather. Run /token in @BotFather to get a fresh one, or /revoke then /newbot if you want a clean slate.
Check that the workspace the bot is configured in is the active workspace in the app. Each workspace has its own messaging config — a bot registered under workspace A won’t drive sessions in workspace B.
By design — only private DMs with the bot can drive a session. Group and channel messages are rejected at the adapter boundary.
Telegram’s Bot API caps file downloads at 20 MB. Upload the file via the app’s attachment picker instead, or split it.