Bot API

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

Эхо-бот за минуту: получаем сообщения и отвечаем тем же текстом.

# 1. Проверяем токен
TOKEN=123:AbCdEf...
curl "https://core.chatto.is/api/v1/bot/$TOKEN/getMe"

# 2. Ждём сообщения (long polling до 25 секунд)
curl "https://core.chatto.is/api/v1/bot/$TOKEN/getUpdates?timeout=25"

# 3. Отвечаем в чат из message.chat.id
curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/sendMessage" \
  -H 'Content-Type: application/json' \
  -d '{"chat_id": 7, "text": "Привет!"}'

Бот пишет только в чаты, где он участник. Личный чат начинает пользователь — сообщением боту или кнопкой «Запустить» (придёт /start). В группах бот получает команды и сообщения с упоминанием @имя_бота.

Запросы и ответы

Все методы принимают GET и POST: параметры в строке запроса, application/json или form-data.

Успех

{"ok": true, "result": …}

Ошибка

{"ok": false, "error_code": 400,
 "description": "Bad Request: …"}

Получение обновлений

Два способа — выберите один. Пока установлен вебхук, getUpdates возвращает ошибку 409.

Long polling

Вызывайте getUpdates в цикле с timeout=25 и offset, равным последнему update_id + 1. Удобно при разработке — не нужен публичный адрес.

Вебхук

После setWebhook Chatto отправляет каждое обновление POST-запросом на ваш HTTPS-адрес с заголовком X-Chatto-Bot-Api-Secret-Token. Ответьте кодом 2xx, иначе доставка повторится.

Кнопки под сообщениями

reply_markup.inline_keyboard — до 10 рядов по 8 кнопок. Кнопка открывает ссылку, мини-приложение или присылает боту callback_query.

{
  "inline_keyboard": [
    [{"text": "Нравится", "callback_data": "like:42"}],
    [{"text": "Открыть каталог", "web_app": {"url": "https://shop.example"}}],
    [{"text": "Сайт", "url": "https://chatto.is"}]
  ]
}

После нажатия кнопки с callback_data у пользователя показывается индикатор загрузки, пока бот не ответит answerCallbackQuery. На ответ — 5 секунд.

Mini Apps

Веб-приложения, которые открываются прямо в Chatto: магазины, сервисы, формы, игры. API совместим с Telegram Web Apps — код, написанный под Telegram.WebApp, работает без правок.

Как открыть мини-приложение

Способ	Как настроить
Кнопка меню	`setChatMenuButton` с `type: "web_app"` — кнопка слева от поля ввода в чате с ботом
Кнопка под сообщением	`{"text": "Каталог", "web_app": {"url": "https://…"}}` в `inline_keyboard`
Профиль бота	`setMainWebApp` — кнопка «Открыть приложение» в профиле
Ссылка	`https://chatto.is/app/имя_бота?startapp=promo` — параметр придёт в `initDataUnsafe.start_param`

Подключение SDK

Внутри Chatto SDK подключается автоматически. Добавьте его явно, чтобы страница работала и в обычном браузере:

<script src="https://chatto.is/js/chatto-web-app.js"></script>
<script>
  const app = window.Chatto.WebApp;   // то же, что window.Telegram.WebApp
  app.ready();
  app.MainButton.setText('Купить за 990 ₽').show().onClick(() => {
    app.HapticFeedback.impactOccurred('medium');
    fetch('/api/order', { method: 'POST', body: app.initData });   // проверьте подпись на сервере
  });
</script>

Возможности SDK

