Skip to main content
Status: live. 14 MCP tools – 5 read-only + 9 для надсилання / редагування / видалення (через draft→confirm).

Як це працює

Telegram інтеграція – власний бот (BYO): Brama НЕ має спільного бота. Ти створюєш свого бота через @BotFather, копіюєш його токен і вставляєш у Brama. Токен зберігається зашифрованим, а Brama лише викликає Telegram Bot API від твого імені. Після підключення Brama автоматично реєструє webhook у Telegram, і вхідні повідомлення твого бота потрапляють у твою ізольовану історію. Read-tools читають саме цю історію (а не Bot API напряму), тож “які повідомлення я отримав сьогодні” відповідається миттєво. На відміну від інших інтеграцій, Telegram має write-tools – агент може надсилати повідомлення, файли, редагувати й видаляти. Деструктивні дії йдуть через draft→confirm: агент готує чернетку, ти переглядаєш (і за потреби редагуєш) у картці підтвердження, і нічого не надсилається, доки ти не натиснеш Send.

Підключення

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

У Telegram відкрий @BotFather → /newbot → дай ім’я → скопіюй токен (формат 123456789:ABCdef…).

2. Connect

app.brama.work → Integrations → Telegram → встав токен бота й натисни Authorize. Brama перевірить токен у Telegram, збереже його зашифрованим і автоматично зареєструє webhook. Статус інтеграції стане active, і ти побачиш Webhook URL зі статусом доставки.
Бот бачить лише ті чати, у яких він уже отримав повідомлення. Щоб бот бачив пости каналу – додай його в канал; додав пізніше й не бачиш постів? Натисни Перепідключити webhook на сторінці інтеграції (токен вводити не треба).

3. Запит

У своєму MCP клієнті (Claude Desktop, Gemini CLI – див. Connect a client):
Які повідомлення я отримав у Telegram сьогодні?
Агент викличе brama_telegram_list_messages і поверне відправника, чат, текст і час кожного повідомлення.

Як Brama знаходить адресата

Коли ти кажеш агенту «напиши Марині» чи «опублікуй у каналі продажів», він спершу шукає адресата за іменем через brama_telegram_find_chat і лише потім готує чернетку. Brama ніколи не вгадує chat_id з історії повідомлень.
  • Адресна книга з кожного вхідного апдейту. Brama веде перелік усіх чатів, з яких твій бот отримував повідомлення: людей, груп, каналів і форум-топіків. Імена, назви й @username оновлюються з кожним новим апдейтом, тож перейменований чат знаходиться під новою назвою.
  • Одне написання для всіх алфавітів. Українське, російське й латинське написання імені зводяться до одного: «Віктор», «Виктор», «Viktor» і «Wiktor» – це один пошук. Агенту не треба шукати двічі.
  • Спершу точний збіг, потім схожий. Кожне слово запиту має бути в імені, тож «Viktor Bystrov» знайде лише тих, у кого є обидва слова. Найкращі збіги – цілі слова – йдуть першими. Лише коли точного збігу немає, Brama показує близькі написання: «Барышевка» знайде канал «Baryshivka».
  • Агент не вибирає сам. Якщо збігів кілька, відповідь має статус ambiguous, і агент мусить показати тобі кандидатів, а не взяти найсвіжішого. Остаточно отримувача ти бачиш у картці підтвердження.
  • can_send наперед. Кожен кандидат одразу каже, чи можна туди написати, а якщо ні – чому. Наприклад, бота видалили з групи, отримувач – інший бот або бізнес-чат поза 24-годинним вікном: у Telegram Business відповісти клієнтові можна лише протягом 24 годин після його останнього повідомлення.
  • Brama запам’ятовує твій вибір. Коли ти підтверджуєш картку для імені («Марина»), наступного разу той самий запит одразу повертає цей чат: status = exact і matched_by = alias. Працює й для прізвиськ: «мама» може вести на чат «Олена». Поле other_matches показує, скільки ще чатів зараз збігаються з цим ім’ям, тож новий чат з тим самим іменем не загубиться. Якщо ти маєш на увазі когось іншого, агент повторить пошук з ignore_aliases: true і покаже всіх кандидатів.
  • Групи, що стали супергрупами. Коли Telegram оновлює групу до супергрупи, її адреса змінюється. Brama повертає чат уже під новою адресою і вказує стару в moved_from_chat_id, тож повідомлення не піде на мертвий id.
Якщо ти підключив власну базу даних (Налаштування → Власна база даних), історія повідомлень лишається лише у твоїй базі, і окремої адресної книги Brama для тебе не веде. Пошук адресата тоді йде по історії повідомлень у твоїй базі: кирилиця й латиниця так само знаходять одна одну (Марина / Maryna), але українське й російське написання одного імені (Віктор / Виктор) можуть не збігтися.

Read tools (live)

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

brama_telegram_find_chat

