Работа с идентификаторами платформы в MaviBot

В MaviBot все сущности Telegram (пользователи, группы, каналы) идентифицируются общей переменной platform_id. Эта переменная не различает типы сущностей.

Проблема: Чтобы использовать такие функции, как accept или reject, которые требуют определенных типов сущностей, необходимо знать отдельно как chat ID, так и user ID.

Решение: Когда вы получаете callback или сообщение, сразу сохраняйте значение platform_id в две отдельные переменные с понятными именами:

  • chat_id – для хранения ID группы/канала.
  • user_id – для хранения ID отдельного пользователя.

Это позволит вам ссылаться на правильный ID в дальнейшей логике приложения.

Как изменить название чата через бота Telegram

Описание

tg_set_group_title(platform_id, title)

Изменяет название группы Telegram.

Параметры

Параметр Описание
platform_id ID чата внутри Telegram.
title Новое название чата.
Параметр Описание
**!** platform_id ID чата внутри Telegram *
**!** title новое название чата

Как изменить описание чата через бота Telegram

Описание

tg_set_chat_description(platform_id, description)

Изменяет описание чата Telegram.

Параметры

Параметр Описание
platform_id ID чата внутри Telegram.
description Новое описание чата.
Параметр Описание
**!** platform_id ID чата внутри Telegram *
**!** description новое название чата

Как установить аватар в группе/чате Telegram

Описание

tg_set_chat_photo(platform_id, photo)

Устанавливает новое фото профиля для чата Telegram.

Параметры

Параметр Описание
platform_id ID чата внутри Telegram, в котором вы хотите установить новое фото профиля.
photo Прямая ссылка на фото.
Параметр Описание
**!** platform_id ID чата внутри Telegram *, в котором вы хотите установить аватар
**!** photo ссылка на фото

Как удалить аватар в группе/чате Telegram

Описание

tg_delete_chat_photo(platform_id)

Удаляет текущее фото профиля из чата Telegram.

Параметры

Параметр Описание
platform_id ID чата внутри Telegram, из которого вы хотите удалить фото профиля.
Параметр Описание
**!** platform_id ID чата внутри Telegram *, в котором нужно установить аватар

Как заблокировать группу Telegram

Описание

tg_ban_chat_sender_chat(platform_id, sender_chat_id)

Блокирует чат-отправитель от публикации сообщений в чате Telegram.

Параметры

Параметр Описание
platform_id ID чата Telegram, в котором будет заблокирован чат-отправитель.
sender_chat_id ID чата-отправителя для блокировки.

Примечание

После блокировки владелец чата-отправителя больше не сможет публиковать сообщения от имени этого чата в указанном чате Telegram до снятия блокировки.

Параметр Описание
**!** platform_id ID чата внутри Telegram *, который нужно заблокировать
**!** sender_chat_id ID чата, который будет заблокирован

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

Как разблокировать группу Telegram

Описание

tg_unban_chat_sender_chat(platform_id, sender_chat_id)

Разблокирует ранее заблокированный чат-отправитель в чате Telegram.

Параметры

Параметр Описание
platform_id ID чата Telegram, в котором будет разблокирован чат-отправитель.
sender_chat_id ID чата-отправителя для разблокировки.
Параметр Описание
**!** platform_id ID чата внутри Telegram *, в котором вы разблокируете
**!** sender_chat_id ID чата, который вы разблокируете

Как создать пригласительную ссылку для вступления в чат Telegram

Описание

Создает новую пригласительную ссылку для чата Telegram.

Параметры

Параметр Описание
platform_id ID чата Telegram.
member_limit Максимальное количество пользователей, которые могут присоединиться по этой пригласительной ссылке.
hours Время истечения срока действия пригласительной ссылки, в часах.
request Если установлено значение True, пользователи, перешедшие по ссылке, должны отправить запрос на вступление, который может одобрить администратор.
name Пользовательское название пригласительной ссылки.

Важно

Если указан параметр member_limit, параметр request автоматически устанавливается в False.

Чтобы пользователи отправляли запросы на вступление, оставьте параметр member_limit пустым.

Параметр Описание
**!** platform_id ID чата в Telegram *
member_limit ограничение на количество участников
hours Время истечения срока действия ссылки (в часах)
request параметр, при котором после перехода по ссылке должен создаваться запрос на вступление в чат.
name название ссылки

При передаче параметра member_limit значение параметра request автоматически изменяется на False. Если вам нужно принимать заявки на вступление, оставьте параметр member_limit пустым.

Создание пригласительной ссылки в чат

Как удалить пригласительную ссылку в чате Telegram

Описание

Отзывает существующую пригласительную ссылку для чата Telegram.

Параметры

Параметр Описание
platform_id ID чата Telegram.
invite_link Пригласительная ссылка для отзыва.
Параметр Описание
**!** platform_id ID чата внутри Telegram *
**!** invite_link ссылка, которую нужно удалить

Как деактивировать все существующие ссылки и заменить их одной ссылкой

Описание

Создает новую основную пригласительную ссылку для чата Telegram.

