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

функции API существенно расширяют возможности работы бота в Telegram

Содержание:

Функции отправки и редактирования сообщений

• Отправить сообщение в Telegram tg_send_message()

• Отправить сообщение с указанием конкретного бота в Telegram tg_send_message_1()

• Редактирование текст сообщения tg_edit_message_text()

• Редактирование текст описания tg_edit_message_caption()

• Редактирование медиавложения в сообщении tg_edit_message_media()

• Редактирование инлайн-клавиатуры в сообщении tg_edit_message_reply_markup()

• Копировать сообщения в Telegram tg_copy_message()

• Переслать сообщение в Telegram tg_forward_message()

• Удалить сообщение в Telegramtg_delete_message()

Функции отправки вложений в сообщении

• Отправить документ tg_send_document() / несколько документов tg_send_some_document() или другие файлы

• Отправить голосовое сообщение tg_send_voice() / несколько аудиосообщений tg_send_some_audio()

• Отправить анимацию tg_send_animation()

• Отправить видео tg_send_video()/ несколько видео tg_send_some_video()

• Отправить геоточку tg_send_venue()

• Отправить контакт tg_send_contact()

• Отправить стикер tg_send_sticker()

• Отправить круглое видео tg_send_video_note()

• Отправить картинку tg_send_photo() / несколько картинок tg_send_some_photo()

• Отправить эмодзи со случайным выбором (Dice) tg_send_dice()

Функции для работы в чатах и каналах

Изменить настройки чата/канала Telegram

• поменять имя чата через бот в Telegram tg_set_group_title()

• поменять описание чата через бот в Telegram tg_set_chat_description()

• установить аватарку на группу/чат в Telegram tg_set_chat_photo()

• удалить аватарку группы/чата в Telegram tg_delete_chat_photo()

Забанить/разбанить группу Telegram

• забанить группу Telegram tg_ban_chat_sender_chat()

• разбанить группу Telegram tg_unban_chat_sender_chat()

Функции работы с ссылками на чат/канал Telegram

• создать ссылку на вступление в чат в Telegram tg_create_chat_invite_link()

• удалить ссылку на вступление в чат в Telegram tg_revoke_chat_invite_link()

• сделать неактивными все существующие ссылки и заменить их на одну tg_export_chat_link()

ССЫЛКА НА ПЕРВОИСТОЧНИК ИНФОРМАЦИИ:

https://core.telegram.org/bots/api

ОБОЗНАЧЕНИЯ:

! - Обязательные параметры

параметр=None - так указывается значение по умолчанию для обозначенного параметра, т.е. неправильно просто копировать текст функции из документации tg_send_message(platform_id, "Какой то текст", client_message_id=61818138, reply_markup=None, parse_mode=None, disable_web_page_preview=0, protect_content=False) После знаков равно указаны значения по умолчанию для каждого параметра, следовательно, если Вам не нужен тот или иной параметр, но нужен какой-либо из последующих, то нельзя просто опустить его - следует указать вместо него значение по умолчанию для данного параметра. Таким образом, правильным будет ввод: tg_send_message(platform_id, "Какой то текст", 61818138, None, None, 0, True)

ОБЩАЯ ИНФОРМАЦИЯ:

* Где взять platform_id для отправки уведомлений

• У вас должен быть подключен телерам-бот к проекту

• В этого бота нужно прислать любое сообщение с того Telegram-аккаунта, куда должны приходить сообщения

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

• Копируете значение ID в мессенджере

  

** Как прописывать кнопки в параметре reply_markup

Пример reply-кнопок:

opts = {"keyboard": [[{"text": "Налево"}, {"text": "Направо"}]]}

Пример inline-кнопок:

opts = {"inline_keyboard": [[{"text": "Пакет 1","callback_data":1}, {"text": "Пакет 2","callback_data":2}]]}

*** Как использовать разметку текста (markdown) в параметре parse_mode

parse_mode выделяет весь текст/его часть курсивом или жирным шрифтом. Может иметь значения html, markdown, markdownV2.

Если выбираете html:

для жирного шрифта используете "<b>caption</b>"

для курсива "<i>caption</i>"

Для Markdown:

для жирного шрифта используете "*caption*"

для курсива "_caption_"

Пример отправки курсивного текста: tg_send_message(47615196, "<i>курсив</i>",None,None,"html")

Пример отправки жирного текста: tg_send_message(platform_id, '*test*', None, None, 'markdown')

