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

# Telegram

> Читання історії повідомлень та надсилання відповідей через AI-агента – власний бот, write через draft→confirm.

<Note>
  **Status: live.** 13 MCP tools – 4 read-only + 9 для надсилання / редагування / видалення (через draft→confirm).
</Note>

## Як це працює

Telegram інтеграція – **власний бот** (BYO): Brama НЕ має спільного бота. Ти створюєш свого бота через [@BotFather](https://t.me/BotFather), копіюєш його токен і вставляєш у Brama. Токен зберігається зашифрованим, а Brama лише викликає Telegram Bot API від твого імені.

Після підключення Brama автоматично реєструє webhook у Telegram, і вхідні повідомлення твого бота потрапляють у твою ізольовану історію. Read-tools читають саме цю історію (а не Bot API напряму), тож "які повідомлення я отримав сьогодні" відповідається миттєво.

На відміну від інших інтеграцій, Telegram має **write-tools** – агент може надсилати повідомлення, файли, редагувати й видаляти. Деструктивні дії йдуть через **draft→confirm**: агент готує чернетку, ти переглядаєш (і за потреби редагуєш) у картці підтвердження, і нічого не надсилається, доки ти не натиснеш Send.

## Підключення

### 1. Створи бота

У Telegram відкрий [@BotFather](https://t.me/BotFather) → `/newbot` → дай ім'я → скопіюй **токен** (формат `123456789:ABCdef…`).

### 2. Connect

[`app.brama.work`](https://app.brama.work) → **Integrations → Telegram** → встав токен бота й натисни **Authorize**.

Brama перевірить токен у Telegram, збереже його зашифрованим і автоматично зареєструє webhook. Статус інтеграції стане **active**, і ти побачиш Webhook URL зі статусом доставки.

<Note>
  Бот бачить лише ті чати, у яких він уже отримав повідомлення. Щоб бот бачив пости каналу – додай його в канал; додав пізніше й не бачиш постів? Натисни **Перепідключити webhook** на сторінці інтеграції (токен вводити не треба).
</Note>

### 3. Запит

У своєму MCP клієнті (Claude Desktop, Gemini CLI – див. [Connect a client](/connect)):

> Які повідомлення я отримав у Telegram сьогодні?

Агент викличе `brama_telegram_list_messages` і поверне відправника, чат, текст і час кожного повідомлення.

## Read tools (live)

Усі 4 read-tools – **read-only**: читають історію повідомлень твого бота. Нічого не надсилають.

<Card title="brama_telegram_list_messages" icon="list">
  Повідомлення, які отримав бот, найновіші зверху – опційно за діапазон дат та/або для одного чату. Повертає відправника (username, ім'я), чат (id, тип, заголовок), текст і час надсилання (UTC).

  **Параметри:**

  * `from` / `to` *(optional)* – ISO 8601 UTC datetime
  * `chat_id` *(optional)* – обмежити одним чатом
  * `limit` *(optional)* – default 50, max 200

  Use: "які повідомлення я отримав сьогодні?", "останні повідомлення від «людини»".
</Card>

<Card title="brama_telegram_search_messages" icon="magnifying-glass">
  Повнотекстовий пошук по отриманих повідомленнях за підрядком (case-insensitive), найновіші зверху, опційно за діапазон дат.

  **Параметри:**

  * `query` *(required)* – підрядок для пошуку
  * `from` / `to` *(optional)* – ISO 8601 UTC datetime
  * `limit` *(optional)* – default 50, max 200

  Use: "знайди повідомлення про X", "хтось згадував «тему»?".
</Card>

<Card title="brama_telegram_get_conversation" icon="messages">
  Одна розмова (усі повідомлення з одним `chat_id`) у хронологічному порядку – від старіших до новіших, обмежено N найновішими.

  **Параметри:**

  * `chat_id` *(required)* – з list / search
  * `limit` *(optional)* – default 50, max 200 найновіших

  Use: "про що ми говорили з «чатом»?", "покажи розмову з X".
</Card>

<Card title="brama_telegram_get_message_raw" icon="file-magnifying-glass">
  Повний raw-об'єкт одного повідомлення – деталі, які list/conversation згортають: метадані медіа (incl. file\_id), forward chain, entities, reply context, локація, опції опитування тощо. Повертає метадані, НЕ байти медіафайлу.

  **Параметри:**

  * `chat_id` *(required)*
  * `message_id` *(required)*

  Use: глибокий розбір одного повідомлення.
</Card>

## Write tools (live)

Надсилання, редагування й видалення йдуть **AS the bot** і тільки в чати, з яких бот уже отримував повідомлення. Деструктивні дії мають парний `*_draft`, що показує **інтерактивну картку підтвердження** – нічого не відбувається, доки ти не натиснеш Send/Delete.

<Card title="brama_telegram_send_message" icon="paper-plane">
  Надіслати текстове повідомлення в чат – доставляється одразу. Для перегляду / редагування у картці перед надсиланням використовуй `brama_telegram_send_message_draft`.

  **Параметри:** `chat_id` *(required)*, `text` *(required)*, `reply_to_message_id` *(optional)*, `parse_mode` *(optional)*.
</Card>

<Card title="brama_telegram_send_message_draft" icon="pen-to-square">
  Підготувати повідомлення й показати інтерактивну картку підтвердження (отримувач + редагований текст + Send/Cancel) перед надсиланням.

  **Параметри:** ті самі, що в `brama_telegram_send_message`.
</Card>

<Card title="brama_telegram_send_rich_message" icon="align-left">
  Надіслати довге, багатоформатне повідомлення (rich-markdown: заголовки, списки, таблиці, цитати, код; до 32768 символів) – доставляється одразу. Підходить для звітів і метрик.

  **Параметри:** `chat_id` *(required)*, `markdown` *(required)*, `reply_to_message_id` *(optional)*.

  <Note>
    Rich-повідомлення рендеряться у нативних застосунках Telegram (iOS, Android, desktop), але НЕ у браузерному Telegram Web. Для отримувачів на Telegram Web обирай `brama_telegram_send_message`.
  </Note>
</Card>

<Card title="brama_telegram_send_rich_message_draft" icon="pen-to-square">
  Підготувати довге rich-markdown повідомлення й показати картку підтвердження з рендереним preview перед надсиланням.

  **Параметри:** ті самі, що в `brama_telegram_send_rich_message`.
</Card>

<Card title="brama_telegram_send_file" icon="paperclip">
  Надіслати файл (фото або документ) у чат – доставляється одразу. Файл задається АБО `file_url` (публічна URL, яку Telegram завантажує), АБО `file_base64` (байти + `file_name`). `as_photo=true` шле inline як фото; default – як документ.

  **Параметри:** `chat_id` *(required)*, `file_url` або `file_base64` (рівно один), `file_name` *(required з base64)*, `mime_type` *(optional)*, `as_photo` *(optional)*, `caption` *(optional)*, `reply_to_message_id` *(optional)*.
</Card>

<Card title="brama_telegram_send_file_draft" icon="pen-to-square">
  Підготувати файл і показати картку підтвердження (отримувач + chip вкладення + редагований caption) перед надсиланням.

  **Параметри:** ті самі, що в `brama_telegram_send_file`.
</Card>

<Card title="brama_telegram_edit_message" icon="pen">
  Відредагувати текст повідомлення, яке бот сам надіслав, замінивши його новим – застосовується одразу. Telegram дозволяє редагувати лише власні недавні повідомлення бота. Edit реверсивний, тож без окремої картки – йде через стандартний tool-approval gate клієнта.

  **Параметри:** `chat_id` *(required)*, `message_id` *(required)*, `text` *(required)*, `parse_mode` *(optional)*.
</Card>

<Card title="brama_telegram_delete_message_draft" icon="trash">
  Підготувати ВИДАЛЕННЯ повідомлення бота й показати картку підтвердження (отримувач + preview + Delete/Cancel). Видалення незворотне, тому прямого delete-tool немає – тільки через картку.

  **Параметри:** `chat_id` *(required)*, `message_id` *(required)*, `label` *(optional)*.
</Card>

<Card title="brama_telegram_confirm_send" icon="circle-check">
  Виконати дію, яку підготувала чернетка – надіслати повідомлення/файл (з можливо відредагованим текстом) або видалити повідомлення. Single-use токен. На хостах, що рендерять картку, цей tool викликається лише кнопкою картки (Send/Delete).

  **Параметри:** `confirm_token` *(required)*, `text` *(optional)*.
</Card>

## Приклади запитів агенту

* "Які повідомлення я отримав у Telegram сьогодні?"
* "Знайди повідомлення про оплату за останній тиждень."
* "Про що ми говорили з «чатом»?"
* "Підготуй відповідь «людині»: …" (агент покаже картку перед надсиланням)
* "Надішли цей звіт у чат як rich-повідомлення."

## Безпека

* **Власний бот (BYO)** – Brama не має спільного бота; ти використовуєш лише свого. Токен зберігається envelope-encrypted, ключі поза базою; на диск не пишеться, у пам'яті лише на час запиту; у логи не потрапляє.
* **Read-tools** – read-only: лише читають історію повідомлень твого бота.
* **Write-tools** – надсилають / редагують / видаляють лише AS the bot і тільки в чати, з яких бот уже отримував повідомлення. Незворотні дії (видалення) та чутливі надсилання йдуть через draft→confirm – ти підтверджуєш у картці.
* Кожен tenant ізольований – твоя історія повідомлень недосяжна іншим tenant'ам.

## Питання

Питання? Напиши `viktor@brama.work`.