# NovCord Bot API

Telegram-подобный HTTP API для ботов NovCord. Боты **хостятся тобой**: запускаешь скрипт на своём ПК/сервере — бот работает, пока скрипт запущен. Сервер NovCord только отдаёт API.

> **v1: только личные сообщения (DM).** Серверные каналы — позже.

- **Base URL:** `https://novcord.online/bot/api`
- **Формат ответов:** как в Telegram — `{ "ok": true, "result": ... }` при успехе, `{ "ok": false, "error_code": <int>, "description": "<str>" }` при ошибке.
- **Питон-библиотека:** `pip install novcord-bot` → `import novcord` (см. раздел в конце).

---

## Содержание

1. [Получение бота и токена](#получение-бота-и-токена)
2. [Авторизация](#авторизация)
3. [Что такое chat_id](#что-такое-chat_id)
4. [Методы](#методы)
5. [Объект Update](#объект-update)
6. [Inline-кнопки (reply_markup)](#inline-кнопки-reply_markup)
7. [Первый бот за 5 минут](#первый-бот-за-5-минут)
8. [Лимиты](#лимиты)

---

## Получение бота и токена

1. Открой приложение NovCord → **Настройки → Мои боты**.
2. Нажми **Создать бота**, задай имя.
3. Скопируй **токен** (формат `botId:secret`). Его можно показать/перевыпустить там же.

Токен — это пароль бота. Не публикуй его. Если засветил — перевыпусти.

---

## Авторизация

Токен передаётся в заголовке каждого запроса:

```
Authorization: Bearer <ТОКЕН>
```

(альтернативно — заголовок `X-Bot-Token: <ТОКЕН>`).

---

## Что такое chat_id

В методах отправки `chat_id` — это **id пользователя** (поле `from.id` из апдейта), а **не** id диалога (`chat.id`).

Самый простой способ узнать `chat_id`: пользователь пишет боту в ЛС, бот получает апдейт через `getUpdates`, и берёт `from.id` — это и есть `chat_id` для ответа.

---

## Методы

### getMe

`GET /bot/api/getMe` — информация о боте.

```bash
curl -s -H "Authorization: Bearer ТОКЕН" \
  https://novcord.online/bot/api/getMe
```

Ответ:
```json
{ "ok": true, "result": {
  "id": "0be9c372", "is_bot": true,
  "username": "my_bot", "first_name": "My Bot",
  "about": "", "bot_id": "bot_xxx"
}}
```

---

### sendMessage

`POST /bot/api/sendMessage` — отправить текстовое сообщение.

| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| `chat_id` | string | да | id пользователя |
| `text` | string | да | текст сообщения |
| `reply_markup` | object | нет | inline-клавиатура |
| `reply_to_message_id` | string | нет | id сообщения, на которое отвечаем |

```bash
curl -s -X POST https://novcord.online/bot/api/sendMessage \
  -H "Authorization: Bearer ТОКЕН" -H "Content-Type: application/json" \
  -d '{"chat_id":"0be9c372","text":"Привет!"}'
```

```python
await bot.send_message("0be9c372", "Привет!")
```

---

### sendPhoto

`POST /bot/api/sendPhoto` — отправить изображение. Либо multipart-файл (`file`), либо ссылка (`file_url`).

| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| `chat_id` | string | да | id пользователя |
| `file` | multipart | * | файл картинки |
| `file_url` | string | * | или прямая ссылка на картинку |
| `caption` | string | нет | подпись |
| `reply_markup` | object | нет | inline-клавиатура |

`*` нужен либо `file`, либо `file_url`.

```bash
# файлом
curl -s -X POST https://novcord.online/bot/api/sendPhoto \
  -H "Authorization: Bearer ТОКЕН" \
  -F "chat_id=0be9c372" -F "caption=Котик" -F "file=@cat.jpg"

# по ссылке
curl -s -X POST https://novcord.online/bot/api/sendPhoto \
  -H "Authorization: Bearer ТОКЕН" -H "Content-Type: application/json" \
  -d '{"chat_id":"0be9c372","file_url":"https://example.com/cat.jpg"}'
```

```python
await bot.send_photo("0be9c372", photo="cat.jpg", caption="Котик")
await bot.send_photo("0be9c372", file_url="https://example.com/cat.jpg")
```

---

### sendDocument

`POST /bot/api/sendDocument` — отправить любой файл. Параметры как у `sendPhoto` (поле `document` / `file_url`).

```bash
curl -s -X POST https://novcord.online/bot/api/sendDocument \
  -H "Authorization: Bearer ТОКЕН" \
  -F "chat_id=0be9c372" -F "file=@report.pdf"
```

```python
await bot.send_document("0be9c372", document="report.pdf")
```

---

### getUpdates

`GET /bot/api/getUpdates` — получить новые апдейты (long-polling).

| Параметр | Тип | По умолч. | Описание |
|---|---|---|---|
| `offset` | int | 0 | вернуть апдейты с `update_id >= offset`; подтверждает (удаляет) все с меньшим id |
| `limit` | int | 100 | макс. число апдейтов (≤100) |
| `timeout` | int | 25 | сколько секунд держать соединение, если апдейтов нет (≤50) |

Принцип: храни `offset = последний update_id + 1`. Передавая его, ты одновременно подтверждаешь обработанные апдейты (они удаляются с сервера) и получаешь только новые.

```bash
curl -s -H "Authorization: Bearer ТОКЕН" \
  "https://novcord.online/bot/api/getUpdates?offset=0&timeout=25"
```

Ответ — массив [Update](#объект-update):
```json
{ "ok": true, "result": [
  { "update_id": 5, "message": {
    "message_id": "dmsg_...", "date": 1780843876,
    "chat": { "id": "dm_2a180b0c", "type": "private" },
    "from": { "id": "0be9c372", "is_bot": false, "username": "dev1xy", "first_name": "девикс" },
    "text": "привет", "type": "text"
  }}
]}
```

---

### editMessageText

`POST /bot/api/editMessageText` — изменить текст (и клавиатуру) своего сообщения.

| Параметр | Тип | Обяз. |
|---|---|---|
| `chat_id` | string | да |
| `message_id` | string | да |
| `text` | string | да |
| `reply_markup` | object | нет |

```bash
curl -s -X POST https://novcord.online/bot/api/editMessageText \
  -H "Authorization: Bearer ТОКЕН" -H "Content-Type: application/json" \
  -d '{"chat_id":"0be9c372","message_id":"dmsg_...","text":"Обновлённый текст"}'
```

```python
await bot.edit_message_text("0be9c372", "dmsg_...", "Обновлённый текст")
```

---

### deleteMessage

`POST /bot/api/deleteMessage` — удалить своё сообщение.

```bash
curl -s -X POST https://novcord.online/bot/api/deleteMessage \
  -H "Authorization: Bearer ТОКЕН" -H "Content-Type: application/json" \
  -d '{"chat_id":"0be9c372","message_id":"dmsg_..."}'
```

```python
await bot.delete_message("0be9c372", "dmsg_...")
```

---

### answerCallbackQuery

`POST /bot/api/answerCallbackQuery` — подтвердить нажатие inline-кнопки.

| Параметр | Тип | Обяз. |
|---|---|---|
| `callback_query_id` | string | да |
| `text` | string | нет |

> В v1 это просто подтверждение приёма. Чтобы реально отреагировать на нажатие — отправь новое сообщение (`sendMessage`) или измени текущее (`editMessageText`).

```python
await callback.answer("Принято!")
```

---

### setMyCommands / getMyCommands

`POST /bot/api/setMyCommands` — задать список команд бота. `GET /bot/api/getMyCommands` — получить его.

```bash
curl -s -X POST https://novcord.online/bot/api/setMyCommands \
  -H "Authorization: Bearer ТОКЕН" -H "Content-Type: application/json" \
  -d '{"commands":[{"command":"start","description":"Запуск"}]}'
```

```python
await bot.set_my_commands([("start", "Запуск")])
```

---

## Объект Update

`getUpdates` возвращает массив объектов. У каждого есть `update_id` и **одно** из полей: `message` или `callback_query`.

### Update с message
```json
{
  "update_id": 5,
  "message": {
    "message_id": "dmsg_...",
    "date": 1780843876,
    "chat": { "id": "dm_...", "type": "private" },
    "from": { "id": "<userId>", "is_bot": false, "username": "...", "first_name": "..." },
    "text": "текст",
    "type": "text",
    "file_url": null,
    "file_name": null,
    "reply_to_message_id": null
  }
}
```

### Update с callback_query (нажата inline-кнопка)
```json
{
  "update_id": 6,
  "callback_query": {
    "id": "6",
    "from": { "id": "<userId>", "is_bot": false, "username": "...", "first_name": "..." },
    "message": { "message_id": "dmsg_...", "chat": { "id": "dm_...", "type": "private" } },
    "data": "значение_callback_data"
  }
}
```

---

## Inline-кнопки (reply_markup)

`reply_markup` — объект с массивом рядов кнопок:

```json
{
  "inline_keyboard": [
    [ { "text": "Вариант A", "callback_data": "a" },
      { "text": "Вариант B", "callback_data": "b" } ],
    [ { "text": "Открыть сайт", "url": "https://novcord.online" } ]
  ]
}
```

- кнопка с `callback_data` — при нажатии бот получит `callback_query` с этим `data`;
- кнопка с `url` — открывает ссылку.

```bash
curl -s -X POST https://novcord.online/bot/api/sendMessage \
  -H "Authorization: Bearer ТОКЕН" -H "Content-Type: application/json" \
  -d '{"chat_id":"0be9c372","text":"Выбери:","reply_markup":{"inline_keyboard":[[{"text":"A","callback_data":"a"},{"text":"B","callback_data":"b"}]]}}'
```

---

## Первый бот за 5 минут

На чистом HTTP (curl) можно всё, но проще — через официальную Python-библиотеку.

```bash
pip install novcord-bot
```

```python
import asyncio
from novcord import Bot, Dispatcher, Router, F
from novcord.filters import Command
from novcord.keyboard import InlineKeyboardBuilder

dp = Dispatcher()
router = Router()
dp.include_router(router)

@router.message(Command("start"))
async def start(message):
    kb = InlineKeyboardBuilder()
    kb.button(text="Нажми меня", callback_data="hi")
    kb.button(text="Сайт", url="https://novcord.online")
    await message.answer("Привет! Я бот на novcord 🤖", reply_markup=kb.as_markup())

@router.callback_query(F.data == "hi")
async def hi(query):
    await query.answer("Принято!")
    await query.message.answer("Ты нажал кнопку 👍")

@router.message(F.text)
async def echo(message):
    await message.answer(f"Ты написал: {message.text}")

async def main():
    bot = Bot("ВСТАВЬ_ТОКЕН")   # Настройки → Мои боты
    await dp.start_polling(bot)

asyncio.run(main())
```

Запусти скрипт (`python bot.py`), затем в приложении найди бота в поиске → **Написать** → отправь `/start`. Бот ответит с кнопками, на текст будет эхо.

Подробности библиотеки (фильтры `F`, FSM, все методы) — в README пакета.

---

## Лимиты

- v1 — только личные сообщения (DM).
- До **20 ботов** на пользователя.
- Загрузка файлов ботом — до **50 МБ**.
- `getUpdates` держит соединение до **50 секунд** (long-poll).
- Бот «онлайн», только пока запущен твой скрипт.