Знайти адресата за іменем: людину, групу, канал або форум-топік. Повертає кандидатів з повною адресою, а не одну вгадану.Параметри:
  • query (required) – фрагмент імені, назви, @username або назви топіка, щонайменше 2 символи; будь-яким алфавітом
  • kind (optional) – private (людина), group, supergroup, channel або topic (форум-топік)
  • limit (optional) – default 10, max 20
  • ignore_aliases (optional) – true, щоб не брати запам’ятований вибір для цього імені й показати всі збіги
Повертає: status – exact (один збіг), ambiguous (кілька – покажи їх людині й дай вибрати) або none (запитай, кого мали на увазі). Кожен кандидат має адресу (chat_id, а для топіків ще message_thread_id або direct_messages_topic_id), ім’я, час і уривок останнього повідомлення, can_send з причиною, якщо ні, та other_matches – скільки інших кандидатів мають те саме ім’я. Якщо відповідь дав запам’ятований вибір, кандидат має matched_by: "alias", а other_matches – скільки ще чатів збігаються з ім’ям.Use: “напиши Марині”, “опублікуй у топіку Пакування”, “надішли в канал продажів”.

brama_telegram_list_messages

Повідомлення, які отримав бот, найновіші зверху – опційно за діапазон дат та/або для одного чату. Повертає відправника (username, ім’я), чат (id, тип, заголовок), текст і час надсилання (UTC).Параметри:
  • from / to (optional) – ISO 8601 UTC datetime
  • chat_id (optional) – обмежити одним чатом
  • limit (optional) – default 50, max 200
Use: “які повідомлення я отримав сьогодні?”, “останні повідомлення від «людини»”.

brama_telegram_search_messages

Повнотекстовий пошук по отриманих повідомленнях за підрядком (case-insensitive), найновіші зверху, опційно за діапазон дат.Параметри:
  • query (required) – підрядок для пошуку
  • from / to (optional) – ISO 8601 UTC datetime
  • limit (optional) – default 50, max 200
Use: “знайди повідомлення про X”, “хтось згадував «тему»?”.

brama_telegram_get_conversation

Одна розмова (усі повідомлення з одним chat_id) у хронологічному порядку – від старіших до новіших, обмежено N найновішими.Параметри:
  • chat_id (required) – з list / search
  • limit (optional) – default 50, max 200 найновіших
Use: “про що ми говорили з «чатом»?”, “покажи розмову з X”.

brama_telegram_get_message_raw

Повний raw-об’єкт одного повідомлення – деталі, які list/conversation згортають: метадані медіа (incl. file_id), forward chain, entities, reply context, локація, опції опитування тощо. Повертає метадані, НЕ байти медіафайлу.Параметри:
  • chat_id (required)
  • message_id (required)
Use: глибокий розбір одного повідомлення.

Прямі відправки й підтвердження

send_* (пряма відправка) надсилає одразу, без картки. Тому Brama пускає її лише туди, де адресата вже підтвердила людина:
  • Підтверджена адреса – чат, для якого ти підтвердив картку чернетки, або чат, куди Brama за останні 90 днів уже надсилала схвалене повідомлення (через картку або дозволену пряму відправку). Топік форуму рахується разом зі своєю групою: підтвердження одного топіка відкриває всю групу.
  • Новий чат – прямий send_* повертає error_code: "address_not_confirmed" з підказкою, яку чернетку використати (use_tool). Агент готує *_draft, ти один раз натискаєш Send у картці, і після цього прямі відправки в цей чат знову йдуть самі. Чернетки й картки підтвердження ніколи не блокуються.
  • До 27.11.2026 (00:00 UTC) – перехідний період. Прямі відправки ще не блокуються. Brama лише запам’ятовує всі чати, куди твій агент успішно пише, тож щоденні звіти й інші регулярні відправки після 27.11 працюватимуть без жодних дій з твого боку. Блокуватися будуть лише зовсім нові чати, куди за 90 днів нічого не надсилали.
Для тенантів з власною базою даних перевірка підтвердженої адреси поки не діє: прямі відправки працюють як раніше.

Повторні відправки не дублюються

Якщо агент повторює ту саму відправку – той самий текст або файл у той самий чат протягом хвилини, – Brama не шле її вдруге:
  • sent: true з deduplicated: true і тим самим sent_message_id – повідомлення вже доставлене, повтор нічого не надіслав;
  • error_code: "duplicate_in_flight" – попередня спроба ще в дорозі або її результат невідомий. Перевір чат і повтори через хвилину, лише якщо повідомлення не прийшло;
  • outcome_unknown: true (з retryable: false) – зв’язок обірвався вже після того, як повідомлення пішло в Telegram, тож воно могло дійти. Не повторюй навмання – спершу перевір чат.
Те саме з карткою: одна підтверджена картка – одне повідомлення, навіть якщо Send натиснули двічі або зв’язок обірвався.

Write tools (live)

