Telegram

Материал из SaleBot Help
Перейти к навигации Перейти к поиску
ПОСЛЕДНЯЯ ЗНАЧИМАЯ ПРАВКА
Участник: BotDev.One

Любой телеграм-бот получает уникальный идентификатор при создании (api-токен). Этот токен используется, как при подключении бота, так и при создании настраиваемых API запросов к нему HTTP-методами POST и GET.

API-токен имеет вид: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.

Запросы по API вида: https://api.telegram.org/bot_name:api_token/method_name.

Лимиты в Телеграм



ОБЩИЕ ЛИМИТЫ ЛИМИТЫ ДЛЯ БОТОВ ФАЙЛЫ
Длина одного сообщения
до 4096 символов
Количество ботов в @BotFather
до 20 ботов
Доступны все типы вложений
Ссылки Изображения Аудио Видео Файлы
Подпись к медиафайлам
до 1024 символов
Имя бота @…bot
до 32 символов
Отправка файлов
до 50 Мб[1]
Продолжительность видеосообщения
до 1 минуты

Информация о боте /setabouttext
до 120 символов
Отправка через сервер Telegram
до 2000 Мб
Изображений и видео в 1 сообщении
до 10 медиа
Описание бота /setdescription
до 512 символов
Загрузка файлов
до 20 Мб
Размер изображения в пикселях
до 1280 x 1280 пикселей
Клавиатурных кнопок (reply)
до 100 кнопок
Загрузка через сервер Telegram
до 2000 Мб
Длина имени файла
до 60 символов
Кнопок в тексте (inline)
до 10 240 байт[2]
Отправка вложений через URL
до 5 Мб (фото)
до 20 Мб (файлы)
  1. gif, pdf и zip файлы
  2. Учитывается: - текст сообщения, - markdown разметка, - теги. (1 символ ≈ 4 байтам)

Как подключить бота

Бот в Telegram создается при помощи другого бота под названием @BotFather. Отправляем ему команду /newbot, выбираем имя, которое будет отображаться в списке контактов, логин бота должен заканчиваться на bot или _bot.

Если адрес не занят, BotFather пришлет в ответ сообщение с токеном — «ключом» для доступа к созданному боту. Его нужно сохранить и никому не показывать:

Создание и получение API-токена бота. Нажмите, чтобы скопировать токен


После этого заходим во вкладку Каналы, выбираем телеграм и вводим полученный токен:

Подключение канала Телеграм

Жмем кнопку готово. На этом подключение бота завершено.

Видео: https://youtu.be/yP2ABDNfDZI - создание бота в Телеграм

https://youtu.be/NuvKVGXDywI - подключение к Телеграм

Форматирование сообщений в Телеграм

Защищенный режим для контента

Работает только в Телеграм (с версии от 21.12.2021). Если защищенный режим не поддерживается версией Телеграм, то пользователь увидит сообщение с просьбой обновить мессенджер

Защищенные сообщения нельзя переслать, скопировать или сохранить. На телефоне нельзя сделать скриншот.

Для включения данной функции достаточно активировать переключатель Ползунок: Markdown в Telegram.

Видео: https://youtu.be/mBSG2RY2y1k

Получение файлов от пользователя

Как работать с кнопками

https://youtu.be/FrqqalU0CmY

Как совместить два вида кнопок

Создайте блок с reply-кнопкой (кнопками), которые вам необходимы.

Например:

[{"type": "reply", "text": "НАЗВАНИЕ КНОПКИ", "line": 0, "index_in_line": 0}]
Телеграм Кнопки (пример 1).png

Далее создаете следующий блок (таймер в 0 секунд) с inline-кнопками, которые необходимо разместить, не убирая reply-кнопки.

Например:

[{"type": "inline", "text": "НАЗВАНИЕ КНОПКИ", "line": 0, "index_in_line": 0}]
Телеграм Кнопки (пример 2).png

Результат:

Телеграм Кнопки (пример 3).png



Кнопка "Поделиться"

Кнопка для пересылки сообщения другому пользователю из списка контактов.

После нажатия на кнопку, открывается список контактов, пользователь выбирает кому переслать сообщение и оно вставляется в поле ввода:

Кнопка Поделиться в Телеграм.


