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 перевыпускает токен.

@botfather умеет: /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 — это получатель. Принимаются две формы:

ФормаПримерКогда
UIDu_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_idstringUID получателя или @username
textstringТекст сообщения
reply_markupInlineKeyboard?Кнопки под сообщением (необязательно)
{"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

ПолеТипОписание
offsetintПодтверждает всё < offset, возвращает >= offset
timeoutintСекунды ожидания (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_idstringid из callback_query
textstringТекст всплывашки
show_alertboolМодальное окно вместо тоста

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_idstringКому было отправлено
message_idstringid сообщения (из result при отправке)
textstringНовый текст (для editMessageText)
reply_markupInlineKeyboard?Новые кнопки (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_idstringId сообщения (для editMessage*, reply_to)
fromstringUID отправителя
tostringUID получателя
textstringТекст (пусто для чистого медиа)
created_atintUnix-время (секунды)
mediaMediaRef[]?Вложения (фото/видео/файл/голос)
reply_tostring?msg_id, на который отвечают
reply_markupInlineKeyboard?Кнопки под сообщением

MediaRef

Одно вложение. Скачивается по media/<ownerUID>/<id>.

ПолеТипОписание
idstringId объекта
content_typestringMIME, напр. image/jpeg, audio/ogg
width / heightint?Размер для фото/видео
sizeint?Байт
duration_msint?Длительность голоса/видео, мс

Update

Элемент из getUpdates. Заполнено ровно одно из полей message / callback_query / inline_query.

ПолеТипОписание
update_idintМонотонный id (для offset)
messageMessageВходящее сообщение
callback_queryobjectНажата кнопка: {id, from, message_id, data}
inline_queryobjectНабран @бот запрос: {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.