API	Описание
initData	Подписанные данные запуска: `user`, `query_id`, `start_param`, `auth_date`, `hash`
themeParams	Цвета приложения и CSS-переменные `--tg-theme-bg-color`, `--tg-theme-text-color`, `--tg-theme-button-color` и другие
MainButton	Нативные кнопки внизу экрана (также `SecondaryButton`): текст, цвет, индикатор загрузки, блик
BackButton	Кнопка «Назад» в шапке; `SettingsButton` — пункт «Настройки» в меню
HapticFeedback	`impactOccurred`, `notificationOccurred`, `selectionChanged`
showPopup	Нативные окна до трёх кнопок; также `showAlert` и `showConfirm`
showScanQrPopup	Встроенный сканер QR-кодов
CloudStorage	Хранилище «ключ — значение» для пары бот и пользователь: до 1024 ключей, значения до 4096 символов
sendData	Строка до 4096 байт боту — придёт как `message.web_app_data`, приложение закроется
openLink	Открыть ссылку в браузере; `openChattoLink` — ссылку Chatto внутри приложения
прочее	`readTextFromClipboard`, `expand`, `close`, `enableClosingConfirmation`, `setHeaderColor`, `setBackgroundColor` — как в Telegram

Проверка initData на сервере

Не доверяйте initDataUnsafe — проверяйте подпись. Алгоритм такой же, как в Telegram: secret = HMAC_SHA256(key="WebAppData", data=токен), затем hash = hex(HMAC_SHA256(key=secret, data=data_check_string)), где data_check_string — все поля, кроме hash, в виде ключ=значение, отсортированные по алфавиту и соединённые символом \n.

# Python
import hmac, hashlib
from urllib.parse import parse_qsl

def check(init_data: str, token: str) -> bool:
    data = dict(parse_qsl(init_data))
    received = data.pop("hash", "")
    check_string = "\n".join(f"{k}={v}" for k, v in sorted(data.items()))
    secret = hmac.new(b"WebAppData", token.encode(), hashlib.sha256).digest()
    return hmac.compare_digest(hmac.new(secret, check_string.encode(), hashlib.sha256).hexdigest(), received)

Не хотите считать HMAC самостоятельно — вызовите validateWebAppData. Живой пример — демо мини-приложение; в Chatto оно открывается кнопкой «Демо Mini App» в @botstudio.

Бот

getMe

GET · POST #

Возвращает User

Информация о боте. Удобно, чтобы проверить токен.

Без параметров.

curl "https://core.chatto.is/api/v1/bot/$TOKEN/getMe"

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/getMe",
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/getMe`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
});
console.log(await r.json());

Ответ — поле result

{
  "id": 42,
  "is_bot": true,
  "first_name": "Погода",
  "username": "weather_bot",
  "can_join_groups": true
}

Обновления

getUpdates

GET · POST #

Возвращает Array of Update

Long polling: возвращает накопившиеся обновления. Обновления с id меньше offset считаются подтверждёнными и удаляются. Не работает, пока установлен вебхук.

Параметр	Тип	Описание
offset необязательный	Integer	id первого нужного обновления (последний полученный update_id + 1)
limit необязательный	Integer	1–100, по умолчанию 100
timeout необязательный	Integer	Сколько секунд ждать новых обновлений (0–25)

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/getUpdates" \
  -H 'Content-Type: application/json' \
  -d '{
    "offset": 18,
    "timeout": 25
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/getUpdates",
  json={
    "offset": 18,
    "timeout": 25
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/getUpdates`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "offset": 18,
    "timeout": 25
  }),
});
console.log(await r.json());

Ответ — поле result

[
  {
    "update_id": 18,
    "message": {
      "message_id": 501,
      "text": "/start",
      "chat": {
        "id": 7,
        "type": "private"
      },
      "from": {
        "id": 8,
        "is_bot": false,
        "first_name": "Dias"
      },
      "date": 1759300000
    }
  }
]

setWebhook

GET · POST #

Возвращает True

Присылать обновления POST-запросом на ваш HTTPS-адрес. Ошибки доставки повторяются до 5 раз с паузой.