Параметры

Параметр Описание
platform_id ID чата Telegram.

Предупреждение

Этот метод генерирует новую основную пригласительную ссылку для чата.

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

Используйте этот метод с осторожностью.

Параметр Описание
**!** platform_id ID чата внутри Telegram *
**!** invite_link ссылка, которую нужно удалить

Как принять запрос и добавить пользователя в канал/чат Telegram

Описание

tg_approve_chat_join_request(chat_id, user_id)

Одобряет ожидающий запрос на вступление в группу или канал Telegram.

Параметры

Параметр Описание
chat_id ID группы или канала Telegram.
user_id ID пользователя Telegram, чей запрос на вступление должен быть одобрен.
**!** chat_id ID группы/канала внутри Telegram *
**!** user_id ID пользователя внутри Telegram *

Принятие запроса:

Как отклонить запрос в канале/чате Telegram

Описание

tg_decline_chat_join_request(chat_id, user_id)

Отклоняет ожидающий запрос на вступление в группу или канал Telegram.

Параметры

Параметр Описание
chat_id ID группы или канала Telegram.
user_id ID пользователя Telegram, чей запрос на вступление должен быть отклонен.
**!** chat_id ID группы/канала внутри Telegram *
**!** user_id ID пользователя внутри Telegram *

Как заблокировать пользователя в Telegram

Описание

tg_ban_chat_member(chat_id, user_id, hours)

Блокирует пользователя в чате Telegram.

Параметры

Параметр Описание
chat_id ID чата Telegram.
user_id ID пользователя Telegram для блокировки.
hours Продолжительность блокировки, в часах. Если не указано, блокировка постоянна.

Примечание

Если значение hours превышает 366 дней, пользователь будет заблокирован навсегда.

Параметр Описание
**!** chat_id ID чата в Telegram *
**!** user_id ID пользователя в Telegram * для блокировки
hours Длительность блокировки в часах. По умолчанию блокировка постоянная. Если указать длительность блокировки более 366 дней, блокировка будет установлена как постоянная.

Как разблокировать пользователя в Telegram

Описание

tg_unban_chat_member(chat_id, user_id)

Разблокирует пользователя в чате Telegram.

Параметры

Параметр Описание
chat_id ID чата Telegram.
user_id ID пользователя Telegram для разблокировки.
Параметр Описание
**!** chat_id ID чата в Telegram *
**!** user_id ID пользователя в Telegram *, которого нужно разблокировать

Как проверить статус подписки в Telegram

Описание

tg_get_chat_member(chat_id, user_id)

Получает информацию о статусе членства пользователя в чате Telegram.

Параметры

Параметр Описание
chat_id ID чата Telegram.
user_id ID пользователя Telegram, чей статус членства будет проверен.
Параметр Описание
**!** chat_id ID чата в Telegram *
**!** user_id ID пользователя в Telegram *, чью подписку мы проверяем

Как определить количество участников в канале/чате

Описание

tg_get_chat_member_count(platform_id)

Возвращает общее количество участников в чате Telegram.

Параметры

Параметр Описание
platform_id ID чата Telegram.
Параметр Описание
**!** platform_id ID чата в Telegram *

Как проверить, находится ли участник чата в определенном списке

some_client_in_list(list_id, recepient)

Проверяет, включен ли пользователь Telegram в указанный список.

Параметры

Параметр Описание
list_id ID списка для проверки.
recepient ID пользователя Telegram. Для участников чата используйте переменную chat_member_id.
Параметр Описание
**!** list_id номер списка
**!** recepient ID пользователя в Telegram *. Для клиентов чата это значение находится в переменной chat_member_id.

Как показать действия бота пользователю (печать/выбор стикера и т.д.)

Описание

tg_send_chat_action(platform_id, bot_action, message_thread_id)

Отправляет действие чата (например, набор текста или загрузку файла) в чат Telegram.

Параметры

Параметр Описание
platform_id ID чата Telegram.
bot_action Действие чата для отображения. Выберите одно из поддерживаемых действий чата Telegram.
message_thread_id ID темы. Доступно только для супергрупп с включенными темами (форумами).

Примечание

Эта функция поддерживается при работе с Telegram Business аккаунтами.

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** bot_action действие бота из списка
message_thread_id ID темы (доступно для супергрупп, если доступна функциональность форума).
**Список доступных действий bot_action**

typing для текстовых сообщений,
&#xNAN;upload_photo для фотографий,
&#xNAN;record_video или upload_video для видео,
&#xNAN;record_voice или upload_voice для голосовых сообщений,
&#xNAN;upload_document для обычных документов,
&#xNAN;choose_sticker для стикеров,
&#xNAN;find_location для данных о местоположении,
&#xNAN;record_video_note или upload_video_note для видеосообщений.

Это уведомление будет отображаться до получения любого ответа от бота, но не более 5 секунд.

Как показать пользователю Alert-уведомление

Описание

tg_answer_callback_query(callback_query_id, text, show_alert, cache_time)