Как работать с описанием бота Telegram (полное,краткое)

tg_set_bot_description()

tg_set_bot_short_description()

tg_get_bot_description()

tg_get_bot_short_description()

Описание

Установка приветственного сообщения

tg_set_bot_description(description, language_code) - описание бота, показываемое когда чат с ботом пуст

Параметры:

description — описание бота, если передать пустую строку, то это удалит соответствующее описание

language_code - двухбуквенный код языка по стандарту ISO 639-1, для локализации текста. Если пусто, краткое описание будет применяться ко всем пользователям, для которых нет специального краткого описания.

Установка описания для превью ссылки

tg_set_bot_short_description(description, language_code) - краткое описание бота, которое отображается на странице профиля бота и отправляется вместе со ссылкой, когда пользователи делятся ботом.

Параметры:

description — описание бота, если передать пустую строку, то это удалит соответствующее описание

language_code - двухбуквенный код языка по стандарту ISO 639-1, для локализации текста. Если пусто, краткое описание будет применяться ко всем пользователям, для которых нет специального краткого описания.

Получение текущего описания

tg_get_bot_description(language_code) - Используйте этот метод, чтобы получить текущее описание бота для данного пользовательского языка

Параметры:

language_code - двухбуквенный код языка по стандарту ISO 639-1, для локализации текста. Если пусто, краткое описание будет применяться ко всем пользователям, для которых нет специального краткого описания.

Получение текущего краткого описания

tg_get_bot_short_description(language_code) - Используйте этот метод, чтобы получить текущее краткое описание бота для данного пользовательского языка

Параметры:

language_code - двухбуквенный код языка по стандарту ISO 639-1, для локализации текста. Если пусто, краткое описание будет применяться ко всем пользователям, для которых нет специального краткого описания.

Пример

Пример установки приветсвенного сообщения и меню бота:

Настройка блока в Salebot

После запуска (проводите это единожды по команде администратора):

Приветсвенное сообщение и меню бота

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

tg_set_bot_description('Добро пожаловать! Я ваш виртуальный помощник Юрграм.🤖') command = [["private_office", "Личный кабинет"]] tg_set_command(command, '', 'default')

Как работать с чатами/каналами Telegram

Так как внутри Salebot идентификаторы клиентов (пользователей, групп, каналов) внутри мессенджера записываются в переменной platform_id без каких-либо меток чему это принадлежит группе или пользователю, то для работы с функциями принятия/отклонения заявки требуется единожды запомнить значения platform_id чата и platform_id пользователя в переменные с разными именами, например, chat_id и user_id.

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

tg_set_group_title()

tg_set_chat_description()

tg_set_chat_photo()

tg_delete_chat_photo()

Описание

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

tg_set_group_title(platform_id, title)

Параметры:

! platform_id — идентификатор чата внутри Telegram * ! title — новое название чата

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

tg_set_chat_description(platform_id, description)

Параметры: ! platform_id — идентификатор чата внутри Telegram * ! description — новое описание чата

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

tg_set_chat_photo(platform_id, photo), где platform_id — идентификатор чата, в котором Вы хотите установить аватарку, photo — ссылка на фото.

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

tg_delete_chat_photo(platform_id)

Параметры: ! platform_id — идентификатор чата внутри Telegram *

Пример

Создание ссылки на вступление в чат:

Как забанить/разбанить группу Telegram

tg_ban_chat_sender_chat()

tg_unban_chat_sender_chat

Описание

Как забанить группу Telegram

tg_ban_chat_sender_chat(platform_id, sender_chat_id)

Параметры: ! platform_id - идентификатор чата, в котором баним ! sender_chat_id - идентификатор чата, который баним

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

Как разбанить группу Telegram

tg_unban_chat_sender_chat(platform_id, sender_chat_id)

Параметры: ! platform_id - идентификатор чата, в котором разбаниваем ! sender_chat_id - идентификатор чата, который разбаниваем

Как работать с ссылками на чат/канал Telegram

tg_create_chat_invite_link()

tg_revoke_chat_invite_link()

tg_export_chat_link()

Описание

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

tg_create_chat_invite_link(platform_id, member_limit, hours, request,name)

Параметры:

! platform_id — идентификатор чата в Telegram * member_limit — лимит на количество участников hours — количество часов, которое будет действовать ссылка request — признак того, что при переходе по ссылке должен формироваться запрос на вступление чат name — название ссылки

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

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