Параметр	Тип	Описание
url обязательный	String	HTTPS-адрес; пустая строка — снять вебхук
secret_token необязательный	String	Придёт в заголовке X-Chatto-Bot-Api-Secret-Token — проверяйте его
drop_pending_updates необязательный	Boolean	Удалить накопившиеся обновления

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/setWebhook" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/bot",
    "secret_token": "s3cret"
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/setWebhook",
  json={
    "url": "https://example.com/bot",
    "secret_token": "s3cret"
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/setWebhook`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "url": "https://example.com/bot",
    "secret_token": "s3cret"
  }),
});
console.log(await r.json());

Ответ — поле result

true

deleteWebhook

GET · POST #

Возвращает True

Снять вебхук и вернуться к getUpdates.

Параметр	Тип	Описание
drop_pending_updates необязательный	Boolean	Удалить накопившиеся обновления

curl "https://core.chatto.is/api/v1/bot/$TOKEN/deleteWebhook"

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/deleteWebhook",
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/deleteWebhook`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
});
console.log(await r.json());

Ответ — поле result

true

getWebhookInfo

GET · POST #

Возвращает WebhookInfo

Текущий вебхук, сколько обновлений ждёт доставки и последняя ошибка.

Без параметров.

curl "https://core.chatto.is/api/v1/bot/$TOKEN/getWebhookInfo"

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/getWebhookInfo",
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/getWebhookInfo`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
});
console.log(await r.json());

Ответ — поле result

{
  "url": "https://example.com/bot",
  "has_custom_certificate": false,
  "pending_update_count": 0
}

Сообщения

sendMessage

GET · POST #

Возвращает Message

Отправить сообщение в чат, где бот участник. Личный чат начинает пользователь.

Параметр	Тип	Описание
chat_id обязательный	Integer	id чата из message.chat.id
text обязательный	String	Текст, до 4096 символов. Поддерживается жирный, _курсив_, `код`
reply_to_message_id необязательный	Integer	Ответить на сообщение
reply_markup необязательный	InlineKeyboardMarkup	Кнопки под сообщением

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/sendMessage" \
  -H 'Content-Type: application/json' \
  -d '{
    "chat_id": 7,
    "text": "Привет! Выберите город",
    "reply_markup": {
      "inline_keyboard": [
        [
          {
            "text": "Москва",
            "callback_data": "city:msk"
          },
          {
            "text": "Сайт",
            "url": "https://chatto.is"
          }
        ]
      ]
    }
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/sendMessage",
  json={
    "chat_id": 7,
    "text": "Привет! Выберите город",
    "reply_markup": {
      "inline_keyboard": [
        [
          {
            "text": "Москва",
            "callback_data": "city:msk"
          },
          {
            "text": "Сайт",
            "url": "https://chatto.is"
          }
        ]
      ]
    }
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/sendMessage`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "chat_id": 7,
    "text": "Привет! Выберите город",
    "reply_markup": {
      "inline_keyboard": [
        [
          {
            "text": "Москва",
            "callback_data": "city:msk"
          },
          {
            "text": "Сайт",
            "url": "https://chatto.is"
          }
        ]
      ]
    }
  }),
});
console.log(await r.json());

Ответ — поле result

{
  "message_id": 777,
  "chat": {
    "id": 7,
    "type": "private"
  },
  "text": "Привет! Выберите город",
  "date": 1759300001
}

editMessageText

GET · POST #

Возвращает Message

Изменить текст своего сообщения. Без reply_markup кнопки убираются (как в Telegram).

Параметр	Тип	Описание
chat_id обязательный	Integer	id чата
message_id обязательный	Integer	id сообщения бота
text обязательный	String	Новый текст
reply_markup необязательный	InlineKeyboardMarkup	Новые кнопки

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/editMessageText" \
  -H 'Content-Type: application/json' \
  -d '{
    "chat_id": 7,
    "message_id": 777,
    "text": "Москва выбрана"
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/editMessageText",
  json={
    "chat_id": 7,
    "message_id": 777,
    "text": "Москва выбрана"
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/editMessageText`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "chat_id": 7,
    "message_id": 777,
    "text": "Москва выбрана"
  }),
});
console.log(await r.json());

Ответ — поле result

{
  "message_id": 777,
  "text": "Москва выбрана",
  "edit_date": 1759300009
}

editMessageReplyMarkup

GET · POST #

Возвращает Message

Заменить или убрать кнопки под сообщением бота.

Параметр	Тип	Описание
chat_id обязательный	Integer	id чата
message_id обязательный	Integer	id сообщения бота
reply_markup необязательный	InlineKeyboardMarkup	Пусто — убрать кнопки

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/editMessageReplyMarkup" \
  -H 'Content-Type: application/json' \
  -d '{
    "chat_id": 7,
    "message_id": 777
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/editMessageReplyMarkup",
  json={
    "chat_id": 7,
    "message_id": 777
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/editMessageReplyMarkup`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "chat_id": 7,
    "message_id": 777
  }),
});
console.log(await r.json());