Отправляет ответ на callback-запрос, который возникает при нажатии пользователем на инлайн-кнопку в Telegram.

Параметры

Параметр Описание
callback_query_id ID callback-запроса, полученный при нажатии пользователем на инлайн-кнопку. Определяет, на какой callback отвечать.
text Текст для отображения в уведомлении.
show_alert Управляет способом отображения уведомления. Установите False для показа временного уведомления в виде всплывающей подсказки или True для отображения постоянного диалогового окна с предупреждением.
cache_time Максимальное время в секундах, в течение которого ответ на callback может кэшироваться на стороне клиента. По умолчанию 0. Клиенты Telegram поддерживают кэширование, начиная с версии 3.14.

Важно

Эта функция может использоваться только в ответ на нажатие пользователем инлайн-кнопки с callback в Telegram.

Пример

Следующая инлайн-клавиатура отправляет разные значения callback при нажатии на каждую кнопку:

[{"line":0,"index_in_line":0,"text":"111","type":"inline","callback":"first"}, {"line":1,"index_in_line":0,"text":"222","type":"inline","callback":"second"}, {"line":2,"index_in_line":0,"text":"333","type":"inline","callback":"third"}]

После нажатия кнопки приходит callback с текстом, содержащимся в соответствующем поле. При нажатии на кнопку «111» вы получите callback с текстом «first».

Создадим блок Start и укажем нужный текст в триггере. В нашем случае: "first"

Если в поле Совпадения выбрать Игнорировать ошибки и неточности, этот блок можно будет в дальнейшем использовать повторно для всех похожих вариантов, отличающихся на 1–2 символа. Например, чтобы поблагодарить пользователя за оценку с помощью такой кнопки.

Далее в калькуляторе используйте функцию tg_answer_callback_query и передайте следующие параметры:
callback_query_id - этот ID позволяет идентифицировать пользователя, нажавшего кнопку, и показать ему Alert-уведомление
text - текст Alert-уведомления.

Пример кода для копирования:

tg_answer_callback_query('#{callback_query_id}', "Вы нажали кнопку 111")

Обратите внимание! Параметр callback_query_id следует передавать точно так, как показано в примере, т.е. внутри '#{}'

Если всё настроено правильно, при нажатии кнопки появится Alert-уведомление с указанным текстом. В мобильной версии в качестве заголовка над текстом будет отображаться имя бота.

Если вы хотите показать простое всплывающее сообщение, передайте False в качестве третьего параметра, как показано в примере ниже:
tg_answer_callback_query('#{callback_query_id}', "Вы нажали кнопку 222", False)

Добавление перенаправления на бота с тегом в качестве ответа на callback-кнопку

Описание

tg_callback_url_open(callback_query_id, url, cache_time)

Открывает бота Telegram с помощью глубокой ссылки в ответ на callback инлайн-кнопки.

Параметры

Параметр Описание
callback_query_id ID callback-запроса, полученный при нажатии пользователем на инлайн-кнопку. Определяет, на какой callback отвечать.
url Глубокая ссылка на бота в формате https://t.me/your_bot?start=XXXX, где your_bot — имя пользователя бота, а XXXX — параметр start.
cache_time Максимальное время в секундах, в течение которого ответ на callback может кэшироваться на стороне клиента. По умолчанию 0. Клиенты Telegram поддерживают кэширование, начиная с версии 3.14.

Важно

Эта функция может использоваться только в ответ на нажатие пользователем инлайн-кнопки с callback в Telegram.

Пример

В ответе на callback-кнопку можно добавить переход на бота с помощью тега tg_callback_url_open('#{callback_query_id}', 't.me/bot_name?start=XXXX')

Например, используем следующие кнопки:

[{"line":0,"index_in_line":0,"text":"111","type":"inline","callback":"first"}, {"line":1,"index_in_line":0,"text":"222","type":"inline","callback":"second"}, {"line":2,"index_in_line":0,"text":"333","type":"inline","callback":"third"}]

После нажатия кнопки приходит callback с текстом, содержащимся в соответствующем поле. При нажатии на кнопку «111» вы получите callback с текстом «first».

Создайте блок с проверкой основного условия и укажите нужный текст в условии. В нашем случае: «first»:

Если в поле Вариант сопоставления выбрать Игнорировать ошибки и неточности, этот блок можно будет в дальнейшем использовать повторно для всех похожих вариантов, отличающихся на 1–2 символа. Например, чтобы поблагодарить пользователя за оценку с помощью такой кнопки.

Далее в калькуляторе блока укажите tg_callback_url_open('#{callback_query_id}', 't.me/bot_name?start=XXXX'):

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

Описание

tg_promote_user(platform_id, user_id, promote_options_list)

Повышает пользователя Telegram до администратора в супергруппе или канале с указанными разрешениями.

Параметры

Параметр Описание
platform_id Идентификатор супергруппы Telegram или имя пользователя канала в формате @channelusername при повышении пользователя в канале.
user_id Идентификатор пользователя Telegram, которого нужно повысить.
promote_options_list Список разрешений администратора, которые нужно предоставить пользователю.

