TomoChat Bot API

Создавайте ботов для TomoChat: отвечайте на сообщения, работайте в группах и каналах сообществ, получайте обновления long-poll или вебхуком. Если вы знакомы с Telegram Bot API — здесь всё похоже.

Быстрый старт Токен Формат запросов Методы Обновления Вебхук Лимиты и ошибки Owner API

Быстрый старт

В приложении TomoChat: Настройки → Боты → Создать бота. Укажите ник (латиница, цифры, _, 5–32 символа, заканчивается на bot) и имя. Скопируйте токен — он показывается один раз.

Проверьте токен:

curl https://bots.tomochat.ru/bot<TOKEN>/getMe

Найдите бота в приложении по нику и напишите ему. Заберите обновление:
```
curl "https://bots.tomochat.ru/bot<TOKEN>/getUpdates?timeout=30"
```

Ответьте:

curl -X POST https://bots.tomochat.ru/bot<TOKEN>/sendMessage \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 38, "text": "Привет! Я бот."}'

Бот — обычный аккаунт TomoChat: его можно добавить в группу штатной кнопкой «Добавить участника», найти в поиске по нику, написать в личку. В беседах он помечен значком бота.

Токен

Формат: <bot_id>:<secret>. Токен передаётся только в пути запроса: /bot<TOKEN>/<method>. Храните его как пароль; перевыпустить можно в Настройках → Боты (старый перестаёт работать сразу).

Формат запросов и ответов

База: https://bots.tomochat.ru/bot<TOKEN>/<method>. Метод можно вызывать GET или POST; параметры — JSON-тело (application/json), application/x-www-form-urlencoded или query string. Имена методов регистронезависимы.

Успех: {"ok": true, "result": …}. Ошибка: {"ok": false, "error_code": 400, "description": "Bad Request: …"}. При 429 дополнительно "parameters": {"retry_after": N}.

Методы

Метод	Параметры	Результат
`getMe`	—	профиль бота: `id`, `nickname`, `name`, `description`, `has_webhook`…
`getUpdates`	`offset`, `limit` (≤100), `timeout` (сек, ≤50 — long-poll)	массив Update
`sendMessage`	`chat_id` или `user_id`, `text` (≤4096), `reply_to_message_id?`, `client_message_id?`	отправленное сообщение
`editMessageText`	`chat_id`, `message_id`, `text`	сообщение
`deleteMessage`	`chat_id`, `message_id`	`true`
`getChat`	`chat_id`	беседа (`id`, `type`, `name`, участники)
`leaveChat`	`chat_id`	`true`
`setWebhook`	`url` (https, публичный адрес), `secret_token?`	`true`
`deleteWebhook`	—	`true`
`getWebhookInfo`	—	`{url, has_custom_secret, last_error_message?, last_error_date?}`
`setMyCommands`	`commands`: массив `{command, description}`	`true`
`getMyCommands`	—	массив команд
`deleteMyCommands`	—	`true`

chat_id — идентификатор беседы (приходит в update.message.chat.id). user_id в sendMessage — написать пользователю в личку: бот сам найдёт или создаст беседу.

Команды из setMyCommands показываются пользователям в меню «/» в чате с ботом. Команда: 1–32 символа a-z0-9_, описание обязательно.

Обновления

Каждый Update содержит update_id и ровно одно из полей:

`message` — новое сообщение боту

{
  "update_id": 17,
  "message": {
    "message_id": 5123,
    "chat": {"id": 42, "type": "group", "title": "Команда"},
    "from": {"id": "849337a7-…", "name": "Иван", "is_bot": false},
    "date": 1755850000,
    "text": "/start hello",
    "kind": "text",
    "has_media": false,
    "command": "start",
    "command_args": "hello"
  }
}

chat.type: direct — личка, group — группа, community — канал сообщества. kind: text, sticker, voice, video_circle, image… для не-текстовых сообщений text пустой, has_media = true. command заполняется для /cmd и /cmd@ваш_бот; команда, адресованная другому боту, приходит просто текстом.

`my_chat_member` — бота добавили в беседу или удалили

{
  "update_id": 18,
  "my_chat_member": {
    "chat": {"id": 42, "type": "group", "title": "Команда"},
    "from": {"id": "849337a7-…"},
    "date": 1755850100,
    "user": {"id": "<bot_id>", "is_bot": true},
    "old_status": "left",
    "new_status": "member",
    "event": "member_added"
  }
}

new_status: member (добавили/создали группу с ботом), left (бот вышел), kicked (удалили или забанили). Хороший момент, чтобы поздороваться в группе.

`chat_member` — в беседе, где состоит бот, кто-то вошёл или вышел

Та же структура: user — кого касается, from — кто это сделал, event — исходное событие (member_joined, member_added, member_left, member_removed, member_banned, guest_joined, guest_left).

getUpdates и подтверждение

Передавайте offset = update_id последнего обработанного + 1 — всё, что меньше, удаляется из очереди. Неподтверждённые обновления хранятся 24 часа. Пока активен вебхук, getUpdates возвращает 409.

Вебхук

setWebhook с url (только https, публичный адрес) и необязательным secret_token (A–Z, a–z, 0–9, _, -). Каждый Update будет отправлен POST-ом как JSON с заголовком X-TomoChat-Bot-Api-Secret-Token: <secret_token>. Ответ 2xx = доставлено; иначе 3 повтора (2 с / 10 с / 30 с), затем ошибка попадает в getWebhookInfo, а обновление остаётся в очереди — заберёте через getUpdates после deleteWebhook.

Лимиты и ошибки

30 отправок в секунду на бота (sendMessage, editMessageText, deleteMessage); при превышении — 429 и retry_after.
Текст сообщения — до 4096 символов.
401 — неверный токен; 403 — бот не участник беседы или нет прав; 404 — метод/беседа не найдены; 409 — конфликт (getUpdates при вебхуке); 502 — недоступен сервис чата.

Owner API (для приложений TomoChat)

Управление своими ботами из клиентов, авторизация — JWT пользователя (Authorization: Bearer).

Метод	Путь	Описание
POST	`/api/v1/bots`	`{nickname, name}` → `{bot, token}`
GET	`/api/v1/bots`	мои боты
GET	`/api/v1/bots/:id`	бот
PATCH	`/api/v1/bots/:id`	`{name?, description?, commands?}`
DELETE	`/api/v1/bots/:id`	удалить
POST	`/api/v1/bots/:id/token`	перевыпустить токен
GET	`/api/v1/bots/:id/public`	описание и команды бота (любой пользователь)

Версия API: 1. Обратная совместимость: новые поля добавляются без предупреждения, существующие не удаляются.