Чтобы создать кнопку, добавим ее в редакторе (через ) и выберем из списка пункт Поделиться (только Telegram), заполним поля:

Создание кнопки Поделиться в Телеграм. Поле Дополнительный текст необязательное.


Таким образом, можно передавать ссылки, в том числе на сообщения из каналов в телеграм.

Код кнопки:

[{"line":0,"index_in_line":0,"text":"Текст для кнопки Поделиться","type":"inline","share_info":"https://salebot.wiki/page/Telegram","share_text":"Тут можно почитать о конструкторе Salebot"}]


Кнопка авторизации на сайте

Кнопка авторизации на сайте с помощью Телеграм и код для встраивания.
Код для встраивания
<script async src="https://telegram.org/js/telegram-widget.js?19" data-telegram-login="botname_bot" data-size="large" data-onauth="onTelegramAuth(user)" data-request-access="write"></script>
<script type="text/javascript">
  function onTelegramAuth(user) {
    alert('Logged in as ' + user.first_name + ' ' + user.last_name + ' (' + user.id + (user.username ? ', @' + user.username : '') + ')');
  }
</script>


Для работы этой кнопки требуется привязка бота к домену. Делается это через @BotFather.

Выберите вашего бота в диалоге с @BotFather и нажмите Bot Settings:

Телеграм Кнопка авторизации на сайте 1.png

Далее, переходим в пункт DomainSet Domain:

Телеграм Кнопка авторизации на сайте 2.png

Вам будет предложено установить домен для бота.

При использовании минилендинга, например: https://salebot.site/md/1914fd9ddcf63bf413d8fc6a67cddf2f, указываете домен: salebot.site.

Если используете эту кнопку на своем сайте, то нужно настроить проверку подлинности данных:

После того, как все настроено, можно создать кнопку:

Добавление кнопки Авторизация через Телеграм

В поле Текст впишите текст для надписи на кнопке, в поле Ссылка - url-адрес страницы, на которой будет реализована авторизация.

Остальные поля будут нужны, если для авторизации будет использоваться отдельный бот (необходимо указать имя бота):  

Если вы хотите отправлять сообщения от имени указанного бота, то поставьте галочку “Запросить разрешение у пользователя на отправку сообщений от бота”.

Кнопки в переменных

Расширенные настройки кнопок (код кнопок)
Кнопки в переменных могут использоваться в функциях API Telegram

В Salebot можно использовать кнопки в вызовах функций API Telegram, используя привычный интерфейс создания кнопок.


Как это сделать:

  • Добавьте в редакторе необходимые вам кнопки;
  • Переместите появившийся код кнопок из поля Расширенные настройки кнопок в поле калькулятора;
  • Добавьте код кнопок в вашу переменную.

Теперь переменную с кнопками можно использовать в вызовах функций (например, tg_send_message):

Кнопки в переменной и вызов функции tg_send_message()


В результате, вы получите кнопки в том виде, в каком задавали их в расширенных настройках кнопок:

Телеграм Кнопки в переменных (пример).png

Код калькулятора:

buttons='[{"line":0,"index_in_line":0,"text":"111","type":"inline","callback":"qwerty1"},{"line":0,"index_in_line":1,"text":"222","type":"inline","callback":"qwerty2"},{"line":1,"index_in_line":0,"text":"333","type":"inline","callback":"qwerty3"}]'
tg_send_message(platform_id, "123", "", buttons)

Inline режим

Включение режима Inline в Телеграм /setinline

Помимо отправки команд в личных сообщениях или группах, пользователи могут взаимодействовать с вашим ботом с помощью встроенных запросов (inline). Если встроенные запросы включены, пользователи могут вызвать вашего бота, введя его имя (@name_bot) и запрос в текстовом поле ввода в любом чате. Запрос отправляется вашему боту при вводе строки. Таким образом, люди могут запрашивать контент у вашего бота в любом из своих чатов, групп или каналов, не отправляя никаких сообщений.

Чтобы включить эту опцию, отправьте команду /setinline на @BotFather и укажите текст-заполнитель (placeholder), который пользователь увидит в текстовом поле ввода после указания имени вашего бота.