Примечание

Пользователю будут предоставлены только те разрешения, которые включены в promote_options_list.

**Обязательный параметр: promote_options_list**

В promote_options_list можно указать следующие разрешения:

  1. is_anonymous — скрывает присутствие администратора в чате,
  2. can_manage_chat — администратор может просматривать журнал событий чата, статистику чата, статистику сообщений в каналах, просматривать участников канала, просматривать анонимных администраторов в супергруппах и обходить медленный режим. Этот уровень разрешения предоставляется по умолчанию, если указаны какие-либо из следующих привилегий.
  3. can_post_messages — администратор может создавать публикации в канале (только для каналов)
  4. can_edit_messages — администратор может редактировать сообщения других пользователей и закреплять сообщения (только для каналов)
  5. can_delete_messages — администратор может удалять сообщения других пользователей
  6. can_manage_video_chats — администратор может управлять видеозвонками,
  7. can_restrict_members — администратор может ограничивать участников, блокировать/разблокировать их в чате,
  8. can_promote_members — администратор может назначать новых администраторов с подмножеством своих собственных привилегий или понижать в должности администраторов, которых он назначил прямо или косвенно (например, администраторов, назначенных им)
  9. can_change_info — администратор может изменять название чата, фото и другие настройки
  10. can_invite_users — администратор может приглашать новых пользователей в чат
  11. can_pin_messages — администратор может закреплять сообщения (только для супергрупп).
Пример

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

В этом примере, помимо указанных разрешений, разрешение can_manage_chat будет предоставлено по умолчанию.

Пример кода для копирования

Пример 1. 
promote_options_list = '[“can_promote_members”,”can_change_info”,”can_invite_users”]' 
tg_promote_user(platform_id, user_id, promote_options_list)

Пример 2. 
promote_options_list = '["can_manage_chat","can_post_messages","can_edit_messages","can_delete_messages","can_manage_video_chats","can_promote_members","can_restrict_members","can_invite_users","can_pin_messages"]' 
result=tg_promote_user(platform_id, reply_from, promote_options_list)  

Как изменить название должности администратора с помощью бота в Telegram

Описание

tg_set_administrator_title(platform_id, user_id, title)

Устанавливает пользовательское название должности для администратора супергруппы Telegram.

Параметры

Параметр Описание
platform_id Идентификатор супергруппы Telegram.
user_id Идентификатор пользователя Telegram, являющегося администратором.
title Пользовательское название должности администратора.

Важно

  • Название должно содержать от 0 до 16 символов.
  • Эмодзи не допускаются в названии.
  • Эта функция работает только для администраторов, которые были повышены ботом.

Пример

result = tg_set_administrator_title(platform_id, reply_from, "firetitle")

Общие ограничения для обычных участников чата или конкретных пользователей Telegram

Описание

tg_chat_permission(platform_id, permission, media_permissions)

Устанавливает разрешения по умолчанию для участников чата Telegram.

Параметры

Параметр Описание
platform_id Идентификатор чата Telegram.
permission Массив общих разрешений чата. Каждый элемент соответствует разрешению из списка поддерживаемых разрешений. Используйте 1, чтобы разрешить действие, и 0, чтобы запретить его.
media_permissions Массив разрешений, связанных с медиа. Каждый элемент соответствует разрешению из списка поддерживаемых медиа-разрешений. Используйте 1, чтобы разрешить действие, и 0, чтобы запретить его.

Примечание

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

  • 1 — Разрешение предоставлено.
  • 0 — Разрешение запрещено.
Список ограничений для обязательного параметра **permission**

Список ограничений для permission:

  1. ! can_send_messages - разрешение на отправку текстовых сообщений, контактов, местоположений и мест.
  2. ! can_send_media_messages - разрешение на отправку аудио, документов, фотографий, видео, видеозаметок и голосовых заметок. Требует can_send_messages
  3. ! can_send_polls - разрешение на отправку опросов. Требует can_send_messages
  4. ! can_send_other_messages - разрешение на отправку анимаций, игр, стикеров и использование встроенных ботов. Требует can_send_media_messages
  5. ! can_add_web_page_previews - разрешение на добавление предварительных просмотров веб-страниц в сообщения. Требует can_send_media_messages
  6. ! can_change_info - разрешение на изменение названия чата, фото и других настроек. Игнорируется в публичных супергруппах.
  7. ! can_invite_users - разрешение на приглашение пользователей
  8. ! can_pin_messages - разрешение на закрепление сообщений. Игнорируется в публичных супергруппах.
  9. can_manage_topics - разрешение на создание тем в форумных группах. Если используется в группе неправильного типа, функция завершится ошибкой и вернет ошибку.
Список значений для обязательного параметра **media_permissions**

Значения для предоставления разрешений, связанных с медиа media_permissions:

  1. can_send_audios - разрешение на отправку аудиофайлов
  2. can_send_documents - разрешение на отправку документов
  3. can_send_photos - разрешение на отправку фотографий
  4. can_send_videos - разрешение на отправку видео
  5. can_send_video_notes - разрешение на отправку круглых видеосообщений
  6. can_send_voice_notes - разрешение на отправку голосовых сообщений

