Функции работы в чатах и каналах 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 *

Как создать/закрыть опрос в чате/канале 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 )

Параметры: ! 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 — идентификатор темы (доступно для супергрупп при наличии функционала форума)

Примечания

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 — идентификатор темы (доступно для супергрупп при наличии функционала форума)

Примечания

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)