ZNAKORA Bot API: руководство разработчика

Для автоматизации собственного профиля на Python используйте Userbot API и Python SDK. О возможностях мессенджера читайте на странице ZNAKORA.

Добро пожаловать в документацию Znakora Bot API 4.0. Это HTTP-интерфейс, который позволяет подключать ботов к нашей системе обмена сообщениями. Боты могут отправлять текстовые сообщения, медиафайлы, использовать интерактивные кнопки и реагировать на действия пользователей.

Базовый URL для всех запросов:

https://znakora.ru/api/bot<TOKEN>/METHOD_NAME

Все запросы должны выполняться методом POST. Параметры можно передавать как JSON.

Авторизация

Каждый бот идентифицируется токеном, который выдается при его создании. Токен выглядит примерно так: 123456:AAHE....

Как получить токен:

  1. Откройте приложение Znakora.
  2. Нажмите кнопку создания чата (+).
  3. Выберите тип "Бот".
  4. Укажите имя и уникальную ссылку (должна заканчиваться на _bot).
  5. Скопируйте токен из одноразового окна сразу после создания бота.

Полный пример (Python)

Простой Echo-бот, который отвечает на команды и пересылает текст обратно. Использует библиотеку requests.

import requests import time # Вставьте сюда ваш токен TOKEN = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" API_URL = f"https://znakora.ru/api/bot{TOKEN}" def api(method, data=None): try: url = f"{API_URL}/{method}" res = requests.post(url, json=data) return res.json() except Exception as e: print(f"Ошибка соединения: {e}") return {} # 1. Удаляем вебхук, чтобы использовать Long Polling api("deleteWebhook") print("Бот запущен...") while True: try: # Запрос обновлений (Long Polling) updates = api("getUpdates") if updates.get("result"): for u in updates["result"]: # Если пришло сообщение if "message" in u: msg = u["message"] chat_id = msg["chat"]["id"] text = msg.get("text", "") if text == "/start": api("sendMessage", { "chat_id": chat_id, "text": "Привет! Я бот Znakora." }) else: api("sendMessage", { "chat_id": chat_id, "text": f"Вы написали: {text}" }) except Exception as e: time.sleep(5)

Методы: Сообщения

POST sendMessage

Используйте этот метод для отправки текстовых сообщений.

ПараметрТипОписание
chat_id Int Уникальный идентификатор чата или пользователя.
text String Текст отправляемого сообщения (до 4096 символов).
reply_markup JSON Объект клавиатуры (Inline или Reply).
POST sendPhoto

Используйте этот метод для отправки фотографий.

ПараметрТипОписание
chat_id Int ID чата.
photo String URL фотографии или файл (при использовании multipart/form-data).
caption String Подпись к фотографии (опционально).
POST editMessageText

Используйте этот метод для редактирования текста сообщений, отправленных ботом.

ПараметрТипОписание
message_id String Идентификатор сообщения для редактирования.
text String Новый текст сообщения.
POST deleteMessage

Используйте этот метод для удаления сообщения.

ПараметрТипОписание
message_id String Идентификатор сообщения.
POST sendAnimation

Отправка GIF-анимаций. Максимальный размер файла: 20MB.

ПараметрТипОписание
chat_idIntID чата.
animationString/FileURL или файл анимации.
captionStringПодпись (опционально).
reply_markupJSONКлавиатура (опционально).
POST sendVoice

Отправка голосовых сообщений. Максимальный размер файла: 20MB.

ПараметрТипОписание
chat_idIntID чата.
voiceString/FileURL или файл голосового сообщения.
captionStringПодпись (опционально).
reply_markupJSONКлавиатура (опционально).
POST sendVideoNote

Отправка круглых видео-сообщений (кружочков). Максимальный размер файла: 20MB.

ПараметрТипОписание
chat_idIntID чата.
video_noteString/FileURL или файл видео-сообщения.
reply_markupJSONКлавиатура (опционально).
POST sendMediaGroup

Отправка альбома из 2-10 фото или видео.

ПараметрТипОписание
chat_idIntID чата.
mediaArrayМассив объектов {type, media}.
reply_markupJSONКлавиатура (опционально).
POST sendDice

Отправка анимированного эмодзи-кубика (для игр).

ПараметрТипОписание
chat_idIntID чата.
emojiStringЭмодзи: , , , , , (по умолчанию).
reply_markupJSONКлавиатура (опционально).
POST sendPoll

Отправка опроса (quiz или regular).

ПараметрТипОписание
chat_idIntID чата.
questionStringВопрос опроса.
optionsArrayМассив вариантов ответа (2-10).
is_anonymousBooleanАнонимный опрос (по умолчанию true).
typeStringregular или quiz (по умолчанию regular).
allows_multiple_answersBooleanРазрешить несколько ответов.
correct_option_idIntID правильного ответа (для quiz).
reply_markupJSONКлавиатура (опционально).
POST editMessageMedia

Редактирование медиа в существующем сообщении.

ПараметрТипОписание
message_idStringID сообщения.
captionStringНовая подпись (опционально).
reply_markupJSONНовая клавиатура (опционально).
POST editMessageReplyMarkup

Редактирование только клавиатуры сообщения.

ПараметрТипОписание
message_idStringID сообщения.
reply_markupJSONНовая клавиатура.
POST copyMessage