Персональные ограничения Telegram для обычных пользователей чата или для конкретных пользователей Telegram

Описание

tg_restrict_chat_member(platform_id, user_id, minutes, permission, media_permissions).

Параметры:

Параметр Описание
! platform_id Идентификатор чата в Telegram *
! user_id Идентификатор пользователя в Telegram *
minutes Количество минут, в течение которых будет действовать ограничение. Если не задать значение, по умолчанию используется 3600, что равно 60 часам. Если установить значение 0, ограничение становится постоянным.
permission Массив значений из списка ограничений разрешений.
media_permissions Список значений для предоставления разрешений, связанных с медиа.
Список ограничений для обязательного параметра **permission**

Список ограничений для permission:

  1. ! can_send_messages - разрешение на отправку текстовых сообщений, контактов, местоположений и мест.
  2. ! can_send_media_messages - разрешение на отправку аудио, документов, фотографий, видео, видеозаметок и голосовых заметок. Требует can_send_messages
  3. ! can_send_polls - разрешение на отправку опросов. Требует can_send_messages
  4. ! can_send_other_messages - разрешение на отправку анимаций, игр, стикеров и использование встроенных ботов. Требует can_send_media_messages
  5. ! can_add_web_page_previews - разрешение на добавление предварительных просмотров веб-страниц в сообщения. Требует can_send_media_messages
  6. ! can_change_info - разрешение на изменение названия чата, фото и других настроек. Игнорируется в публичных супергруппах.
  7. ! can_invite_users - разрешение на приглашение пользователей
  8. ! can_pin_messages - разрешение на закрепление сообщений. Игнорируется в публичных супергруппах.
  9. can_manage_topics - разрешение на создание тем в форумных группах. Если используется в группе неправильного типа, функция завершится ошибкой и вернет ошибку.
Список значений для обязательного параметра **media_permissions**

Значения для предоставления разрешений, связанных с медиа media_permissions:

  1. can_send_audios - разрешение на отправку аудиофайлов
  2. can_send_documents - разрешение на отправку документов
  3. can_send_photos - разрешение на отправку фотографий
  4. can_send_videos - разрешение на отправку видео
  5. can_send_video_notes - разрешение на отправку круглых видеосообщений
  6. can_send_voice_notes - разрешение на отправку голосовых сообщений
Пример

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

Когда пользователь заходит в чат, он увидит уведомление о том, что не может отправлять сообщения в чате.
Если установлен лимит времени, он также увидит продолжительность этого ограничения.

Пример кода для копирования:

permission = [0, 0, 0, 0, 0, 0, 0, 0] 
tg_restrict_chat_member(-1001607137668, 473737685, 3, permission)

Как закрепить сообщение

Описание

tg_pin_chat_message(platform_id, message_id, disable_notification)

Закрепляет сообщение в чате Telegram.

Параметры

Параметр Описание
platform_id ID чата Telegram.
message_id ID сообщения для закрепления.
disable_notification Управляет уведомлением участников чата о закрепленном сообщении. Установите 1 для тихого закрепления или 0 для отправки уведомления.

Примечание

Уведомления всегда отключены в каналах и личных чатах, независимо от значения disable_notification.

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

Описание

tg_unpin_chat_message(platform_id, message_id)

Открепляет сообщение в чате Telegram.

Параметры

Параметр Описание
platform_id ID чата Telegram.
message_id ID сообщения для открепления. Если опущен, открепляется последнее закрепленное сообщение.

Примечание

Если message_id не указан, функция открепляет последнее закрепленное сообщение на основе времени его отправки.

Как открепить все закрепленные сообщения

Описание

tg_unpin_all(platform_id)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *

ВНИМАНИЕ!

В Telegram есть ограничение на функции закрепления/открепления сообщений.

Временные лимиты для использования **tg_pin_chat_message / tg_unpin_chat_message / tg_unpin_all **НЕ устанавливаются системой MaviBot.

Если допустимое время для закрепления сообщения истекло, функция все равно вернет true, но Telegram не применит изменение.

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

Как создать опрос в Telegram

Описание

tg_send_poll(platform_id, question, options, is_anonymous, allows_multiple_answers, reply_markup, disable_notification, protect_content, token, reply_to_message_id, message_thread_id, business_connection_id)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** question вопрос
**!** options массив вариантов ответа
is_anonymous 1 - анонимный опрос , '' - не анонимный
allows_multiple_answers 1 - доступно несколько ответов, '' - один ответ
reply_markup клавиатура или '' - без клавиатуры
disable_notification флаг отправки со звуковым уведомлением (по умолчанию 0)
1 – отключить уведомление о получении, 0 – отправить с уведомлением
protect_content 1 для защиты от копирования и скриншотов, '' без защиты
token токен бота; если не указан, используется текущий
reply_to_message_id ID цитируемого сообщения
message_thread_id ID темы (доступно для супергрупп, если существует функционал форума)
business_connection_id значение при подключении бота (Business ID). Отображается в каналах. Должен быть указан, если используется токен бота и сообщение должно быть отправлено через учетную запись пользователя, подключенную к боту
Важно знать!