tg_revoke_chat_invite_link(platform_id, invite_link)

Параметры: ! platform_id — идентификатор чата в Telegram * ! invite_link - ссылка, которую надо удалить

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

Использовать с осторожностью. Все существующие ссылки для входа в вашу группу станут неактивными.

tg_export_chat_link(platform_id)

Параметры: ! platform_id — идентификатор чата в Telegram *

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

Пример

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

tg_approve_chat_join_request()

tg_decline_chat_join_request()

Описание

Как принять заявку и добавить пользователя в канал/чат в Telegram tg_approve_chat_join_request(chat_id, user_id)

Параметры: ! chat_id - идентификатор группы/канала внутри Telegram * ! user_id - идентификатор пользователя внутри Telegram *

Как отклонить заявку в канал/чат в Telegram

tg_decline_chat_join_request(chat_id, user_id)

Параметры: ! chat_id - идентификатор группы/канала внутри Telegram * ! user_id - идентификатор пользователя внутри Telegram *

Пример

Прием заявки:

Отклонение заявки:

Как работать с подписчиками чата/канала Telegram

tg_ban_chat_member()

tg_unban_chat_member()

tg_get_chat_member()

tg_get_chat_member_count()

some_client_in_list()

Описание

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

tg_ban_chat_member(chat_id, user_id, hours)

Параметры: ! chat_id — идентификатор чата внутри Telegram * ! user_id - идентификатор пользователя внутри Telegram * для блокировки hours - длительность блокировки в часах. По умолчанию блокировка навечно. При указании длительности блокировки свыше 366 дней блокировка будет установлена навечно

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

tg_unban_chat_member(chat_id, user_id)

Параметры: ! chat_id — идентификатор чата внутри Telegram * ! user_id — iидентификатор пользователя внутри Telegram * , которого необходимо разблокировать

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

tg_get_chat_member(chat_id, user_id)

Параметры: ! chat_id — идентификатор чата внутри Telegram * ! user_id — идентификатор пользователя внутри Telegram *, подписку которого проверяем

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

tg_get_chat_member_count(platform_id)

Параметры: ! platform_id — идентификатор чата в Telegram *

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

some_client_in_list(list_id, recepient)

Параметры: ! list_id - номер списка ! recepient - идентификатор пользователя внутри Telegram *. Для клиентов чата данное значение в переменной chat_member_id.

Видеоразбор

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

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

tg_send_chat_action()

tg_answer_callback_query()

tg_callback_url_open()

Описание

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

tg_send_chat_action(platform_id, bot_action, message_thread_id )

Параметры: ! platform_id - идентификатор чата в Telegram * ! bot_action - действие бота из списка. message_thread_id — идентификатор темы (доступно для супергрупп при наличии функционала форума).

Список возможных действий bot_action: typing для текстовых сообщений, upload_photo для фотографий, record_video или upload_video для видео , record_voice или upload_voice для голосовых заметок, upload_document для общих файлов, choose_sticker для стикеров, find_location для данных о местоположении, record_video_note или upload_video_note для видеозаметки.

Данное уведомление будет отображаться, пока не будет получен какой-либо ответ от бота, но не более 5 секунд.

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

tg_answer_callback_query(callback_query_id, text,show_alert,cache_time)

Параметры: ! callback_query_id (обязательный)- данный идентификатор позволяет определить нажавшего кнопку и продемонстрировать ему Alert-уведомление ! text (обязательный) - текст Alert-уведомления.

show_alert - признак исчезающего уведомления (False - исчезающее уведомление (подсказка), True - уведомление в окне) cache_time - Максимальное количество времени в секундах, в течение которого результат запроса обратного вызова может быть кэширован на стороне клиента. Приложения Telegram будут поддерживать кэширование, начиная с версии 3.14. Значение по умолчанию равно 0

Как в реакции на callback-кнопку добавить переход в бота с тэгом

tg_callback_url_open(callback_query_id, url)

Параметры: ! callback_query_id - данный id позволяет идентифицировать нажавшего кнопку и продемонстрировать ему Alert-уведомление, ! url - URL-адрес, указывающий бота и параметр (выглядит так: t.me/your_bot?start=XXXX, вместо your_bot - имя бота)

Пример

Alert-уведомления показываются только в результате нажатия на callback-кнопку в телеграмме.