Копирование сообщения бота в другой чат.

Клавиатуры

Inline Keyboard

Inline-клавиатура отображается внутри сообщения. Используйте для действий, связанных с конкретным сообщением.

JSON
{ "inline_keyboard": [ [{"text":"👍 Лайк","callback_data":"like"}"], [{"text":"🌐 Сайт","url":"https://example.com"}"] ] }

Типы кнопок

ПараметрТипОписание
chat_idIntID целевого чата.
from_chat_idIntID исходного чата.
message_idStringID сообщения для копирования.
captionStringНовая подпись (опционально).
ПараметрОписание
callback_dataДанные для бота при нажатии (до 64 символов, ASCII)
urlОткрыть URL в браузере
web_appОткрыть Mini App внутри мессенджера
login_urlURL для авторизации

Полный пример бота (Python)

Python
import requests, time TOKEN = "YOUR_BOT_TOKEN" API_URL = f"https://znakora.ru/api/bot{TOKEN}" offset = 0 def api(method, data=None): r = requests.post(f"{API_URL}/{method}", json=data or {}, timeout=35) return r.json() def send(chat_id, text): return api("sendMessage", {"chat_id": chat_id, "text": text}) def callback_ok(callback_id, text="OK"): return api("answerCallbackQuery", { "callback_query_id": callback_id, "text": text }) while True: updates = api("getUpdates", {"offset": offset, "timeout": 30}) for update in updates.get("result", []): offset = update["update_id"] + 1 # Обычное сообщение if "message" in update: msg = update["message"] chat_id = msg["chat"]["id"] if msg.get("text") == "/start": send(chat_id, "Привет!") # Нажатие кнопки inline_keyboard if "callback_query" in update: cb = update["callback_query"] callback_id = cb["id"] data = cb.get("data", "") # ВАЖНО: используй cb["from"]["id"] для sendMessage! chat_id = cb["from"]["id"] callback_ok(callback_id, "Обработано!") if data == "info": send(chat_id, "📌 Информация...") elif data == "menu": send(chat_id, "🔥 Главное меню...") time.sleep(1)

⚠️ Важно: Для sendMessage после callback используйте cb["from"]["id"] (numericId пользователя), а не cb["message"]["chat"]["id"] (ObjectId чата).

Лимиты: до 10 рядов, 8 кнопок в ряду, текст до 64 символов.

Reply Keyboard

Reply-клавиатура отображается внизу экрана как замена стандартной клавиатуре.

JSON
{ "keyboard": [["Профиль", "Настройки"], ["Помощь"]], "resize_keyboard": true, "one_time_keyboard": true }

Удаление: отправьте {"remove_keyboard":true}

Пример бота на Node.js

Node.js
const axios = require('axios'); const TOKEN = 'YOUR_BOT_TOKEN'; const API_URL = `https://znakora.ru/api/bot${TOKEN}`; let offset = 0; async function api(method, data = {}) { try { const res = await axios.post(`${API_URL}/${method}`, data, { timeout: 35000 }); return res.data; } catch (e) { console.error('API ERROR:', e.message); return {}; } } async function send(chatId, text) { return api('sendMessage', { chat_id: chatId, text }); } async function callbackOk(callbackId, text = 'OK') { return api('answerCallbackQuery', { callback_query_id: callbackId, text, show_alert: false }); } async function main() { console.log('Bot started'); await api('deleteWebhook'); while (true) { try { const { result: updates } = await api('getUpdates', { offset, timeout: 30 }); for (const update of updates || []) { offset = update.update_id + 1; // Обычное сообщение if (update.message) { const msg = update.message; const chatId = msg.chat.id; const text = msg.text || ''; if (text === '/start') { await send(chatId, 'Привет!'); } } // Нажатие кнопки inline_keyboard if (update.callback_query) { const cb = update.callback_query; const callbackId = cb.id; const data = cb.data || ''; // ВАЖНО: используй cb.from.id для sendMessage! const chatId = cb.from.id; await callbackOk(callbackId, 'Обработано!'); if (data === 'info') { await send(chatId, '📌 Информация...'); } else if (data === 'menu') { await send(chatId, '🔥 Главное меню...'); } } } } catch (e) { console.error('ERROR:', e); } await new Promise(r => setTimeout(r, 1000)); } } main();

Установка: npm install axios

⚠️ Важно: Для sendMessage после callback используйте cb.from.id (numericId пользователя), а не cb.message.chat.id (ObjectId чата).

Методы: Обновления

POST getUpdates
{ "timeout": 30 }
POST setWebhook

Укажите URL, на который сервер будет отправлять HTTPS POST запросы при поступлении новых сообщений (Push-модель).

ПараметрТипОписание
url String HTTPS URL вашего сервера.
POST deleteWebhook

Используйте этот метод, чтобы удалить интеграцию с Webhook и переключиться обратно на getUpdates (Long Polling).

POST answerCallbackQuery

Отправляет ответ на нажатие Inline-кнопки (callback_query). Этот метод убирает индикатор "загрузки" на кнопке у пользователя.

ПараметрТипОписание
callback_query_id String ID запроса, полученный в объекте Update.
text String Текст всплывающего уведомления (опционально).
show_alert Boolean Если true, показать модальное окно вместо toast (опционально).