Примечания

  1. Функция возвращает ответ от Telegram с message_id. Лучше его сохранить. Используя message_id, вы можете остановить опрос с помощью tg_stop_poll (см. описание ниже) и получить результат.

  2. Если пользователь добавляет опрос в мессенджере, в чат отправляется колбек:

poll_added - неизменная часть
YOUR QUESTION - текст вопроса из опроса

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

Пример колбека при добавлении опроса в чат

Второй колбек после poll_added содержит цифры - это не что иное, как идентификатор пользователя в Telegram, который добавил опрос.

При создании опроса ботом колбек не приходит.

3. В канале можно создавать только анонимные опросы

Внимание, рекомендуется отправлять в группу только анонимные опросы!

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

Обратная связь от клиентов — ключ к нашему росту. Опросы предлагают простой способ получить эту обратную связь и преобразовать ее в конкретные бизнес-выводы.

Пример кода для копирования:

/* Example of creating a simple poll */
options = ["white", "red", "blue", "green"]
poll1 = tg_send_poll(platform_id, 'What is your favorite color?', options, 1, '', '', 1, '')

Функция для создания опроса в Telegram:

Созданный нами опрос в Telegram

Как создать викторину в Telegram

Описание

tg_send_quiz_poll(platform_id, question, options, explanation, correct_option_id, is_anonymous, reply_markup, parse_mode, protect_content, disable_notification, token, reply_to_message_id, message_thread_id )

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** question вопрос
**!** options массив вариантов ответа
**!** explanation текст, отображаемый, когда пользователь выбирает неправильный ответ или нажимает на значок лампочки в опросе-викторине, 0–200 символов, не более двух разрывов строк после разбора сущностей.
**!** correct_option_id номер правильного ответа, нумерация с 1
is_anonymous 1 - анонимный опрос , '' - не анонимный
reply_markup клавиатура или '' - без клавиатуры
parse_mode формат объяснения: markdown, html или '' (пустая строка для форматирования)
protect_content 1 для защиты от копирования и скриншотов, '' без защиты
disable_notification флаг отправки со звуковым уведомлением (по умолчанию 0)
1 – отключить уведомление о получении, 0 – отправить с уведомлением
token токен бота; если не указан, используется текущий
reply_to_message_id ID цитируемого сообщения
message_thread_id ID темы (доступно в супергруппах с активными функциями форума)
**Важно знать!**

Примечания

1. Сохраните message_id

Функция API возвращает ответ Telegram, содержащий message_id. Всегда сохраняйте этот ID, так как он необходим для:

  • Завершения викторины с помощью функции tg_stop_poll (см. описание ниже).
  • Получения окончательных результатов.

2. Колбек poll_added

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

  • Формат: poll_added + Вопрос опроса
  • Если добавлено в групповой чат: колбек также включает ID пользователя Telegram, который добавил опрос.

Если создано ботом: Колбек poll_added не отправляется.

3. Ограничение канала

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

4. Колбек poll_answer (Голосование пользователя)

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

  • Формат: poll_answer + ID опроса + [Индекс ответа]
  • Пример: poll_answer 5325838371359031648 [3]
  • Примечание: нумерация ответов начинается с 0. [3] означает, что пользователь выбрал четвертый вариант ответа.

5. Вебхук для неанонимных групповых опросов

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

6. Требование активации и лучшая практика

  • Требование: бот не может инициировать разговор. Если клиент никогда не связывался с ботом, вы не можете отправить ему прямое сообщение в ответ на его голос, пока он сначала не активирует бота (например, отправив команду /start).

Рекомендация: чтобы избежать этого ограничения, настоятельно рекомендуется отправлять в группы только анонимные викторины.

7. Отслеживайте свои опросы

Сразу после создания викторины сохраните ее уникальный ID опроса в переменную. Это позволит вам определить, к какому конкретному опросу относится входящий колбек.

Пример

Пример кода для копирования.

options = ["white", "red", "blue", "green"] 
r = tg_send_quiz_poll(platform_id, "What color is a crocodile?", options, "That is the explanation", 4, '', '', '', '', 1)

Пример: создание викторины.

Как завершить опрос

Описание

tg_stop_poll(platform_id, message_id)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** message_id ID сообщения опроса/викторины. Его можно получить из вебхука

Вызов этой функции для завершения опроса/викторины возвращает словарь, содержащий окончательные результаты.

Как работать с темами в Telegram

Важно: основная тема группы не имеет ID и требует отдельных функций для работы с ней.

Как переименовать общую тему группы

Описание

tg_edit_general_forum_topic(platform_id, topic_name)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** topic_name новое название темы
bot_name

необязательный параметр: имя бота.

При работе с темами вы можете указать, какой бот должен выполнять функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе "Каналы", в поле "ID группы".

Пример