Для примера используем следующие кнопки: [{"line":0,"index_in_line":0,"text":"111","type":"inline","callback":"первая"}, {"line":1,"index_in_line":0,"text":"222","type":"inline","callback":"вторая"}, {"line":2,"index_in_line":0,"text":"333","type":"inline","callback":"третья"}]

После нажатия на такую кнопку приходит callback с текстом, содержащимся в соответствующем поле. При нажатии на кнопку “111” придет callback с текстом “первая”.

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

Если в поле Выбор соответствия выбрать Игнорируя ошибки и неточности, то в дальнейшем можно будет такой блок использовать для всех вариантов, которые отличаются на 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}', 't.me/bot_name?start=XXXX')

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

tg_promote_user()

tg_set_administrator_title()

tg_chat_permission()

tg_set_administrator_title()

tg_chat_permission()

tg_restrict_chat_member()

Описание

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

tg_promote_user(platform_id, user_id, promote_options_list)

Параметры: ! platform_id — идентификатор супергруппы или, если используете в канале, имя канала вида @channelusername, внутри Telegram * ! user_id — идентификатор пользователя внутри Telegram * ! promote_options_list — список прав, которые нужно включить.

В списке прав promote_options_list можно указать следующие права: is_anonymous — присутствие администратора в чате скрыто, can_manage_chat — администратор может получить доступ к журналу событий чата, статистике чата, статистике сообщений в каналах, видеть участников канала, видеть анонимных администраторов в супер-группах и игнорировать медленный режим. Этот уровень прав выдается по умолчанию, в случае указания любой из последующих привилегий. can_post_messages — администратор может создавать сообщения канала, только для каналов can_edit_messages — администратор может редактировать сообщения других пользователей и может закреплять сообщения, только для каналов can_delete_messages — администратор может удалять сообщения других пользователей can_manage_video_chats — администратор может управлять видеочатами, can_restrict_members — администратор может ограничивать, ставить/отменять бан участникам чата, can_promote_members — администратор может добавлять новых администраторов с подмножеством их собственных привилегий или понижать в должности администраторов, которых он повысил, прямо или косвенно (повысили администраторы, которые были им назначены) can_change_info — администратор может изменить название чата, фото и другие настройки can_invite_users — администратор может приглашать новых пользователей в чат can_pin_messages — администратор может закреплять сообщения, только для супергруппы.

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

tg_set_administrator_title(platform_id, user_id, title)

Параметры: ! platform_id — идентификатор супергруппы внутри Telegram * ! user_id — идентификатор пользователя внутри Telegram * ! title — титул администратора. Для титула есть следующие ограничения: 0-16 символов, эмодзи не разрешены.

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

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

tg_chat_permission(platform_id, permission, media_permissions)

Параметры: ! platform_id - идентификатор чата внутри Telegram * ! permission - массив значений для списка ограничений, приведенного ниже. В массиве значение 1 разрешает действие, а 0 - запрещает. Порядковый номер соответствует позиции в массиве ! media_permissions - список значений прав для работы с медиа (подробнее ниже). В списке значение 1 разрешает действие, а 0 запрещает. Порядковый номер соответствует позиции в списке.

Список ограничений 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:

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

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 - список значений для выдачи прав по работе с медиа

Пример

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

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

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

В данном примере помимо перечисленных прав будут по умолчанию выданы права can_manage_chat.

Назначение прав пользователю

Установка титула администратору

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

Пример 1

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

Пример 2

promote_options_list = ‘[“can_promote_members”,”can_change_info”,”can_invite_users”]’ tg_promote_user(platform_id, user_id, promote_options_list)

Пример 3

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) / Пример 4 */ result=tg_set_administrator_title(platform_id, reply_from, "огоньтитул")

Как работать с сообщениями в чате/канале Telegram

tg_pin_chat_message()

tg_unpin_chat_message()

tg_unpin_all()

Описание

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

tg_pin_chat_message(platform_id, message_id, disable_notification)

Параметры: ! platform_id — идентификатор чата внутри Telegram * message_id – идентификатор сообщения, которое нужно закрепить disable_notification – параметр определяет нужно ли отправлять уведомление всем участникам чата о новом закрепленном сообщении (уведомления всегда отключены в каналах и приватных чатах). Если не нужно отправлять уведомления, то в качестве значения параметра disable_notification передайте 1, иначе - 0.

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

tg_unpin_chat_message(platform_id, message_id)