После нажатия на вариант из списка в инлайн режиме, отправится сообщение, которое указано в заголовке выбранного варианта и на это значение можно настроить реакцию в воронке.


Чтобы указать данные для вывода в инлайн режиме, нужно задать переменную inline_bot. В инлайн режиме поиск по значениям в переменной inline_bot происходит, практически, в реальном времени.

Данные в переменной могут быть заданы тремя вариантами. Рассмотрим от самого простого, до максимальных настроек.

1. Массив с текстовыми данными

Например, поиск по массиву продуктов:

Телеграм Inline режим (массив-текст-1).png

Поиск происходит по вхождению введенной фразы в вариантах в массиве. Например, ввели букву «м» - выдало три варианта, добавили букву «а», и результат отфильтрован по новым данным.

Поиск по мере набора

После нажатие на нужный пункт в бот будет отправлено сообщение от пользователя:

Отправка выбранного варианта в бот

Пример данных:

inline_bot = ["Молоко", "Хлеб", "Макароны", "Шоколад", "Яйца", "Масло", "Слойка", "Чай", "Овощи", "Фрукты"]

2. Массив со словарями для вариантов кнопок

Второй вариант более настраиваемый и, вместо текстовых значений, массив будет содержать словари.

Разберем максимальный набор параметров для одного словаря:

inline_bot = {"title": "Оплата", "description": "Способы оплаты описание", "thumb_url": "https://img.icons8.com/dusk/50/000000/card-exchange.png", "message_text": "оплата товара 1"}
  • title - заголовок кнопки
  • description - описание
  • thumb_url - ссылка на картинку
  • message_text - этот текст отправится при выборе варианта
1. Вывод результатов поиска2. Отправка текста в чат после нажатия

Для одного варианта (словаря), обязательным является только ключ title со значением, которое отправится при нажатии на этот пункт, например – {"title": "Настройка"}:

Телеграм Inline режим (массив-словарь-2).png

Пример данных:

[{"title": "Корзина", "description": "Выбранные товары", "thumb_url": "https://img.icons8.com/dusk/64/000000/shopping-basket.png"}, 
{"title": "Доставка", "description": "Варианты доставки заказа", "thumb_url": "https://img.icons8.com/dusk/64/000000/delivery--v1.png"}, 
{"title": "Оплата", "description": "Способы оплаты описание", "thumb_url": "https://img.icons8.com/dusk/50/000000/card-exchange.png", "message_text": "оплата товара 1"}, 
{"title": "Настройка"}]
Телеграм Inline режим (массив-словарь-3).png

3. Словарь со списком для вариантов кнопок

Третий вариант подходит, если вы хотите задать определенные меню на нужные фразы и удобен в использовании вместе с инлайн кнопкой, в которой зашита нужная фраза.

В примере, поиск будет происходить по ключам: меню, посты и продукты:

Телеграм Inline режим (массив-словарь-список-1).png


Структура следующая – ключ: [массив кнопок]:

{"поисковая фраза1": 
[{"title": "Корзина", "description": "Выбранные товары"}, 
{"title":  "Оплата",  "description": "Способы оплаты", "thumb_url": "#{переменная с урлом}", "message_text": "Способы оплаты"}, 
{"title": "Доставка", "description": "Варианты доставки заказа", "thumb_url": "ссылка на картинку"}], 
"поисковая фраза2": 
[{"title": "Первый",   "description": "Описание 1111"}, 
{"title": "Четвертый", "description": "#{переменная}"}], 
"поисковая фраза3": ["Молоко", "Хлеб", "#{переменная}", "Шоколад"]}

Разберем максимальный набор параметров для одного варианта (словаря). Для примера возьмем следующий:

inline_bot = {"title": "Оплата", "description": "Способы оплаты описание", "thumb_url": "https://img.icons8.com/dusk/50/000000/card-exchange.png", "message_text": "оплата товара 1"}
  • title - заголовок кнопки
  • description - описание
  • thumb_url - ссылка на картинку
  • message_text - этот текст отправится при выборе варианта


Минимально, один вариант (словарь), должен содержать ключ title со значением, которое отправится при нажатии на этот пункт, например – {"title": "Настройка"}


Пример данных:

{"меню":
[{"title": "Корзина", "description": "Выбранные товары", "thumb_url": "https://img.icons8.com/dusk/64/000000/shopping-basket.png"},
{ "title": "Оплата",  "description": "Способы оплаты", "thumb_url": "https://img.icons8.com/dusk/50/000000/card-exchange.png", "message_text": "Способы оплаты"},
{ "title": "Доставка", "description": "Варианты доставки заказа", "thumb_url": "https://img.icons8.com/dusk/64/000000/delivery--v1.png"}],
"посты":
[{"title": "Первый", "description": "Описание 1111"},
{ "title": "Второй", "description": "Описание 2222"},
{ "title": "Третий", "description": "Описание 333"},
{ "title": "Четвертый", "description": "Описание 44444"}],
"продукты": ["Молоко", "Хлеб", "Макароны", "Шоколад", "Яйца", "Масло", "Слойка", "Чай", "Овощи", "Фрукты"]}

Инлайн кнопка с заданным поисковым значением

Чтобы задать поисковую фразу, нужно в инлайн кнопку добавить параметр inline_query.

Со значением которое автоматически подставляется в запрос.

Добавим три кнопки, которые соответствуют примеру выше, код кнопок:

[{"line":0,"index_in_line":0,"text":"Покажи меню","type":"inline","inline_query":"меню"}, {"line":0,"index_in_line":1,"text":"Статьи","type":"inline","inline_query":"посты"}, 
{"line":2,"index_in_line":0,"text":"Список продуктов","type":"inline","inline_query":"продукты"}]
Телеграм Инлайн кнопка с поиском.png

При нажатии на кнопку Статьи выведется найденный список кнопок (при добавлении указали для этой кнопки "inline_query":"посты"):

Телеграм Инлайн кнопка с поиском (пример-1).png

Нажмем на кнопку Покажи меню:

Телеграм Инлайн кнопка с поиском (пример-2).png

Варианты берутся из заданной переменной, как описано выше

Настройка инлайн кнопки с заданным поисковым значением в Телеграм (вкладка Настройки проекта)

Переменную inline_bot можно задать не только в общих переменных, но и просто переменной, в таком случае ее значение нужно заключить в одинарные кавычки, поле калькулятора:

inline_bot = '["Молоко", "Хлеб", "Макароны", "Шоколад", "Яйца", "Масло", "Слойка", "Чай", "Овощи", "Фрукты"]'

Также, можно любое значение передать в виде переменной:

inline_bot = '["Молоко", "Хлеб", "Макароны", "Шоколад", "Яйца", "Масло", "Слойка", "Чай", "Овощи", "Фрукты", "#{aa}"]'

Бот в группах

Чтобы бот работал в группах Телеграм (каналы или чаты) , необходимо:

  • Добавить бота в группу в качестве администратора;
  • Включить в BotFather эту возможность (/setjoingroups), как указано ниже:
/setjoingroups


Переменные в группах

Переменные с информацией об авторе сообщения
message_from идентификатор автора сообщения
message_from_name имя автора сообщения
message_from_username ник автора сообщения в Телеграм
Переменные с информацией о пересылаемом сообщении
reply_message_id номер сообщения, которое пересылают
reply_from кто автор пересылаемого сообщения
reply_from_name имя того, чье сообщение пересылается
reply_from_username ник того, чье сообщение пересылается
reply_from_chat_id номер диалога, из которого сообщение переслали
Переменные с информацией об авторе сообщения
chat_member_name имя пользователя
chat_member_username ник пользоваля
chat_member_id номер пользователя


Колбеки в группах

Колбеки во вкладке Клиенты
Колбек Событие
new_chat_member добавлен новый пользователь
left_chat_member пользователь покинул канал
kicked_chat_member пользователь удален администратором
chat_join_request получена заявка на добавление в канал
edited_channel_post пост на канале был отредактирован (edited_channel_post + дата и время редактирования)

При получении любого из вышеназванных колбеков обновляются значения переменных:

chat_member_name имя пользователя
chat_member_username ник пользоваля
chat_member_id номер пользователя


Заявки на вступление в группу

Для принятия заявки и добавления пользователя в канал или чат используется функция:

tg_approve_chat_join_request(platform_id, user_id)

Для того чтобы отклонить заявку используется функция:

tg_decline_chat_join_request(platform_id, user_id)


Удаление системных уведомлений в группах

Для автоматического удаления всех системных сообщений достаточно присвоить любое значение переменной del_tg_system_messages (переменная может быть как константой проекта, так и переменной сделки) и дать боту разрешение на удаление сообщений.

Удаляются следующие тиды системных уведомлений:

Тип уведомления Описание
new_chat_member Пользователь вступил в группу
left_chat_member Пользователь вышел из группы
pinned_message Закреплено сообщение
new_chat_photo Изменена фотография группы
delete_chat_photo Удалена фотография группы
new_chat_title Изменено название группы

Если вы хотите удалять лишь избранные типы системных уведомлений, то вместо переменной del_tg_system_messages создайте переменную del_tg_chosen_messages и поместите в нее массив с типами уведомлений, которые нужно удалить.

Например:

del_tg_chosen_messages = ['new_chat_member','left_chat_member','pinned_message','new_chat_photo','delete_chat_photo']

Бот будет удалять все уведомления, кроме изменения названия группы.

Примеры

Проверить, является ли пользователь участником группы:

member_status = get(get(tg_get_chat_member('#{chat_id}', '#{platform_id}'), 'result'), 'status')
/* или */
member_status = get(tg_get_chat_member('#{chat_id}', '#{platform_id}'), 'result|status')

В переменную member_status будет сохранен статус участника (member, administrator, left, kicked, или none, при ошибке).

Создание опроса

В Телеграм можно создать простой опрос или викторину.

Простой опрос

Для создания обычного опроса используется функция tg_send_poll():

tg_send_poll (platform_id, question, options, is_anonymous, allows_multiple_answers, reply_markup, disable_notification, protect_content, token)
Обязательные параметры:
  • platform_id - id в Телеграм, куда нужно прислать сообщение
  • question - вопрос
  • options - массив вариантов ответов
Необязательные параметры:
  • is_anonymous - 1 - анонимный опрос, '' - не анонимный
  • allows_multiple_answers - 1 - возможны несколько ответов, '' - один ответ
  • reply_markup - кнопки сообщения или '' - без пользовательских кнопок
  • disable_notification - 1 - отправить с уведомлением, '' - без уведомления
  • protect_content - 1 защитить от копирования и скриншотов, '' - без защиты
  • token - токен бота, если не передан используется текущий


Пример, код в калькуляторе:

options = ["белый", "красный", "синий", "зеленый"]
tg_send_poll(platform_id, 'Ваш любимый цвет?', options, 1, '', '', 1, '')
Телеграм Простой опрос (пример).png


Примечания

Колбек poll_answer, пользователь выбрал вариант 4
  1. Функция tg_send_poll() возвращает message_id, который лучше сохранить, так как с его помощью можно завершить опрос функцией tg_stop_poll() (описание ниже) и получить результат.
  2. Если опрос добавлен пользователем в канал, то в диалог придет колбек: poll_added текст_вопроса.
  3. Если опрос добавлен пользователем в чат, то в диалог придет колбек: poll_added user_id текст_вопроса.
  4. Если опрос добавлен ботом, колбек не приходит.
  5. В канале можно создавать только анонимные опросы.
  6. Если опрос был отправлен в диалог пользователя с ботом, то (при ответе пользователя) придет колбек с выбранными ответами: poll_answer 5325838371359031647 [3], нумерация ответов начинается с 0 (на скриншоте был выбран 4 ответ).
  7. Если не анонимный опрос был создан в чате (ботом или пользователем), в котором состоит бот, то на каждый голос будет отправлен вебхук, при получении которого, будет отправлен колбек poll_answer 5325838371359031647 [3]в диалог с клиентом. Если клиент не контактировал с ботом, то отправить ему что-либо в ответ не получится, пока клиент не активирует бота.


Викторина

Для создания викторины используется функция tg_send_quiz_poll():

tg_send_quiz_poll (platform_id, question, options, explanation, correct_option_id, is_anonymous, reply_markup, parse_mode, protect_content, disable_notification, token)
Обязательные параметры:
  • platform_id - id в Телеграм, куда нужно прислать сообщение
  • question - вопрос
  • options - массив вариантов ответов
  • explanation - текст, который отображается, когда пользователь выбирает неправильный ответ или нажимает на значок лампы в опросе в стиле викторины (до 200 символов и максимум 2 перевода строки)
  • correct_option_id - номер правильного ответа, нумерация с 1