Общую тему группы можно изменить с помощью функции tg_edit_general_forum_topic(). Она требует два обязательных параметра: ID чата и новое название для темы группы:

Пример кода для копирования

/переименовать чат общей темы/
answer = tg_edit_general_forum_topic(-1001839380031, 'General')

Как закрыть общую тему

Описание

tg_close_general_forum_topic(platform_id)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
bot_name

необязательный параметр: имя бота.

При работе с темами можно указать, какой бот должен выполнить функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе «Каналы», в поле «ID группы».

Пример кода для копирования

/закрыть чат общей темы/
answer = tg_close_general_forum_topic(-1001839380031)

Как повторно открыть ранее закрытую общую тему

Описание

tg_reopen_general_forum_topic(platform_id)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
bot_name

необязательный параметр: имя бота.

При работе с темами можно указать, какой бот должен выполнить функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе «Каналы», в поле «ID группы».

Пример кода для копирования

/повторно открыть чат общей темы/
answer = tg_reopen_general_forum_topic(-1001839380031)

Как скрыть общую тему

Описание

tg_hide_general_forum_topic(platform_id)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
bot_name

необязательный параметр: имя бота.

При работе с темами можно указать, какой бот должен выполнить функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе «Каналы», в поле «ID группы».

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

Пример кода для копирования

/скрыть чат общей темы/
answer = tg_hide_general_forum_topic(-1001839380031)

Как отобразить общую тему или восстановить её видимость

Описание

tg_unhide_general_forum_topic(platform_id)

Параметры:

Параметр Описание
**!** platform_id ID темы в Telegram *
bot_name

необязательный параметр: имя бота.

При работе с темами можно указать, какой бот должен выполнить функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе «Каналы», в поле «ID группы».

Важно!

Эта функция не открывает общую тему повторно; она только делает её видимой.

Пример кода для копирования

/отобразить чат общей темы/
answer = tg_unhide_general_forum_topic(-1001839380031)

Как создать новую тему в Telegram

Описание

tg_create_forum_topic(platform_id, name, icon, icon_color)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** name новое название темы
icon ID эмодзи, который будет установлен для темы. Передаётся в виде строки. Можно использовать только эмодзи из списка, полученного с помощью функции tg_get_forum_icon.
icon_color цвет эмодзи из списка: 7322096, 16766590, 13338331, 9367192, 16749490, 16478047. Не все эмодзи поддерживают изменение цвета.
bot_name

необязательный параметр: имя бота.

При работе с темами можно указать, какой бот должен выполнить функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе «Каналы», в поле «ID группы».

Установленный цвет нельзя изменить; цвет можно назначить только при создании темы.

При выполнении функция вернёт ответ, содержащий параметры новой темы, включая ID темы (необходим для различных функций).

Пример кода для копирования

Чтобы создать дополнительный чат темы
answer = tg_create_forum_topic(-1001839380031, 'second_bot_topic', None, 7322096)

Чтобы сохранить ID созданного дополнительного чата темы
answer={"ok":true,"result":{"message_thread_id":254,"name":"second_bot_topic","icon_color":7322096}}/
idtema1=answer['result']['message_thread_id']

Как редактировать тему. Как переименовать и/или изменить эмодзи для темы

Описание

tg_edit_forum_topic(platform_id, message_thread_id, name, icon)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** message_thread_id ID дополнительного чата темы
name новое название темы
icon ID эмодзи, который будет установлен для темы. Передаётся в виде строки. Можно использовать только эмодзи из списка, полученного с помощью функции tg_get_forum_icon.
bot_name

необязательный параметр: имя бота.

При работе с темами можно указать, какой бот должен выполнить функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе «Каналы», в поле «ID группы».

Пример кода для копирования

answer = tg_edit_forum_topic(-1001839380031, 254)

Как закрыть выбранную тему

Описание

Закрытие темы означает, что она становится доступной только для чтения; писать в закрытой теме запрещено.

tg_close_forum_topic(platform_id, message_thread_id)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** message_thread_id ID дополнительного чата темы
bot_name

необязательный параметр: имя бота.

При работе с темами можно указать, какой бот должен выполнить функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе «Каналы», в поле «ID группы».

Пример кода для копирования

answer = tg_close_forum_topic(-1001839380031, 254)

Как повторно открыть ранее закрытую тему

Описание

tg_reopen_forum_topic(platform_id, message_thread_id)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** message_thread_id ID дополнительного чата темы
bot_name

необязательный параметр: имя бота.

При работе с темами можно указать, какой бот должен выполнить функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе «Каналы», в поле «ID группы».

Пример кода для копирования

answer = tg_reopen_forum_topic(-1001839380031, 254)

Как удалить тему и все её сообщения

Описание

tg_delete_forum_topic(platform_id, message_thread_id)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** message_thread_id ID дополнительного чата темы
bot_name

необязательный параметр: имя бота.

При работе с темами можно указать, какой бот должен выполнить функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе «Каналы», в поле «ID группы».

Пример кода для копирования

answer = tg_delete_forum_topic(-1001839380031, 254)