Ответ — поле result

{
  "message_id": 777,
  "text": "Москва выбрана"
}

deleteMessage

GET · POST #

Возвращает True

Удалить сообщение у всех участников.

Параметр	Тип	Описание
chat_id обязательный	Integer	id чата
message_id обязательный	Integer	id сообщения

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/deleteMessage" \
  -H 'Content-Type: application/json' \
  -d '{
    "chat_id": 7,
    "message_id": 777
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/deleteMessage",
  json={
    "chat_id": 7,
    "message_id": 777
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/deleteMessage`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "chat_id": 7,
    "message_id": 777
  }),
});
console.log(await r.json());

Ответ — поле result

true

sendChatAction

GET · POST #

Возвращает True

Показать «печатает…» — пока бот готовит ответ.

Параметр	Тип	Описание
chat_id обязательный	Integer	id чата
action обязательный	String	typing \| upload_photo \| upload_document

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/sendChatAction" \
  -H 'Content-Type: application/json' \
  -d '{
    "chat_id": 7,
    "action": "typing"
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/sendChatAction",
  json={
    "chat_id": 7,
    "action": "typing"
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/sendChatAction`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "chat_id": 7,
    "action": "typing"
  }),
});
console.log(await r.json());

Ответ — поле result

true

Кнопки

answerCallbackQuery

GET · POST #

Возвращает True

Ответ на нажатие кнопки с callback_data. Пользователь видит текст всплывашкой (или окном при show_alert). Отвечайте в течение 5 секунд.

Параметр	Тип	Описание
callback_query_id обязательный	String	callback_query.id из обновления
text необязательный	String	До 200 символов
show_alert необязательный	Boolean	Окно вместо всплывашки
url необязательный	String	Открыть ссылку

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/answerCallbackQuery" \
  -H 'Content-Type: application/json' \
  -d '{
    "callback_query_id": "9b2e5c1a-…",
    "text": "Готово!"
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/answerCallbackQuery",
  json={
    "callback_query_id": "9b2e5c1a-…",
    "text": "Готово!"
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/answerCallbackQuery`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "callback_query_id": "9b2e5c1a-…",
    "text": "Готово!"
  }),
});
console.log(await r.json());

Ответ — поле result

true

Профиль бота

setMyCommands

GET · POST #

Возвращает True

Команды — подсказки при вводе «/» и в кнопке «Меню».

Параметр	Тип	Описание
commands обязательный	Array of BotCommand	До 100 команд: command (a–z, 0–9, _) и description

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/setMyCommands" \
  -H 'Content-Type: application/json' \
  -d '{
    "commands": [
      {
        "command": "start",
        "description": "Начать"
      },
      {
        "command": "weather",
        "description": "Погода сейчас"
      }
    ]
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/setMyCommands",
  json={
    "commands": [
      {
        "command": "start",
        "description": "Начать"
      },
      {
        "command": "weather",
        "description": "Погода сейчас"
      }
    ]
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/setMyCommands`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "commands": [
      {
        "command": "start",
        "description": "Начать"
      },
      {
        "command": "weather",
        "description": "Погода сейчас"
      }
    ]
  }),
});
console.log(await r.json());

Ответ — поле result

true

getMyCommands