Необязательные параметры:
  • is_anonymous - 1 - анонимный опрос, '' - не анонимный
  • reply_markup - кнопки сообщения или '' - без пользовательских кнопок
  • parse_mode - markdown или html или '' - без форматирования
  • protect_content - 1 защитить от копирования и скриншотов, '' - без защиты
  • disable_notification - 1 - отправить с уведомлением, '' - без уведомления
  • token - токен бота, если не передан используется текущий


Пример, код в калькуляторе:

options = ["белый", "красный", "синий", "зеленый"]
r = tg_send_quiz_poll(platform_id, 'Какого цвета крокодил?', options, 'Вот такое вот объяснение.', 4, '', '', '', '', 1)

Примечания

Колбек poll_answer, пользователь выбрал вариант 4
  1. Функция tg_send_quiz_poll() возвращает message_id, который лучше сохранить, так как с его помощью можно завершить викторину функцией tg_stop_poll() (описание ниже) и получить результат.
  2. Если викторина добавлена пользователем в канал, то в диалог придет колбек: poll_added текст_вопроса.
  3. Если викторина добавлена пользователем в чат, то в диалог придет колбек: poll_added user_id текст_вопроса.
  4. Если викторина добавлена ботом, колбек не приходит.
  5. В канале можно создавать только анонимные викторины.
  6. Если викторина была отправлена в диалог пользователя с ботом, то (при ответе пользователя) придет колбек с выбранными ответами: poll_answer 5325838371359031647 [3], нумерация ответов начинается с 0 (на скриншоте был выбран 4 ответ).
  7. Если не анонимная викторина была создана в чате (ботом или пользователем), в котором состоит бот, то на каждый голос будет отправлен вебхук, при получении которого, будет отправлен колбек poll_answer 5325838371359031647 [3]в диалог с клиентом. Если клиент не контактировал с ботом, то отправить ему что-либо в ответ не получится, пока клиент не активирует бота.


Завершение опроса

Чтобы завершить опрос или викторину, нужно вызвать функцию tg_stop_poll().

result = tg_stop_poll(platform_id, message_id)
  • platform_id - id в Телеграм, где находится викторина (ид пользователя, канала, группы)
  • message_id - id сообщения с опросом или викториной

После выполнения функции в переменную result запишется словарь, который можно распарсить используя функцию get().

Пример содержимого переменной result:

{'update_id': 787499908, 'poll': {'id': '5258177312003719338', 'question': 'Тут вопрос?', 'options': [{'text': 'Ответ 1', 'voter_count': 1}, {'text': 'Ответ 2', 'voter_count': 1}, {'text': 'Ответ 3', 'voter_count': 0}], 'total_voter_count': 2, 'is_closed': True, 'is_anonymous': True, 'type': 'regular', 'allows_multiple_answers': False}}

Получение полного вебхука Телеграм

Для получения полного вебхука от Телеграм достаточно присвоить любое значение переменной save_webhook (переменная может быть как константой проекта, так и переменной сделки).

Настройка получения вебхука Телеграм, объявление переменной save_webhook


При этом ответ Телеграм будет записываться в переменную tg_request, которую вы найдете в карточке клиента среди переменных сделки:

Переменная tg_request во вкладке Клиенты


Как при помощи tg_request получить ссылку на картинку/фото/анимацию/видео


Реализуем простую схему на получение файла:

  1. Присвойте любое значение переменной save_webhook (см. выше)
  2. Создайте блок с условием для запуска, в примере - хочуид
  3. Из первого блока создайте следующий, в котором выведем результат



В Телеграм:

  • напишите свое ключевое слово
  • отправьте файл, ссылку которого вы желаете получить:
Получение tg_request в Телеграм


Нас интересует последний file_id. Полученный file_id можно использовать в API-функциях отправки сообщений Телеграм.

Платежная система в Телеграм

API Telegram

Telegram API

Полезные ссылки

Видео: https://youtu.be/yP2ABDNfDZI - подключение канала «Телеграм»