Функции работы в чатах и каналах Telegram
Last updated
Last updated
Так как внутри Salebot идентификаторы клиентов (пользователей, групп, каналов) внутри мессенджера записываются в переменной platform_id без каких-либо меток чему это принадлежит группе или пользователю, то для работы с функциями принятия/отклонения заявки требуется единожды запомнить значения platform_id чата и platform_id пользователя в переменные с разными именами, например, chat_id и user_id.
Как поменять имя чата через бот в 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(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(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(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(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.
Как показать пользователю действия бота (печатает/выбирает стикер и т.д)
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, cache_time)
Параметры: ! callback_query_id - данный id позволяет идентифицировать нажавшего кнопку и продемонстрировать ему Alert-уведомление, ! url - URL-адрес, указывающий бота и параметр (выглядит так: t.me/your_bot?start=XXXX, вместо your_bot - имя бота) cache_time - максимальное количество времени в секундах, в течение которого результат запроса обратного вызова может быть кэширован на стороне клиента.
Как повысить пользователя до администратора в супер-группе или канале в 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 запрещает. Порядковый номер соответствует позиции в списке.
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 - разрешение создавать темы в группах-форумах. Если пытаться применить в группах неподходящего типа, то функция не сработает и вернет ошибку.
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 - список значений для выдачи прав по работе с медиа
Как закрепить сообщение
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(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 - идентификатор сообщения с опросом или викториной. Этот идентификатор можно получить из вебхука
При этом владелец забаненного чата не сможет писать и от имени других своих чатов до тех пор, пока не будет разбанен