Параметры: ! platform_id — идентификатор чата внутри Telegram * message_id – идентификатор сообщения, которое нужно открепить. Если message_id не указан, то будет откреплено самое последнее (по дате отправки) закрепленное сообщение.

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

tg_unpin_all(platform_id)

Параметры: ! platform_id — идентификатор чата внутри Telegram *

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

tg_set_command()

tg_get_command()

tg_delete_command()

Описание

Для установки команд

tg_set_command(commands, language, scope, platform_id, user_id)

Параметры: ! commands — команды для бота в виде списка списков, каждый вложенный список состоит из 2 элементов: 1 - наименование команды, 2 - ее описание (существует ограничение в 100 команд),

language – двухбуквенный код языка ISO 639-1, например 'ru' или 'en' Если не указан, то команды будут применяться ко всем пользователям из области, для языка которых нет выделенных команд),

scope – параметр описывающий круг пользователей, для которых создаются команды. Значение по умолчанию 'default'

platform_id - идентификатор чата внутри Telegram *. Применяется только при определенных значениях параметра scope

user_id – идентификатор пользователя внутри Telegram * . Применяется только при определенных значениях параметра scope.

Как настроить реакцию на команды

Для команд в переписке с ботом реагировать нужно на сообщения вида: '/command_name' – в этом примере command_name – команда.

для команд в чатах при вводе команды будут приходить сообщения вида:

Для команд в группах и чатах реагировать нужно на сообщения вида:

'/command_name@bot_username' – в этом примере command_name – команда, а @bot_username – username бота.

Список значений scope:

'default' - параметр по-умолчанию, подразумевает что команды будут работать в личных сообщениях с ботом.

'all_private_chats' – все закрытые чаты, команды доступны всем в закрытых чатах, в которых добавлен бот.

'all_group_chats' – все групповые и супергрупповые чаты, команды доступны всем в указанных видах чатов, в которых добавлен бот.

'all_chat_administrators' – команды для администраторов всех групповых и супергрупповых чатов, в которых добавлен бот.

'chat' – команды для определенного чата (если выбрали данный вариант, то необходимо указать platform_id).

'chat_administrators' – команды для администраторов определенного чата (если выбрали данный вариант, то необходимо указать platform_id).

'chat_member' – команды для конкретного участника определенного чата (если выбрали данный вариант, то необходимо указать platform_id и user_id, указанный пользователь должен состоять в указанном чате).

Если Вы не хотите использовать параметр language, но при этом используете параметр scope, то не забудьте указать после команд пустой параметр, как в примере: tg_set_command(command, '', scope)

Для просмотра команд

tg_get_command(language, scope, platform_id, user_id)

Параметры: language – двухбуквенный код языка ISO 639-1, например 'ru' или 'en' Если не указан, то будут показаны команды, применяемые ко всем пользователям из заданной области, для языка которых нет выделенных команд),

scope – параметр описывающий круг пользователей, для которых должны быть показаны команды(необязательный параметр, если не используете, то по умолчанию будет применено значение 'default'),

platform_id - идентификатор чата внутри Telegram * Применяется только при определенных значениях параметра scope,

user_id – идентификатор пользователя внутри Telegram * Применяется только при определенных значениях параметра scope.

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

tg_get_command('', scope)

Для удаления команд

tg_delete_command(language, scope, platform_id, user_id), где

language – двухбуквенный код языка ISO 639-1, например 'ru' или 'en' (необязательный параметр, если не указан, то будут удалены команды, которые применяться ко всем пользователям из заданной области, для языка которых нет выделенных команд),

scope – параметр описывающий круг пользователей, для которых удаляются команды Если не используете, то по умолчанию будет применено значение 'default'

platform_id - идентификатор чата (необязательный параметр, применяется только при определенных значениях параметра scope),

user_id – идентификатор пользователя (необязательный параметр, применяется только при определенных значениях параметра scope). Если Вы не хотите использовать параметр language, но при этом используете параметр scope, то не забудьте указать в начале пустой параметр, как в примере:

tg_delete_command('', scope)

Команда вида tg_delete_command() удалит команды без указания параметра language из параметра scope по умолчанию.

Пример

Пример установки команд:

command = [["count", "return count of user"],["unpin", "unpin all message"]] tg_set_command(command, '', 'all_chat_administrators')

В этом примере команды вынесены в отдельную переменную. Также можно добавить эти команды прямо в функцию:

tg_set_command('[["count", "return count of user"],["unpin", "unpin all message"]]', '', 'all_chat_administrators')

