Bot API — справочник

Авторизация

Без заголовка — 401 Missing Authorization. С неверным токеном — 401 Invalid bot token. Боты не используют куки: аутентификация только по токену.

Получение обновлений (long-polling)

Следующее значение after — это messages.at(-1).createdAt. Без timeout запрос возвращает пустоту сразу — используйте long-polling для мгновенных ответов.

Все методы

sendMessage

sendMessageToUser

Написать первым пользователю. Требует username или userId, text и опциональную keyboard. Ограничение: 20 новых диалогов в час (429).

sendPhoto

Файл передаётся ссылкой (url) или data:-строкой. Поля: chatId, url, caption, replyToId.

sendDocument

Файл по ссылке (url). Поля: chatId, url, name, caption, replyToId.

sendVideo

Аналогично sendPhoto для видео. Поля: chatId, url, caption, replyToId.

sendVoice

Голосовое сообщение по ссылке (url). Дополнительно durationSec. Поля: chatId, url, caption, replyToId, durationSec.

sendVideoNote

Круглое видеосообщение. Поля: chatId, url, caption, replyToId, durationSec.

sendSticker

Стикер по эмодзи. Поля: chatId (обязательно), emoji (обязательно), name, scene, replyToId.

sendPoll

Опрос с 2–8 вариантами. Поля: chatId, question, options (массив строк), replyToId.

sendLocation

Точка на карте. Поля: chatId, lat, lng, caption, replyToId.

sendContact

Контакт. Поля: chatId, name, phone, userId, replyToId.

sendMediaGroup

Альбом до 10 файлов одним сообщением. items — массив { kind, url, name }. Виды: image, video, file, voice, video-note.

editMessageText

Редактировать своё сообщение. Поля: messageId, text. Чужие сообщения не редактируются (403).

deleteMessage

Удалить своё сообщение по messageId. Только свои (403).

sendReaction

Поставить/снять реакцию. Поля: messageId, emoji. Повторный вызов с тем же эмодзи снимает реакцию.

editMessageKeyboard

Заменить клавиатуру под своим сообщением. Поля: messageId, keyboard.

forwardMessage

Переслать сообщение. Поля: messageId, toChatId. Оба чата должны быть чатами бота.

copyMessage

Отправить содержимое сообщения без отметки «переслано». Поля: chatId, messageId.

sendChatAction

Показать статус «печатает» или загрузки. Поля: chatId, необязательный action (typing, upload_photo, record_video, upload_video, record_voice, upload_voice, upload_document, record_video_note, upload_video_note). Живёт 5 секунд.

sendGame

Карточка игры в чате. Поля: chatId, gameId.

getChats

Все чаты, где состоит бот: id, тип, название, юзернейм, число участников, флаг админа.

getChat

Один чат с полным списком участников.

createGroup

Создать группу. Поля: title (обязательно), memberIds — массив userId (только знакомые).

createChannel

Создать канал. Поля: title (обязательно), description, username, isPublic.

setChatDiscussion

Привязать обсуждение к каналу. action: create, link (с groupId), unlink.

getChatDiscussion

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

getChatAdmins

Владелец и администраторы чата.

getChatMember

Данные участника, его права и срок ограничения.

getChatMemberCount

Количество участников в чате.

addChatMember

Добавить участника (только админ). Поля: chatId, userId.

promoteChatMember

Назначить/снять админа (только владелец). Поля: chatId, userId, admin (true/false).

restrictChatMember

Временное молчание (только админ). Поля: chatId, userId, minutes (до 30 дней).

banChatMember

Забанить участника (только админ). Владельца и админов забанить нельзя (400).

unbanChatMember

Разбанить участника (только админ). Поля: chatId, userId.

deleteAnyMessage

Удалить чужое сообщение (только админ). Поля: chatId, messageId.

exportChatInviteLink

Ссылка-приглашение в чат (только админ). Поля: chatId, revoke (true — выпустить новую).

leaveChat

Выйти из чата. Поле: chatId.

setChatPermissions

Настройка прав чата (только админ). Поле permissions — объект с правилами.

setChatTitle

Переименовать чат (только админ). Поля: chatId, title.

setChatDescription

Описание канала или группы (только админ). Поля: chatId, description.

getUser

Данные пользователя: имя, юзернейм, аватар. Email не отдаётся.

getUserStatus

Онлайн и время последнего посещения.

getCommonChats

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

resolveUsername

Найти пользователя, канал или группу по юзернейму. Возвращает kind, user или chat.

me

Аккаунт бота: имя, юзернейм, аватар, мини-приложение.

setMyProfile

Изменить имя и описание бота. Поля: name, description.

setMyAvatar

Установить аватар бота. Поле image — URL или data:-строка.

setMyCommands

Установить команды бота. Поле commands — массив { command, description }. До 50 команд.

getMyCommands

Список установленных команд бота.

getMyStats

Статистика: число чатов, отправленных сообщений, уникальных собеседников.

setWebApp

Настроить мини-приложение бота. Поля: url, name.

setWebAppCode

Хостинг кода мини-приложения на сервере Shalter. Поле code (до 200 000 символов), name.

checkWebAppData

Проверить initData мини-приложения. Поле initData.

publishPost

Опубликовать пост в канале (только админ). Поля: chatId, text, url.

getChannelStats

Подписчики, посты, просмотры, комментарии канала (только админ).

getMessages

Страница сообщений чата. Свежие в конце. before — идентификатор сообщения для пагинации.

searchMessages

Поиск по истории чата. До 50 последних совпадений.

getMessage

Одно сообщение по ID.

getPinnedMessages

Все закреплённые сообщения в чате.

pinChatMessage

Закрепить сообщение. Поля: messageId, pinned (true по умолчанию).

scheduleMessage

Отложенная отправка. Поля: chatId, text, sendAt (ISO 8601, будущее время).

getScheduled

Список отложенных сообщений в чате.

cancelScheduled

Отменить отложенное сообщение по scheduledId.

// Минимальный бот на чистом Node.js (нет зависимостей)
const TOKEN = process.env.SHALTER_TOKEN;
const API = "https://shalter.ru/api/bot-api";
const auth = { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" };

let after = new Date().toISOString();

async function send(chatId, text) {
  await fetch(`${API}/sendMessage`, {
    method: "POST", headers: auth,
    body: JSON.stringify({ chatId, text }),
  });
}

async function tick() {
  const res = await fetch(`${API}/updates?after=${after}&timeout=30`, { headers: auth });
  const { messages } = await res.json();
  for (const msg of messages) {
    after = msg.createdAt;
    if (msg.text === "/start") await send(msg.chatId, "Привет! Я бот.");
    else await send(msg.chatId, `Вы написали: ${msg.text}`);
  }
}

setInterval(() => tick().catch(console.error), 2000);