Clouchat Команды
Команды начинаются с «/». Список, заданный через /setcommands или setMyCommands, появляется в меню рядом с полем ввода и в подсказках при наборе «/».
Каждому боту стоит поддерживать /start — с неё начинается диалог — и /help.
Кнопки и клавиатуры
Кнопки под сообщением не отправляют текст в чат. Они открывают ссылку, присылают боту колбэк, копируют текст, запускают мини-приложение или переключают пользователя в inline-режим. Бот может менять кнопки в уже отправленном сообщении — так делают меню, листалки и формы.
Клавиатура вместо системной предлагает готовые ответы. Кнопка может запросить контакт или геопозицию пользователя; контакт собирает сервер из аккаунта, поэтому чужой номер подставить нельзя.
Колбэки
Нажатие на колбэк-кнопку приходит боту как callback_query. Ответьте answerCallbackQuery в течение 10 секунд: можно показать короткое уведомление, окно или открыть ссылку на этого же бота. Без ответа индикатор загрузки на кнопке исчезнет сам.
Ссылки на бота
https://join.clouchat.org/имя_бота открывает чат с ботом. Параметр ?start=значение придёт боту в команде /start значение после нажатия «Старт» — так передают реферальные коды и метки кампаний.
https://join.clouchat.org/имя_бота?startapp=значение сразу открывает главное мини-приложение бота и передаёт ему start_param.
Кнопка меню
Слева от поля ввода в чате с ботом есть кнопка меню. Она показывает список команд или запускает мини-приложение — это настраивается в «Моих ботах» или методом setChatMenuButton, отдельно для всех чатов или для конкретного пользователя. Подробнее — в разделе Мини-приложения.
Группы и каналы
Бота добавляют в группу как обычного участника, если владелец не запретил это командой /setjoingroups. В канал бота можно добавить только администратором; тогда он получает посты канала и может публиковать свои.
По умолчанию в группе включён режим приватности: бот получает команды, сообщения с упоминанием и ответы на свои сообщения. Бот-администратор и бот с выключенным режимом приватности получают все сообщения. Сообщения других ботов боту не приходят.
Бот действует от своего имени и с теми правами, что ему выдали: удалять сообщения, ограничивать участников и закреплять он может, только если у него есть эти права. О собственном добавлении, удалении и смене прав бот узнаёт из апдейта my_chat_member.
Inline-режим
Включите режим командой /setinline. Пользователь набирает @имя_бота запрос в любом чате, бот получает inline_query и отвечает списком результатов: статьи, сохранённые фото, видео, GIF, стикеры, документы, геопозиции и контакты. Выбранный результат уходит в чат от пользователя с пометкой «через @имя_бота».
Если у результата есть кнопки, бот может получать по ним колбэки и править отправленное сообщение. Детали — в справочнике.
Мини-приложения
Мини-приложение — веб-страница бота, которая открывается поверх чата и получает подписанные данные пользователя. Запустить её можно кнопкой под сообщением, кнопкой клавиатуры, кнопкой меню, ссылкой со startapp и из меню вложений. Пользователь может добавить ярлык мини-приложения на главный экран. Подробнее — в разделе Мини-приложения.
Меню вложений
Боты, одобренные администрацией Clouchat, можно добавить в меню вложений. Тогда мини-приложение бота открывается из личных чатов и групп, а результат отправляется в этот чат от имени пользователя.
Правила
- Бот не может написать человеку первым — только после того, как человек запустил бота или написал ему.
- Пользователь может заблокировать бота, после этого доставка ему прекращается.
- Действуют лимиты на частоту сообщений; при превышении API отвечает ошибкой 429.
- Не запрашивайте у пользователей коды подтверждения и PIN-коды Clouchat.
- Если бот обрабатывает персональные данные, вы как его владелец отвечаете за соблюдение закона и публикуете свою политику обработки данных.
- На ботов можно пожаловаться. Модераторы Clouchat могут отключить бота, его мини-приложения или inline-режим.