Telegram

Telegram — ещё один способ связаться с командой. Ответы, уведомления, сводка и карточки подтверждений приходят на телефон, а ты можешь писать, отправлять фото, файлы и голосовые или делиться местом на карте. Бот твой собственный: ты его создаёшь, и он отвечает только в твоём личном чате с ним.

Публичный адрес хабу для этого не нужен: он сам спрашивает у Telegram новые сообщения, так что бот работает и с ноутбука дома.

Создай бота#

1. В Telegram открой @BotFather и отправь /newbot.
2. Придумай имя, а потом username, который заканчивается на bot.
3. BotFather пришлёт токен вида 1234567890:AA…. Скопируй его.

Подключи#

Скажи в чате «подключи Telegram». Ассистент покажет карточку Telegram:

1. Вставь токен в поле Токен Telegram-бота и нажми Сохранить в хранилище. Токен уходит прямо в зашифрованное хранилище (как telegram_bot_token), ассистент его не видит. Можно и просто вставить токен в сообщение: хаб узнает его, вынет из текста и сохранит.
2. Бот подключится сам. На карточке появится: «Последний шаг: откройте @твой_бот в Telegram и нажмите «Запустить» — чат привяжется сам».
3. Нажми Открыть бота в Telegram, а в Telegram — Запустить. Бот ответит: «Готово — этот чат привязан к Piomio».

Если кнопка не подходит, отправь боту команду с карточки: /start и шестизначный код. Новый код сделает другой.

Та же карточка есть в Настройки → Плагины → Telegram → Подключение. Значок на ней показывает состояние: Подключён, Ждёт привязки, Нет токена, Токен не принят (замени токен), Нет связи или Подключение….

Только твой чат#

Бот привязывается ровно к одному личному чату — тому, из которого пришёл код.

• Группу привязать нельзя: бот ответит, что привязать можно только личный чат.
• Любой другой человек, написавший боту, получит один вежливый ответ «этот бот личный» — и всё.
• После пяти неверных кодов из одного чата привязка из него блокируется, а после двадцати неверных кодов всего код меняется.

Кто отвечает#

В Telegram ты говоришь с агентом по умолчанию — в том же разговоре, что и его чат в приложении. Он, как обычно, может передавать работу коллегам (см. Агенты и команда). Чтобы отвечал другой агент, скажи «сделай Анну агентом по умолчанию» или выбери Агент по умолчанию в Настройки → Общие.

Ответы на то, что ты пишешь этому агенту в приложении, тоже приходят в Telegram, а над ними — твои слова в цитате («Вы в веб-версии:»), так что в Telegram это читается как один разговор. Скажи «не присылай в Telegram ответы из веб-чата», чтобы это выключить. Чаты других агентов и групповые чаты в Telegram не дублируются.

Что приходит в Telegram#

• Ответы с форматированием: жирный, курсив, списки, ссылки, цитаты и код. Заголовки становятся жирными, таблица — выровненным блоком, а длинный ответ делится на несколько сообщений. Пока агент работает, Telegram показывает «печатает…». Для превью ссылки сервера Telegram открывают её сами, поэтому превью в ответе бывает не больше одного и только у ссылки, которая не унесёт твои данные: после внешнего контента ссылка, которую агент составил сам, приходит без превью, а ссылка из прочитанного или из твоих слов — с ним.
• Картинки из ответа приходят фото или альбомом до десяти штук. Большая картинка приходит файлом. То, что Telegram не принял, приходит ссылками. Картинку, которую чат придержал (см. Картинки и карусели), Telegram не получит.
• Карты приходят точкой на карте с названием места.
• Уведомления с жирным заголовком. У уведомлений от напоминаний и слежений есть кнопки 👍 Полезно, 🔉 Реже и 🔕 Выключить. В тихие часы они приходят без звука.
• Сводка (см. Задачи, расписания и «Входящие»).
• Карточки подтверждений с кнопками ✅ Разрешить и ❌ Отклонить. После нажатия в сообщении появится результат; если ты уже ответил в другом месте, бот так и напишет.

У уведомлений и сводки есть ещё кнопка Открыть — если адрес хаба (PIOMIO_PUBLIC_URL) публичный и по https, а у карточек подтверждений кнопка 🔐 Открыть пульт — если таков адрес пульта (PIOMIO_CONSOLE_URL). См. Настройки и переменные окружения.

Карточка подтверждения в Telegram по умолчанию короткая: какой агент просит и какое действие, плюс ссылка на пульт безопасности с подробностями. Чтобы видеть подробности прямо в Telegram, включи Показывать детали в Telegram в Настройки → Общие. Подробнее — в разделе Подтверждения и автомод.

Страницы и другие карточки остаются в приложении: в Telegram приходят слова агента.

Что можно отправить#

Пиши как в приложении. А ещё можно отправить:

• Фото, альбомы, файлы, видео и аудио. Альбом доходит до агента одним сообщением. Файлы попадают в рабочую папку агента.
• Голосовые. Хаб расшифровывает их до ответа агента, если настроена расшифровка речи; в первый раз ассистент сам предложит её настроить (см. Чат).
• Места: точка или заведение доходят до агента с названием, адресом и координатами.
• Пересланные сообщения и ответы. Агент узнаёт, откуда переслано сообщение и на что ты отвечаешь.

Боты в Telegram могут скачивать файлы до 20 МБ. Про файл побольше бот предупредит — отправь его в приложении. Стикеры, опросы и контакты не передаются.

Если вставить в сообщение ключ или токен, хаб переложит его в хранилище, а бот удалит твоё сообщение, чтобы секрет не остался в переписке. Если Telegram не даст удалить, бот попросит удалить сообщение самому.

Команды#

Меню команд бота показывает их на языке хаба. Другие команды, например /task или /goal, уходят ассистенту, как в приложении (см. Чат). Всё, что пишет бот, — на языке хаба.

Отвязать или выключить#

• Отвязать чат: попроси ассистента показать настройку Telegram или открой Настройки → Плагины → Telegram → Подключение и нажми Отвязать. Бот напишет в старый чат, что его отвязали, и сделает новый код — можно привязать другой чат.
• Заменить токен: Заменить рядом с токеном на той же карточке. Так делают после того, как отозвали токен в BotFather.
• Выключить Telegram: «выключи Telegram» или переключатель на его странице в Настройки → Плагины.

Настройки#

В Настройках плагина Telegram — ссылка на токен в хранилище и Адрес Bot API. Адрес меняют, только если у тебя свой сервер Bot API; обычно это https://api.telegram.org.