Для дальнейшего вызова команд в поле ввода сообщения введите символ '/'. Если все было сделано верно, то увидите подсказку в виде списка команд. Жирным шрифтом выделены команды, правее их описание.

Для использования команд настройте реакцию на сообщения содержащие команды.

Для просмотра установленных команд

command = tg_get_command('', 'all_chat_administrators')

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

{"ok":true,"result":[{"command":"count","description":"return count of user"},{"command":"unpin","description":"unpin all message"}]}

Если вызвать функцию без параметров, то scope по умолчанию примет значение 'default'.

command = tg_get_command()

Удалить установленные команды можно:

tg_delete_command('', 'all_chat_administrators')

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

tg_send_poll()

tg_send_quiz_poll()

tg_stop_poll()

Описание

Как создать простой опрос в 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 - идентификатор чата внутри 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 - идентификатор цитируемого сообщения

message_thread_id — идентификатор темы (доступно для супергрупп при наличии функционала форума)

business_connection_id - значение при подключении бота - Business ID - отображается в каналах. Следует передавать, если в параметрах передается токен бота и надо отправить через подключенный к боту пользовательский аккаунт

Примечания

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

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

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

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

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

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

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

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

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

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

Как создать викторину в 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 - идентификатор чата внутри Telegram *

! question - вопрос

! options - массив вариантов ответов

! explanation - текст, который отображается, когда пользователь выбирает неправильный ответ или нажимает на значок лампы в опросе в стиле викторины, 0–200 символов с не более, чем двумя переводами строки после разбора сущностей.

! correct_option_id - номер правильного ответа, нумерация с 1

is_anonymous - 1 - анонимный опрос, '' - неанонимный

reply_markup - клавиатура или '' - без клавиатуры

parse_mode - markdown или html для explanation или '' - без форматирования

protect_content - 1 защитить от копирования и скриншотов, '' - без защиты

disable_notification — признак отправки со звуковым уведомлением (по умолчанию 0) 1 - отключить уведомление при получении, 0 - передать с уведомлением

token - токен бота, если не передан используется текущий

reply_to_message_id - ид цитируемого сообщения

message_thread_id — идентификатор темы (доступно для супергрупп при наличии функционала форума)

open_period - время для прохождения викторины/теста; передается числовое значение от 5 до 600, равное количеству секунд.

business_connection_id - значение при подключении бота - Business ID - отображается в каналах. Следует передавать, если в параметрах передается токен бота и надо отправить через подключенный к боту пользовательский аккаунт

Примечания

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

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

Пример колбека в

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

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

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

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

Нумерация ответов начинается с 0. poll_answer 5325838371359031648 [3]

poll_answer - неизменяемая часть 5325838371359031648 - идентификатор викторины [3] - ответ

Колбек на выбор ответа в Викторине

5. Если неанонимный опрос был создан в группе (не важно функцией или пользователем), в которой состоит в качестве администратора бот, то на каждый голос будет отправлен вебхук, при получении которого в диалог бота с клиентом будет отправлен колбек из пункта 4. Если клиент не контактировал с ботом, то отправить ему что-либо в ответ не получится, пока клиент не активирует бота.

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

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

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

Когда опрос или викторина завершаются этой функцией в ответ приходит словарь с результатом опроса.

tg_stop_poll(platform_id, message_id)

Параметры: ! platform_id - идентификатор чата внутри Telegram * ! message_id - идентификатор сообщения с опросом или викториной. Этот идентификатор можно получить из вебхука

Пример

В своей работе мы часто задаемся вопросами, на которые могли бы ответить наши клиенты. Опросы очень помогают получить обратную связь от клиентов и сделать определенные выводы. Давайте разберемся как создать простой опрос при помощи функции Api:

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

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

Пример создания Викторины:

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

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

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

Видеоразбор

Как работать с Форумами/Темами Telegram

Как работать с главной темой Telegram

tg_edit_general_forum_topic()

tg_close_general_forum_topic()

tg_reopen_general_forum_topic()

tg_hide_general_forum_topic()

tg_unhide_general_forum_topic()

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

Описание

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

tg_edit_general_forum_topic(platform_id, topic_name)

Параметры:

! platform_id - идентификатор Темы внутри Telegram *

! topic_name - новое имя темы.

Как закрыть главную Тему

tg_close_general_forum_topic(platform_id)

Параметры:

! platform_id - идентификатор Темы внутри Telegram *

Как открыть ранее закрытую главную Тему

tg_reopen_general_forum_topic(platform_id)

Параметры:

! platform_id - идентификатор Темы внутри Telegram *

Как скрыть главную Тему

tg_hide_general_forum_topic(platform_id)

Параметры:

! platform_id - идентификатор Темы внутри Telegram *

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

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

tg_unhide_general_forum_topic(platform_id)

Параметры:

! platform_id - идентификатор Темы внутри Telegram *

Важно!!! эта функция не открывает главную тему, а только делает ее видимой

Примеры

Изменить Главную тему группы можно при помощи функции tg_edit_general_forum_topic(). Здесь 2 обязательных параметра - это идентификатор чата и новое наименование для Темы группы:

Изменение названия главной Темы

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

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

/*закрыть чат главной Темы*/
answer = tg_close_general_forum_topic(-1001839380031)

/*открыть чат главной Темы*/
answer = tg_reopen_general_forum_topic(-1001839380031)

/*скрыть чат главной Темы*/
answer = tg_hide_general_forum_topic(-1001839380031)

/*отобразить чат главной Темы*/
answer = tg_unhide_general_forum_topic(-1001839380031)

Как работать с дополнительными темами Telegram

tg_create_forum_topic()

tg_edit_forum_topic()

tg_close_forum_topic()

tg_reopen_forum_topic()

tg_delete_forum_topic()

Описание

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

tg_create_forum_topic(platform_id, name, icon, icon_color)

Параметры:

! platform_id - идентификатор чата внутри Telegram *

! name - название новой темы

icon - идентификатор эмодзи, которое будет установлено на тему. Передается в виде строки. Можно использовать только те эмодзи, что есть в списке, полученном функцией tg_get_forum_icon

icon_color - цвет эмодзи из списка: 7322096, 16766590, 13338331, 9367192, 16749490, 16478047. Изменить цвет можно далеко не у всех эмодзи.

Изменить установленный цвет нельзя, цвет задается только в момент создания темы

В результате исполнения функция вернет ответ, содержащий параметры новой темы, в том числе идентификатор темы (нужен для различных функций)

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

tg_edit_forum_topic(platform_id, message_thread_id, name, icon)

Параметры:

! platform_id - идентификатор чата внутри Telegram *

! message_thread_id - идентификатор чата дополнительной темы

name - название новой темы

icon - идентификатор эмодзи, которое будет установлено на тему. Передается в виде строки. Можно использовать только те эмодзи, что есть в списке, полученном функцией tg_get_forum_icon

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

Закрыть тему - это значит оставить ее только для чтения, писать в закрытую тему нельзя

tg_close_forum_topic(platform_id, message_thread_id)

Параметры:

! platform_id - идентификатор чата внутри Telegram *

! message_thread_id - идентификатор чата дополнительной темы

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

tg_reopen_forum_topic(platform_id, message_thread_id)

Параметры:

! platform_id - идентификатор чата внутри Telegram *

! message_thread_id - идентификатор чата дополнительной темы

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

tg_delete_forum_topic(platform_id, message_thread_id)

Параметры:

! platform_id - идентификатор чата внутри Telegram *

! message_thread_id - идентификатор чата дополнительной темы

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

tg_unpin_topic_messages(platform_id, message_thread_id)

Параметры:

! platform_id - идентификатор чата внутри Telegram *

! message_thread_id - идентификатор чата дополнительной темы

Примеры

Давайте создадим чат дополнительной темы:

Создание новой темы

Переменная answer будет содержать ответ следующего содержания: {"ok":true,"result":{"message_thread_id":254,"name":"second_bot_topic","icon_color":7322096}}

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

Сохраняем из ответа функции по созданию идентификатор дополнительной темы

Скрин Карточки клиента, раздел Переменные

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

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

/*Сохраняем идентификатор чата созданной дополнительной темы*/
/*answer={"ok":true,"result":{"message_thread_id":254,"name":"second_bot_topic","icon_color":7322096}}*/
idtema1=answer['result']['message_thread_id']

/**/
answer = tg_close_forum_topic(-1001839380031, 254)

answer = tg_reopen_forum_topic(-1001839380031, 254)

answer = tg_delete_forum_topic(-1001839380031, 254)

answer = tg_unpin_topic_messages(-1001839380031, 254)

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

tg_get_forum_icon()

Описание

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

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()