Надсилання, редагування й видалення йдуть AS the bot і тільки в чати, з яких бот уже отримував повідомлення. Деструктивні дії мають парний *_draft, що показує інтерактивну картку підтвердження – нічого не відбувається, доки ти не натиснеш Send/Delete. Адреса у всіх send_* і *_draft – це об’єкт, а не лише chat_id: передавай його в тому вигляді, в якому повернув brama_telegram_find_chat.
  • chat_id (required) – чат
  • message_thread_id (optional) – топік у форумі (або в приватному чаті з топіками). Без нього повідомлення піде в загальний топік «General»
  • direct_messages_topic_id (optional) – розмова в direct messages каналу; Telegram вимагає його для таких чатів
Пости в канал ідуть лише через *_draft: картка показує «CHANNEL POST» і кількість підписників, бо повідомлення отримають усі.

brama_telegram_send_message

Надіслати текстове повідомлення в чат – доставляється одразу. Лише в підтверджену адресу (див. розділ «Прямі відправки й підтвердження» вище). Для перегляду / редагування у картці перед надсиланням використовуй brama_telegram_send_message_draft.Параметри: адреса (chat_id (required), message_thread_id / direct_messages_topic_id (optional)), text (required), reply_to_message_id (optional), parse_mode (optional).

brama_telegram_send_message_draft

Підготувати повідомлення й показати інтерактивну картку підтвердження (отримувач + редагований текст + Send/Cancel) перед надсиланням.Параметри: ті самі, що в brama_telegram_send_message, плюс query (optional) – ім’я, за яким агент шукав адресата в brama_telegram_find_chat. Після твого Send Brama запам’ятає цей вибір для імені.

brama_telegram_send_rich_message

Надіслати довге, багатоформатне повідомлення (rich-markdown: заголовки, списки, таблиці, цитати, код; до 32768 символів) – доставляється одразу. Підходить для звітів і метрик.Параметри: адреса (chat_id (required), message_thread_id / direct_messages_topic_id (optional)), markdown (required), reply_to_message_id (optional).
Rich-повідомлення рендеряться у нативних застосунках Telegram (iOS, Android, desktop), але НЕ у браузерному Telegram Web. Для отримувачів на Telegram Web обирай brama_telegram_send_message.

brama_telegram_send_rich_message_draft

Підготувати довге rich-markdown повідомлення й показати картку підтвердження з рендереним preview перед надсиланням.Параметри: ті самі, що в brama_telegram_send_rich_message, плюс query (optional) – ім’я, за яким агент шукав адресата в brama_telegram_find_chat. Після твого Send Brama запам’ятає цей вибір для імені.

brama_telegram_send_file

Надіслати файл (фото або документ) у чат – доставляється одразу. Файл задається АБО file_url (публічна URL, яку Telegram завантажує), АБО file_base64 (байти + file_name). as_photo=true шле inline як фото; default – як документ.Параметри: адреса (chat_id (required), message_thread_id / direct_messages_topic_id (optional)), file_url або file_base64 (рівно один), file_name (required з base64), mime_type (optional), as_photo (optional), caption (optional), reply_to_message_id (optional).

brama_telegram_send_file_draft

Підготувати файл і показати картку підтвердження (отримувач + chip вкладення + редагований caption) перед надсиланням.Параметри: ті самі, що в brama_telegram_send_file, плюс query (optional) – ім’я, за яким агент шукав адресата в brama_telegram_find_chat. Після твого Send Brama запам’ятає цей вибір для імені.

brama_telegram_edit_message

Відредагувати текст повідомлення, яке бот сам надіслав, замінивши його новим – застосовується одразу. Telegram дозволяє редагувати лише власні недавні повідомлення бота. Edit реверсивний, тож без окремої картки – йде через стандартний tool-approval gate клієнта.Параметри: chat_id (required), message_id (required), text (required), parse_mode (optional).

brama_telegram_delete_message_draft

Підготувати ВИДАЛЕННЯ повідомлення бота й показати картку підтвердження (отримувач + preview + Delete/Cancel). Видалення незворотне, тому прямого delete-tool немає – тільки через картку.Параметри: chat_id (required), message_id (required), label (optional).

brama_telegram_confirm_send

Виконати дію, яку підготувала чернетка – надіслати повідомлення/файл (з можливо відредагованим текстом) або видалити повідомлення. Single-use токен. На хостах, що рендерять картку, цей tool викликається лише кнопкою картки (Send/Delete).Параметри: confirm_token (required), text (optional).

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

  • “Які повідомлення я отримав у Telegram сьогодні?”
  • “Напиши Марині, що зустріч переноситься.” (агент знайде Марину, а якщо їх кілька – запитає, яку; наступного разу Brama вже пам’ятатиме твій вибір)
  • “Знайди повідомлення про оплату за останній тиждень.”
  • “Про що ми говорили з «чатом»?”
  • “Підготуй відповідь «людині»: …” (агент покаже картку перед надсиланням)
  • “Надішли цей звіт у чат як rich-повідомлення.”

Безпека

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

Питання

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