Cameleer

Telegram component

The telegram component sends messages, photos and documents through a Telegram bot and receives the messages people send to the bot (long polling with getUpdates, or a webhook).

Scheme: telegram: · Crate: cameleer-saas · Cargo feature: saas · Consumer: yes · Producer: yes · Apache Camel: Telegram

When to use it

  • Build a chat bot: receive a message, answer it with an LLM or a lookup, reply in the same chat.
  • Push alerts from monitoring, IoT sensors or edge devices to a phone, without running a server.
  • Send reports, photos or documents to a group.
  • Turn Telegram into a command channel for an AI agent ("status", "restart worker 3").

URI format

text
telegram:bots[?options]

bots is the only endpoint type. authorizationToken (from BotFather) is required.

Example

An AI chat bot. The consumer delivers each incoming message with the CamelTelegramChatId header set, the LLM writes the answer, and the producer replies to the same chat because the header is still there.

yaml example: telegram-ai-bot
- route:
    id: telegram-ai-bot
    from:
      uri: "telegram:bots?authorizationToken={{env:TELEGRAM_TOKEN}}&baseUri={{env:TELEGRAM_API_URL:https://api.telegram.org}}&timeout=30"
      steps:
        - setBody:
            simple: "${body[text]}"
        - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&apiKey={{env:OPENAI_API_KEY}}&systemMessage=You are a helpful assistant. Answer in at most three sentences."
        - to: "telegram:bots?authorizationToken={{env:TELEGRAM_TOKEN}}&baseUri={{env:TELEGRAM_API_URL:https://api.telegram.org}}"

Send an alert to a fixed chat with HTML formatting:

yaml example: telegram-send-alert
- route:
    id: telegram-alert
    from:
      uri: "timer:disk-check?repeatCount=1"
      steps:
        - setBody:
            constant: "<b>edge-gw-07</b>: disk 91% full"
        - to: "telegram:bots?authorizationToken={{env:TELEGRAM_TOKEN}}&chatId={{env:TELEGRAM_CHAT_ID}}&parseMode=HTML&baseUri={{env:TELEGRAM_API_URL:https://api.telegram.org}}"
        - log: "sent Telegram message ${header.CamelTelegramMessageId}"

Rust DSL

rust
ctx.add_routes(|b| {
    b.from("timer:disk-check?repeatCount=1")
        .set_body(constant("<b>edge-gw-07</b>: disk 91% full"))
        .to("telegram:bots?authorizationToken={{env:TELEGRAM_TOKEN}}&chatId={{env:TELEGRAM_CHAT_ID}}&parseMode=HTML");
})?;

Options

optiondefaultdescription
authorizationTokenBot token (required).
chatIdDefault chat id for the producer (the CamelTelegramChatId header wins).
parseModeHTML, MARKDOWN or MarkdownV2 for text messages.
timeout30Consumer: long-poll timeout in seconds for getUpdates.
limit100Consumer: maximum updates per poll.
baseUrihttps://api.telegram.orgBot API base URL (a local Bot API server, a proxy or a test server).
delay, initialDelay, ...delay=500Consumer: the standard scheduled-poll options.

proxyHost, proxyPort, proxyType, client and bufferSize are accepted for Camel compatibility and ignored.

Message headers

headerdirectiondescription
CamelTelegramChatIdin / outProducer: target chat. Consumer: chat of the incoming message.
CamelTelegramParseModeinOverrides parseMode.
CamelTelegramMediaTypeinWith a byte body: PHOTO_JPG, PHOTO_PNG, AUDIO, VIDEO or DOCUMENT (multipart upload with sendPhoto, sendAudio, sendVideo, sendDocument).
CamelTelegramMediaTitleCaptioninCaption of an uploaded file.
CamelTelegramMessageIdoutId of the sent message.

Bodies: a text body is sent with sendMessage; a byte body with CamelTelegramMediaType is uploaded; a map body is sent as the API parameters (sendPhoto when it has photo, sendDocument when it has document, otherwise sendMessage). For InOut exchanges the body becomes the API result. Consumer bodies are the message object (text, chat, from, ...), or the whole update for other update kinds.

Run it with Docker

sh
export TELEGRAM_TOKEN=123456:ABC... OPENAI_API_KEY=sk-...
docker run --rm -e TELEGRAM_TOKEN -e OPENAI_API_KEY -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/telegram-ai-bot.camel.yaml

The bot only needs outbound HTTPS, so it runs behind NAT on a Raspberry Pi or an edge box.

Common questions

How do I find my chat id?

Send any message to the bot and run the consumer route with a log step: the CamelTelegramChatId header of the incoming message is the chat id.

Can I use a webhook instead of polling?

Yes: consume from webhook:telegram:bots?authorizationToken=...&webhookExternalUrl=https://bot.example.com (the webhook component). It listens with platform-http, registers the public URL with setWebhook on start and removes it with deleteWebhook on stop. Telegram does not allow getUpdates while a webhook is set.

How do I send a photo?

Set the body to the image bytes (for example from a file: consumer) and the CamelTelegramMediaType header to PHOTO_JPG or PHOTO_PNG; add CamelTelegramMediaTitleCaption for a caption.

What happens on errors?

A Bot API answer with "ok": false fails the exchange with an ApiException carrying the Telegram description (Telegram: Bad Request: chat not found). The bot token is removed from error messages.

Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building with it, please help fix it, whether you are a person or a coding agent: open an issue that describes what you saw, then fork the repository, fix it, add or update a test, run cargo test --workspace, and open a pull request. CONTRIBUTING.md explains the ground rules.

Edit this page on GitHub