GET · POST #

Возвращает Array of BotCommand

Текущие команды бота.

Без параметров.

curl "https://core.chatto.is/api/v1/bot/$TOKEN/getMyCommands"

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/getMyCommands",
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/getMyCommands`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
});
console.log(await r.json());

Ответ — поле result

[
  {
    "command": "start",
    "description": "Начать"
  }
]

deleteMyCommands

GET · POST #

Возвращает True

Убрать все команды.

Без параметров.

curl "https://core.chatto.is/api/v1/bot/$TOKEN/deleteMyCommands"

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/deleteMyCommands",
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/deleteMyCommands`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
});
console.log(await r.json());

Ответ — поле result

true

setMyName

GET · POST #

Возвращает True

Имя бота.

Параметр	Тип	Описание
name обязательный	String	До 64 символов

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/setMyName" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Погода"
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/setMyName",
  json={
    "name": "Погода"
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/setMyName`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "name": "Погода"
  }),
});
console.log(await r.json());

Ответ — поле result

true

setMyDescription

GET · POST #

Возвращает True

«Что умеет этот бот?» — показывается в пустом чате перед «Запустить».

Параметр	Тип	Описание
description необязательный	String	До 512 символов

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/setMyDescription" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Прогноз погоды на неделю для любого города"
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/setMyDescription",
  json={
    "description": "Прогноз погоды на неделю для любого города"
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/setMyDescription`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "description": "Прогноз погоды на неделю для любого города"
  }),
});
console.log(await r.json());

Ответ — поле result

true

setMyShortDescription

GET · POST #

Возвращает True

Коротко о боте — в профиле и поиске.

Параметр	Тип	Описание
short_description необязательный	String	До 120 символов

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/setMyShortDescription" \
  -H 'Content-Type: application/json' \
  -d '{
    "short_description": "Погода в любом городе"
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/setMyShortDescription",
  json={
    "short_description": "Погода в любом городе"
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/setMyShortDescription`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "short_description": "Погода в любом городе"
  }),
});
console.log(await r.json());

Ответ — поле result

true

setChatMenuButton

GET · POST #

Возвращает True

Кнопка слева от поля ввода: список команд или ваш веб-сайт.

Параметр	Тип	Описание
menu_button обязательный	MenuButton	{"type": "commands"} или {"type": "web_app", "text": "Открыть", "web_app": {"url": "https://…"}}

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/setChatMenuButton" \
  -H 'Content-Type: application/json' \
  -d '{
    "menu_button": {
      "type": "web_app",
      "text": "Открыть",
      "web_app": {
        "url": "https://example.com"
      }
    }
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/setChatMenuButton",
  json={
    "menu_button": {
      "type": "web_app",
      "text": "Открыть",
      "web_app": {
        "url": "https://example.com"
      }
    }
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/setChatMenuButton`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "menu_button": {
      "type": "web_app",
      "text": "Открыть",
      "web_app": {
        "url": "https://example.com"
      }
    }
  }),
});
console.log(await r.json());

Ответ — поле result

true

getChatMenuButton

GET · POST #

Возвращает MenuButton

Текущая кнопка меню.

Без параметров.

curl "https://core.chatto.is/api/v1/bot/$TOKEN/getChatMenuButton"

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/getChatMenuButton",
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/getChatMenuButton`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
});
console.log(await r.json());

Ответ — поле result

{
  "type": "web_app",
  "text": "Открыть",
  "web_app": {
    "url": "https://example.com"
  }
}

Mini Apps

setMainWebApp

GET · POST #

Возвращает True

Главное мини-приложение бота: кнопка «Открыть» в профиле и ссылки chatto.is/app/{бот}?startapp=…. Пустой url — убрать.

Параметр	Тип	Описание
url необязательный	String	HTTPS-адрес приложения

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/setMainWebApp" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://shop.example/app"
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/setMainWebApp",
  json={
    "url": "https://shop.example/app"
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/setMainWebApp`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "url": "https://shop.example/app"
  }),
});
console.log(await r.json());

