> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Bot API

> Client-mode REST API connector for a curated Telegram Bot API slice: sendMessage, sendPhoto, getUpdates, setWebhook, and getMe

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Telegram Bot API](https://core.telegram.org/bots/api):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST sendMessage | `POST /bot{token}/sendMessage` | Text alerts to a chat |
| POST sendPhoto | `POST /bot{token}/sendPhoto` | Photo via `file_id` or HTTPS URL |
| GET getUpdates | `GET /bot{token}/getUpdates` | Long poll; mutually exclusive with webhook |
| POST setWebhook | `POST /bot{token}/setWebhook` | Register HTTPS webhook URL (client-mode) |
| GET getMe (smoke) | `GET /bot{token}/getMe` | Credential check |

Default `BASE_ADDRESS` is `https://api.telegram.org`. Topics use `messaging/telegram/<object>/<verb>`.

> [!NOTE]
>
> Telegram authenticates by embedding the bot token in the URL path (`/bot{token}/METHOD_NAME`). This template does **not** send an Authorization header. Prefer Hub secrets for the token. `getUpdates` and `setWebhook` cannot both be active. Inbound webhook → MQTT is out of scope for this client-mode package. Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Telegram Bot API
# Auth: path /bot{value.json.token}/METHOD (no Authorization header)
# BASE_ADDRESS: https://api.telegram.org

DEFINE ROUTE TelegramBotApiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.telegram.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getme
        WITH SOURCE_TOPIC "messaging/telegram/bot/get-me"
        WITH DESTINATION_TOPIC "messaging/telegram/bot/get-me/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/bot{value.json.token}/getMe"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Sendmessage
        WITH SOURCE_TOPIC "messaging/telegram/message/send"
        WITH DESTINATION_TOPIC "messaging/telegram/message/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/bot{value.json.token}/sendMessage"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Sendphoto
        WITH SOURCE_TOPIC "messaging/telegram/photo/send"
        WITH DESTINATION_TOPIC "messaging/telegram/photo/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/bot{value.json.token}/sendPhoto"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Getupdates
        WITH SOURCE_TOPIC "messaging/telegram/update/get"
        WITH DESTINATION_TOPIC "messaging/telegram/update/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/bot{value.json.token}/getUpdates?offset={value.json.offset}&limit={value.json.limit}&timeout={value.json.timeout}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Setwebhook
        WITH SOURCE_TOPIC "messaging/telegram/webhook/set"
        WITH DESTINATION_TOPIC "messaging/telegram/webhook/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/bot{value.json.token}/setWebhook"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getme | GET | `/bot{token}/getMe` | `messaging/telegram/bot/get-me` | `messaging/telegram/bot/get-me/response` |
| Sendmessage | POST | `/bot{token}/sendMessage` | `messaging/telegram/message/send` | `messaging/telegram/message/send/response` |
| Sendphoto | POST | `/bot{token}/sendPhoto` | `messaging/telegram/photo/send` | `messaging/telegram/photo/send/response` |
| Getupdates | GET | `/bot{token}/getUpdates` | `messaging/telegram/update/get` | `messaging/telegram/update/get/response` |
| Setwebhook | POST | `/bot{token}/setWebhook` | `messaging/telegram/webhook/set` | `messaging/telegram/webhook/set/response` |

## Auth

1. Create a bot with [@BotFather](https://t.me/BotFather) and copy the bot token.
2. Set connector `BASE_ADDRESS` to `https://api.telegram.org`.
3. Pass `token` on the MQTT request payload so path placeholders resolve: `/bot{value.json.token}/…`.
4. Store the token in Hub secrets / `GET SECRET "TELEGRAM_BOT_TOKEN"`. Never commit real credentials.
5. Successful `getMe` / `sendMessage` returns **HTTP 200** with JSON `"ok": true`.

## Example payloads

**getMe:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_BOTFATHER_TOKEN"
}
```

**sendMessage:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_BOTFATHER_TOKEN",
  "chat_id": 123456789,
  "text": "Hello from Coreflux"
}
```

**sendPhoto:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_BOTFATHER_TOKEN",
  "chat_id": 123456789,
  "photo": "https://example.com/image.png",
  "caption": "Snapshot"
}
```

**setWebhook:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_BOTFATHER_TOKEN",
  "url": "https://your.public.host/telegram/webhook"
}
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Official Bot API](https://core.telegram.org/bots/api)
* [Bot tutorial](https://core.telegram.org/bots/tutorial)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.