Как открепить все сообщения в теме

Описание

tg_unpin_topic_messages(platform_id, message_thread_id)

Параметры:

Параметр Описание
**!** platform_id ID чата в Telegram *
**!** message_thread_id ID дополнительного чата темы
bot_name

необязательный параметр: имя бота.

При работе с темами можно указать, какой бот должен выполнить функцию. Это полезно, если в вашем проекте используется несколько ботов Telegram. Имя бота можно найти в разделе «Каналы», в поле «ID группы».

Пример кода для копирования

answer = tg_unpin_topic_messages(-1001839380031, 254)

Как получить список эмодзи для темы Telegram

Описание

Как получить список эмодзи

tg_get_forum_icon() – эта функция возвращает список эмодзи, доступных для использования в качестве иконок тем форума. Результат необходимо присвоить переменной, так как функция возвращает словарь, где каждый ключ — это эмодзи, а соответствующее ему значение — уникальный идентификатор эмодзи (id).

Параметры: отсутствуют.

Содержимое списка эмодзи

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

Функция вернет список эмодзи в своем ответе. Это означает, что переменная answer будет содержать словарь в качестве своего значения.

{'📰': '5434144690511290129', '💡': '5312536423851630001', '⚡️': '5312016608254762256', '🎙': '5377544228505134960', '🔝': '5418085807791545980', '🗣': '5368697802761185083', '🆒': '5420216386448270341', '❗️': '5379748062124056162', '📝': '5357193964787081133', '📆': '5433614043006903194', '📁': '5357315181649076022', '🔎': '5309965701241379366', '📣': '5309984423003823246', '🔥': '5312241539987020022', '❤️': '5312138559556164615', '❓': '5377316857231450742', '📈': '5350305691942788490', '📉': '5350713563512052787', '💎': '5309958691854754293', '💰': '5350452584119279096', '💸': '5309929258443874898', '\U0001fa99': '5377690785674175481', '💱': '5310107765874632305', '⁉️': '5377438129928020693', '🎮': '5309950797704865693', '💻': '5350554349074391003', '📱': '5409357944619802453', '🚗': '5312322066328853156', '🏠': '5312486108309757006', '💘': '5310029292527164639', '🎉': '5310228579009699834', '‼️': '5377498341074542641', '🏆': '5312315739842026755', '🏁': '5408906741125490282', '🎬': '5368653135101310687', '🎵': '5310045076531978942', '🔞': '5420331611830886484', '📚': '5350481781306958339', '👑': '5357107601584693888', '⚽️': '5375159220280762629', '🏀': '5384327463629233871', '📺': '5350513667144163474', '👀': '5357121491508928442', '\U0001fae6': '5357185426392096577', '🍓': '5310157398516703416', '💄': '5310262535021142850', '👠': '5368741306484925109', '✈️': '5348436127038579546', '\U0001f9f3': '5357120306097956843', '🏖': '5310303848311562896', '⛅️': '5350424168615649565', '🦄': '5413625003218313783', '🛍': '5350699789551935589', '👜': '5377478880577724584', '🛒': '5431492767249342908', '🚂': '5350497316203668441', '🛥': '5350422527938141909', '🏔': '5418196338774907917', '🏕': '5350648297189023928', '🤖': '5309832892262654231', '\U0001faa9': '5350751634102166060', '🎟': '5377624166436445368', '🏴\u200d☠️': '5386395194029515402', '🗳': '5350387571199319521', '🎓': '5357419403325481346', '🔭': '5368585403467048206', '🔬': '5377580546748588396', '🎶': '5377317729109811382', '🎤': '5382003830487523366', '🕺': '5357298525765902091', '💃': '5357370526597653193', '\U0001fa96': '5357188789351490453', '💼': '5348227245599105972', '\U0001f9ea': '5411138633765757782', '👨\u200d👩\u200d👧\u200d👦': '5386435923204382258', '👶': '5377675010259297233', '🤰': '5386609083400856174', '💅': '5368808634392257474', '🏛': '5350548830041415279', '\U0001f9ee': '5355127101970194557', '🖨': '5386379624773066504', '👮\u200d♂️': '5377494501373780436', '\U0001fa7a': '5350307998340226571', '💊': '5310094636159607472', '💉': '5310139157790596888', '\U0001f9fc': '5377468357907849200', '\U0001faaa': '5418115271267197333', '🛃': '5370947704199323325', '🍽': '5350344462612570293', '🐟': '5384574037701696503', '🎨': '5310039132297242441', '🎭': '5350658016700013471', '🎩': '5357504778685392027', '🔮': '5350367161514732241', '🍹': '5350520238444126134', '🎂': '5310132165583840589', '☕️': '5350392020785437399', '🍣': '5350406176997646350', '🍔': '5350403544182694064', '🍕': '5350444672789519765', '\U0001f9a0': '5312424913615723286', '💬': '5417915203100613993', '🎄': '5312054580060625569', '🎃': '5309744892677727325'}

Пример кода для копирования
answer = tg_get_forum_icon()