Ответ — поле result

true

answerWebAppQuery

GET · POST #

Возвращает SentWebAppMessage

Ответить на запрос мини-приложения: сообщение от бота придёт в чат с пользователем. query_id — из initData.

Параметр	Тип	Описание
web_app_query_id обязательный	String	query_id из initData
result обязательный	InlineQueryResult	{"type": "article", "id": "1", "title": "…", "input_message_content": {"message_text": "…"}, "reply_markup": {…}}

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/answerWebAppQuery" \
  -H 'Content-Type: application/json' \
  -d '{
    "web_app_query_id": "AAHdF6IQAAAAAN0XohDhrOrc",
    "result": {
      "type": "article",
      "id": "1",
      "title": "Заказ",
      "input_message_content": {
        "message_text": "Заказ №42 оформлен"
      }
    }
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/answerWebAppQuery",
  json={
    "web_app_query_id": "AAHdF6IQAAAAAN0XohDhrOrc",
    "result": {
      "type": "article",
      "id": "1",
      "title": "Заказ",
      "input_message_content": {
        "message_text": "Заказ №42 оформлен"
      }
    }
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/answerWebAppQuery`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "web_app_query_id": "AAHdF6IQAAAAAN0XohDhrOrc",
    "result": {
      "type": "article",
      "id": "1",
      "title": "Заказ",
      "input_message_content": {
        "message_text": "Заказ №42 оформлен"
      }
    }
  }),
});
console.log(await r.json());

Ответ — поле result

{
  "inline_message_id": "1024"
}

validateWebAppData

GET · POST #

Возвращает Object

Проверить подпись initData на стороне Chatto — если не хочется считать HMAC самостоятельно. Подпись действительна 24 часа.

Параметр	Тип	Описание
init_data обязательный	String	Строка Chatto.WebApp.initData, как есть

curl -X POST "https://core.chatto.is/api/v1/bot/$TOKEN/validateWebAppData" \
  -H 'Content-Type: application/json' \
  -d '{
    "init_data": "query_id=AAHd…&user=%7B%22id%22%3A7%7D&auth_date=1790000000&hash=c5f3…"
  }'

import requests

r = requests.post(
  f"{BASE}/bot/{TOKEN}/validateWebAppData",
  json={
    "init_data": "query_id=AAHd…&user=%7B%22id%22%3A7%7D&auth_date=1790000000&hash=c5f3…"
  },
)
print(r.json())

const r = await fetch(`${BASE}/bot/${TOKEN}/validateWebAppData`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "init_data": "query_id=AAHd…&user=%7B%22id%22%3A7%7D&auth_date=1790000000&hash=c5f3…"
  }),
});
console.log(await r.json());

Ответ — поле result

{
  "valid": true,
  "data": {
    "query_id": "AAHd…",
    "user": {
      "id": 7,
      "first_name": "Анна"
    },
    "auth_date": "1790000000"
  }
}

Объекты

Поля, которые приходят в обновлениях и ответах.

Update

Поле	Тип	Описание
update_id	Integer	Возрастающий идентификатор обновления
message	Message	Новое сообщение боту (или web_app_data из мини-приложения)
callback_query	CallbackQuery	Нажатие кнопки

Message

Поле	Тип	Описание
message_id	Integer	Идентификатор сообщения
from	User	Отправитель
chat	Chat	Чат
date	Integer	Время отправки, Unix
edit_date	Integer	Время изменения
text	String	Текст
reply_to_message	Message	Сообщение, на которое ответили (message_id, text)
reply_markup	InlineKeyboardMarkup	Кнопки
web_app_data	WebAppData	Данные из мини-приложения

User

Поле	Тип	Описание
id	Integer	Идентификатор пользователя
is_bot	Boolean	Это бот
first_name	String	Имя
username	String	Имя пользователя без @
language_code	String	Язык интерфейса

Chat

Поле	Тип	Описание
id	Integer	Идентификатор чата — используйте как chat_id
type	String	private, group или channel
title	String	Название группы

CallbackQuery

Поле	Тип	Описание
id	String	Для answerCallbackQuery
from	User	Кто нажал
message	Message	Сообщение с кнопкой
data	String	callback_data кнопки

InlineKeyboardButton

Поле	Тип	Описание
text	String	Подпись, до 64 символов
url	String	Открыть ссылку
callback_data	String	До 64 байт, придёт боту
web_app	WebAppInfo	{"url": "https://…"} — открыть мини-приложение

WebAppData

Поле	Тип	Описание
data	String	Строка из Chatto.WebApp.sendData
button_text	String	Подпись кнопки, если была

Ошибки

При ошибке приходит ok: false, код и описание.

Код	Когда возникает
400	Неверные параметры, чат не найден, бот не участник чата, некорректные кнопки
401	Неверный или перевыпущенный токен
403	Пользователь заблокировал бота
404	Неизвестный метод
409	`getUpdates` при активном вебхуке
429	Слишком много запросов — повторите позже

Лимиты

Что	Ограничение
Запросы к API	до 30 в секунду на бота
Текст сообщения	до 4096 символов
Кнопки	до 10 рядов по 8 кнопок, callback_data до 64 байт
Ответ на нажатие кнопки	5 секунд
Ботов на аккаунт	до 20
Повторы вебхука	до 5 попыток: через 5 с, 30 с, 2 мин, 10 мин
Подпись initData	действительна 24 часа

Примеры ботов

Готовые заготовки — подставьте токен и запустите.

Python — эхо-бот на long polling

import requests

BASE = "https://core.chatto.is/api/v1"
TOKEN = "123:AbC..."
api = lambda m, **p: requests.post(
    f"{BASE}/bot/{TOKEN}/{m}", json=p, timeout=35).json()

offset = 0
while True:
    for u in api("getUpdates", offset=offset, timeout=25)["result"]:
        offset = u["update_id"] + 1
        msg = u.get("message")
        if msg:
            api("sendMessage", chat_id=msg["chat"]["id"],
                text="Вы написали: " + (msg.get("text") or ""))

Node.js — вебхук с кнопками (Express)

import express from 'express';
const BASE = 'https://core.chatto.is/api/v1', TOKEN = '123:AbC...';
const api = (m, body) => fetch(`${BASE}/bot/${TOKEN}/${m}`, {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(body) });

const app = express().use(express.json());
app.post('/bot', async (req, res) => {
  if (req.get('X-Chatto-Bot-Api-Secret-Token') !== 's3cret') return res.sendStatus(403);
  const { message, callback_query: q } = req.body;
  if (message) await api('sendMessage', { chat_id: message.chat.id, text: 'Как дела?',
    reply_markup: { inline_keyboard: [[{ text: 'Отлично', callback_data: 'ok' }]] } });
  if (q) await api('answerCallbackQuery', { callback_query_id: q.id, text: 'Принято' });
  res.sendStatus(200);
});
app.listen(3000);

Создайте бота

Получите токен

Подключите сервер

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

Запросы и ответы

Успех

Ошибка

Получение обновлений

Long polling

Вебхук

Кнопки под сообщениями

Mini Apps

Как открыть мини-приложение

Подключение SDK

Возможности SDK

Проверка initData на сервере

Бот

getMe

Обновления

getUpdates

setWebhook

deleteWebhook

getWebhookInfo

Сообщения

sendMessage

editMessageText

editMessageReplyMarkup

deleteMessage

sendChatAction

Кнопки

answerCallbackQuery

Профиль бота

setMyCommands

getMyCommands

deleteMyCommands

setMyName

setMyDescription

setMyShortDescription

setChatMenuButton

getChatMenuButton

Mini Apps

setMainWebApp

answerWebAppQuery

validateWebAppData

Объекты

Update

Message

User

Chat

CallbackQuery

InlineKeyboardButton

WebAppData

Ошибки

Лимиты

Примеры ботов