CytaraBot API

Bot API

HTTP-интерфейс для ботов Cytara. Бот авторизуется токеном, забирает входящие методом getUpdates и отвечает методом sendMessage.

1. Создать бота

Ботов создаёт служебный бот «Гефест» прямо в приложении:

2. Базовый URL

https://api.cytara.space/bot/<TOKEN>/<METHOD>

Пример: https://api.cytara.space/bot/17:a42a4c…/getMe. Работают GET и POST. Параметры передавай в query или в JSON-теле.

3. Формат ответа

Все методы возвращают JSON-конверт:

{ "ok": true, "result": ... }        // успех
{ "ok": false, "error_code": 401, "description": "Unauthorized" }  // ошибка

4. Методы

getMe

Информация о боте.

curl https://api.cytara.space/bot/<TOKEN>/getMe

{ "ok": true, "result": { "id": 17, "is_bot": true, "first_name": "TestBot", "username": "test_bot" } }

getUpdates

Входящие сообщения боту. Параметры:

Параметр	Тип	Описание
offset	int	Вернуть апдейты с update_id ≥ offset. Для подтверждения передавай last_update_id + 1.
limit	int	Сколько вернуть (1-100, по умолчанию 100).
timeout	int	Long-poll: сколько секунд держать запрос, ожидая новые апдейты (0-50, по умолчанию 0). Снижает частоту опроса.

curl "https://api.cytara.space/bot/<TOKEN>/getUpdates?offset=0"

{ "ok": true, "result": [
  { "update_id": 1665,
    "message": {
      "message_id": 1665,
      "from": { "id": 5, "first_name": "Лор", "username": "lor", "is_bot": false },
      "chat": { "id": 10, "type": "private" },
      "date": 1779993988,
      "text": "привет, бот!"
    }
  }
] }

chat.id из апдейта используй как chat_id при ответе.

sendMessage

Отправить сообщение в чат. Параметры:

Параметр	Тип	Описание
chat_id	int	Обязательный. ID чата (из chat.id апдейта).
text	string	Обязательный. Текст сообщения.
reply_to_message_id	int	Необязательный. Ответить на сообщение.

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

sendPhoto

Отправить фото по публичному URL (сервер скачает картинку к себе). Параметры:

Параметр	Тип	Описание
chat_id	int	Обязательный. ID чата.
photo	string	Обязательный. Публичный http(s) URL картинки (до 25 МБ).
caption	string	Необязательный. Подпись под фото.

curl -X POST https://api.cytara.space/bot/<TOKEN>/sendPhoto \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 10, "photo": "https://example.com/cat.jpg", "caption": "Котик"}'

sendChatAction

Показать статус «печатает…» в чате. Параметры:

Параметр	Тип	Описание
chat_id	int	Обязательный. ID чата.
action	string	typing показать индикатор, cancel убрать. По умолчанию typing.

curl -X POST https://api.cytara.space/bot/<TOKEN>/sendChatAction \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 10, "action": "typing"}'

5. Пример бота Python

import time, requests

BASE = "https://api.cytara.space/bot/<TOKEN>"
offset = 0
while True:
    r = requests.get(f"{BASE}/getUpdates", params={"offset": offset}).json()
    for u in r.get("result", []):
        offset = u["update_id"] + 1
        msg = u["message"]
        text = msg.get("text", "")
        requests.post(f"{BASE}/sendMessage", json={
            "chat_id": msg["chat"]["id"],
            "text": f"Ты написал: {text}"
        })
    time.sleep(1)

Скоро

Вебхуки (setWebhook), отправка медиа (sendPhoto), long-polling timeout, inline-кнопки, команды.