Lichi Bot API
HTTP-API для ботов Lichi. Совместим с Telegram Bot API по форме запросов и ответов — если вы делали ботов для Telegram, здесь всё знакомо.
base URL ·https://lichi.chat
Обзор
Бот — это обычный аккаунт Lichi, которым управляет программа по токену. Бот может отправлять и получать сообщения, медиа и голосовые, показывать кнопки под сообщениями, отвечать на нажатия и на inline-запросы (@бот запрос в любом чате).
Все запросы: POST https://lichi.chat/bot<ПУТЬ> — точнее /bot/<token>/<method>. Ответ всегда JSON вида:
{"ok": true, "result": …}
{"ok": false, "error_code": 400, "description": "…"}
Создать бота
Напишите системному боту @botfather в приложении Lichi команду /newbot, задайте имя и @username — в ответ получите токен вида <botUID>:<secret>. Храните его в секрете; /revoke перевыпускает токен.
/newbot, /mybots, /revoke, /help.Токен и запросы
Токен встраивается прямо в путь. Тело — JSON (для медиа — multipart/form-data).
curl -X POST https://lichi.chat/bot/<token>/sendMessage \
-H 'Content-Type: application/json' \
-d '{"chat_id":"<userUID или @username>","text":"Привет!"}'
Адрес чата (chat_id)
Во все методы отправки chat_id — это получатель. Принимаются две формы:
| Форма | Пример | Когда |
|---|---|---|
| UID | u_8f3a… | Точный id пользователя (из from входящего апдейта — самый надёжный способ ответить) |
@username | @alice | По публичному юзернейму; сервер резолвит его в UID |
chat_id из update.message.from — так бот пишет именно тому, кто ему написал, без резолва юзернейма.Получение апдейтов
Бот получает входящие через long-poll getUpdates: держите открытый запрос, сервер отвечает, как только есть новое (или по таймауту). Подтверждение — через offset (как в Telegram): передавайте offset = max(update_id)+1, это удаляет подтверждённые апдейты.
getUpdates. Два параллельных поллера получат дубли (у каждого свой курсор).Ошибки
При ошибке ответ — {"ok":false} с HTTP-статусом и тем же числом в error_code, плюс человекочитаемое description:
{"ok":false,"error_code":400,"description":"chat not found"}
| Код | Значение | Примеры description |
|---|---|---|
400 | Неверный запрос | chat_id and text required, chat not found, bad_multipart, not_an_image |
401 | Неверный токен | unauthorized |
404 | Нет метода / пути | unknown_method: …, bad_path |
500 | Сбой на сервере | send_failed, edit_failed |
503 | Сервис не готов | not_configured, media_not_configured |
Методы
POST getMe
Личность бота. Без параметров.
{"ok":true,"result":{"id":"<botUID>","is_bot":true,"username":"mybot","first_name":"My Bot"}}
POST sendMessage
| Поле | Тип | Описание |
|---|---|---|
chat_id | string | UID получателя или @username |
text | string | Текст сообщения |
reply_markup | InlineKeyboard? | Кнопки под сообщением (необязательно) |
{"chat_id":"@alice","text":"Меню:",
"reply_markup":{"inline_keyboard":[
[{"text":"Сайт","url":"https://lichi.chat"}],
[{"text":"Пинг","callback_data":"ping","color":"#2ea6ff"}]
]}}
POST sendPhoto · sendDocument · sendVideo · sendVoice
multipart/form-data: поле chat_id, необязательный caption, и файл. Для sendVoice добавьте duration (мс) — тогда клиент рисует голосовой пузырь с волной.
curl -X POST https://lichi.chat/bot/<token>/sendPhoto \
-F chat_id=@alice -F caption='смотри' -F photo=@pic.png
POST getUpdates
| Поле | Тип | Описание |
|---|---|---|
offset | int | Подтверждает всё < offset, возвращает >= offset |
timeout | int | Секунды ожидания (0–50), long-poll |
В result — массив Update:
{"ok":true,"result":[
{"update_id":42,"message":{"msg_id":"…","from":"u_alice","to":"<botUID>",
"text":"/start","created_at":1732200000}},
{"update_id":43,"callback_query":{"id":"…","from":"u_alice",
"message_id":"…","data":"ping"}}
]}
limit ограничен сотней за запрос. Пустой result — это нормальный ответ по таймауту long-poll, повторяйте запрос.
POST setMyCommands · getMyCommands
Список команд для меню «/». Клиент показывает его, когда пользователь набирает / в чате с ботом.
{"commands":[{"command":"start","description":"Запустить"},
{"command":"help","description":"Помощь"}]}
POST answerCallbackQuery
Ответ на нажатие callback_data-кнопки (приходит как callback_query в Update). Показывает пользователю всплывающее уведомление.
| Поле | Тип | Описание |
|---|---|---|
callback_query_id | string | id из callback_query |
text | string | Текст всплывашки |
show_alert | bool | Модальное окно вместо тоста |
POST answerInlineQuery
Ответ на inline-запрос (пользователь набрал @бот запрос в любом чате — приходит как inline_query). Верните список результатов; пользователь выберет один, и он отправится в чат.
{"inline_query_id":"<id>","results":[
{"type":"article","id":"1","title":"Отправить","message_text":"текст"},
{"type":"gif","id":"2","title":"гифка","url":"https://…/a.mp4","thumb_url":"https://…/a.jpg"}
]}
POST editMessageText · editMessageReplyMarkup
Правит отправленное ботом сообщение и его кнопки «на месте» — так делается навигация по меню (нажал кнопку → текст и кнопки поменялись).
| Поле | Тип | Описание |
|---|---|---|
chat_id | string | Кому было отправлено |
message_id | string | id сообщения (из result при отправке) |
text | string | Новый текст (для editMessageText) |
reply_markup | InlineKeyboard? | Новые кнопки (null — убрать) |
Типы
InlineKeyboard
Сетка кнопок (ряды). У кнопки ровно одно действие: url (открыть ссылку) или callback_data (прислать боту нажатие). color — необязательная подсветка (расширение Lichi сверх TG).
{"inline_keyboard":[
[{"text":"Ссылка","url":"https://lichi.chat"}],
[{"text":"−","callback_data":"dec"},{"text":"+","callback_data":"inc","color":"#2ea6ff"}]
]}
Message
Сообщение — то, что приходит в update.message и возвращается в result при отправке.
| Поле | Тип | Описание |
|---|---|---|
msg_id | string | Id сообщения (для editMessage*, reply_to) |
from | string | UID отправителя |
to | string | UID получателя |
text | string | Текст (пусто для чистого медиа) |
created_at | int | Unix-время (секунды) |
media | MediaRef[]? | Вложения (фото/видео/файл/голос) |
reply_to | string? | msg_id, на который отвечают |
reply_markup | InlineKeyboard? | Кнопки под сообщением |
MediaRef
Одно вложение. Скачивается по media/<ownerUID>/<id>.
| Поле | Тип | Описание |
|---|---|---|
id | string | Id объекта |
content_type | string | MIME, напр. image/jpeg, audio/ogg |
width / height | int? | Размер для фото/видео |
size | int? | Байт |
duration_ms | int? | Длительность голоса/видео, мс |
Update
Элемент из getUpdates. Заполнено ровно одно из полей message / callback_query / inline_query.
| Поле | Тип | Описание |
|---|---|---|
update_id | int | Монотонный id (для offset) |
message | Message | Входящее сообщение |
callback_query | object | Нажата кнопка: {id, from, message_id, data} |
inline_query | object | Набран @бот запрос: {id, from, query, offset} |
Go SDK
Готовый клиент bonding/sdk/lichibot скрывает long-poll за колбэком:
c := lichibot.New("https://lichi.chat", token)
c.Run(ctx, func(c *lichibot.Client, u lichibot.Update) {
if u.Message != nil && u.Message.Text != "" {
_ = c.SendMessage(ctx, u.Message.From, "echo: "+u.Message.Text)
}
})
Методы: GetMe, SendMessage/SendMessageMarkup, SendPhoto/SendDocument/SendVoice, GetUpdates, SetCommands, AnswerCallback, AnswerInlineQuery, EditMessageText/EditMessageReplyMarkup.