ДОКУМЕНТАЦИЯ
Bot API
Бот — отдельный аккаунт Disalive. Вы управляете им через токен и запускаете код на своём компьютере или сервере. API передаёт сообщения и вступления участников, позволяет отправлять сообщения и файлы, редактировать свои сообщения, удалять сообщения, назначать и снимать роли, а также банить, заглушать и исключать участников. Условия для этих действий вы задаёте в коде своего бота.
Быстрый старт
- Войдите в Disalive и откройте панель разработчика.
- Создайте бота и сохраните токен. После закрытия токен можно только перевыпустить.
- Установите бота на сервер, которым владеете. Чтобы другие владельцы могли добавить бота по его
@username, включите «Доступен для установки». - При необходимости выдайте боту роль с правами «Управлять сообщениями», «Управлять участниками» и «Управлять ролями». Для приватного канала добавьте бота или его роль в доступ либо выдайте роль администратора со всеми правами сервера.
- Запустите свой код с переменной окружения
DISALIVE_BOT_TOKENна своём устройстве. - Язык разработки бота не важен, главное, чтобы он мог взаимодействовать с API.
Токен даёт доступ к действиям от имени бота в пределах выданных ему прав. Не вставляйте его в клиентский JavaScript, репозиторий и сообщения.
Авторизация и ответы
Передавайте токен в заголовке Authorization: Bot dlb_.... База адресов: https://disalive.ru/v1/bots/. Ответы имеют вид {"success":true,"data":...}. При ошибке возвращаются success:false и поле error.
| Код | Значение |
|---|---|
| 400 | Неверные параметры |
| 401 | Токен неверен или отозван |
| 403 | Недостаточно прав |
| 404 | Объект не найден в доступном сервере |
| 429 | Превышена частота запросов |
Методы
GET getMe.php
Проверка токена и получение ID, имени, описания, аватара, баннера, цветов бейджа и статуса бота. Не более 60 запросов в минуту.
GET getChannels.php
Список доступных боту текстовых каналов. Каждый элемент содержит serverId, serverName, channelId, chatId, channelName и isPrivate. Приватный канал доступен, если в его настройках указан бот или его роль, либо боту назначена роль со всеми правами администратора сервера. Не более 60 запросов в минуту.
GET getMembers.php?serverId=9&cursor=0&limit=50
Участники установленного сервера с пагинацией по memberId. Ответ содержит members, cursor, hasMore и ownerId. Участник содержит userId, username, displayName, avatar, isBot, roleId, roleName, rolePermissions, isOwner, isBanned и isMuted. rolePermissions — права назначенной роли на момент запроса; владелец сервера имеет права независимо от роли. Передавайте полученный cursor в следующий запрос, пока hasMore=true. Лимит 1–100, до 60 запросов в минуту.
GET getRoles.php?serverId=9
Список ролей установленного и доступного боту сервера. Ответ содержит data.roles: у каждой роли есть id, name, permissions, оформление и порядок. Используйте id в setMemberRole.php. До 60 запросов в минуту.
POST setMemberRole.php
Назначить роль: {"serverId":9,"username":"@new_user","roleId":12,"action":"assign"}. Снять роль: {"serverId":9,"userId":42,"roleId":12,"action":"remove"}. Укажите ровно один способ выбора участника: userId, username или messageId — автора сообщения в доступном боту канале. Для снятия передайте ID роли, которая сейчас назначена участнику. На сервере у участника только одна роль: назначение новой заменяет прежнюю, а снятие оставляет участника без роли. Ответ содержит roleId и previousRoleId.
Боту нужно право manageRoles. Нельзя менять роль владельца, самого бота или участника с равными либо более высокими правами; назначаемая роль должна иметь меньше прав, чем роль бота, и не содержать прав, отсутствующих у бота. При изменении роли между чтением и записью API вернёт 409. До 30 запросов в минуту.
curl -X POST 'https://disalive.ru/v1/bots/setMemberRole.php' \
-H "Authorization: Bot $DISALIVE_BOT_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"serverId":9,"username":"@new_user","roleId":12,"action":"assign"}'
GET checkMemberPermission.php?serverId=9&userId=42&permission=manageMessages
Проверяет право участника по текущим правилам сервера и возвращает data.allowed (true или false). Вместо userId можно передать username; укажите ровно один из них. Доступные права: manageServer, manageChannels, manageCategories, manageInvites, manageMembers, manageRoles, manageCalls, manageMessages. Проверка учитывает владельца, настройки приглашений и блокировку участника на сервере. Для проверки команды используйте этот метод непосредственно перед её выполнением: права роли могут измениться после получения списка участников. До 60 запросов в минуту.
curl -G 'https://disalive.ru/v1/bots/checkMemberPermission.php' \ -H "Authorization: Bot $DISALIVE_BOT_TOKEN" \ --data-urlencode 'serverId=9' --data-urlencode 'userId=42' \ --data-urlencode 'permission=manageMessages'
Методы модерации и удаления сообщений также проверяют права самого бота на сервере. Если действие недоступно, API вернёт 403.
GET getUpdates.php?cursor=0&memberCursor=0&reactionCursor=0&limit=50
Возвращает message_create, member_join и message_reaction. У каждого потока свой курсор: cursor для сообщений, memberCursor для вступлений и reactionCursor для реакций. Передавайте все полученные курсоры в следующий запрос. Если hasMore=true, запрашивайте следующую страницу сразу. Лимит до 100 событий каждого типа за запрос, до 120 запросов в минуту. Пауза 2 секунды между пустыми страницами даёт примерно 30 запросов в минуту. Каждый успешный запрос обновляет онлайн бота. Для совместимости со старыми ботами memberCursor и reactionCursor можно опустить — соответствующие события не придут.
{"success":true,"data":{"events":[
{"type":"message_create","id":123,"chatId":456,"channelId":78,
"serverId":9,"isPrivate":false,"replyToMessageId":null,
"attachments":[],"text":"/ping","time":"2026-11-08 12:00:00",
"author":{"id":42,"username":"neo","displayName":"Neo","isBot":false}},
{"type":"member_join","id":7,"serverId":9,"time":"2026-11-08 12:01:00",
"user":{"id":43,"username":"new_user","displayName":"Новый участник","isBot":false}},
{"type":"message_reaction","id":8,"action":"add","messageId":123,
"chatId":456,"channelId":78,"serverId":9,"nameReaction":"[people:34]",
"time":"2026-11-08 12:02:00","user":{"id":43,"username":"new_user","displayName":"Новый участник","isBot":false}}
],"cursor":123,"memberCursor":7,"reactionCursor":8,"hasMore":false}}
Реакции имеют action со значением add или remove; id — ID события, а messageId — ID сообщения. События приходят из доступных текстовых каналов установленных серверов; реакции самого бота исключены. Для реакций нужна миграция 2026-11-09-bot-reaction-events.sql. Сообщения приходят после установки бота; собственные сообщения исключены. Сообщения других ботов содержат author.isBot=true. Для member_join нужна миграция 2026-11-08-bot-member-events.sql. После сбоя возможна повторная обработка: сохраняйте все курсоры после успешной обработки и делайте действия идемпотентными.
GET / POST getMessage.php
Получить одно сообщение по messageId или до 100 сообщений по messageIds. Для одного сообщения: GET getMessage.php?messageId=123, ответ в data.message. Для пачки: GET getMessage.php?messageIds=123,124,125 или POST с JSON {"messageIds":[123,124,125]}, ответ в data.messages. Можно также передать один messageId в POST JSON. Укажите только одно из этих полей.
Формат сообщения совпадает с событием message_create, включая актуальный текст, автора, replyToMessageId и вложения. Доступны сообщения из текстовых каналов установленных серверов после установки бота, в том числе собственные сообщения бота. Удалённые сообщения, заблокированные серверы и недоступные приватные каналы исключаются. Одиночный запрос вернёт 404, если сообщение недоступно; пакетный пропустит недоступные ID и сохранит порядок запрошенных ID. Повторяющиеся ID вернутся один раз. До 60 запросов в минуту.
curl -X POST 'https://disalive.ru/v1/bots/getMessage.php' \
-H "Authorization: Bot $DISALIVE_BOT_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"messageIds":[123,124,125]}'
POST sendMessage.php
Тело JSON: {"channelId":78,"text":"pong","replyToMessageId":123}. Для ответа ID сообщения должен относиться к тому же каналу. Поле replyToMessageId необязательно.
Для изображения, документа, аудио или видео отправьте multipart/form-data: channelId, необязательные text и replyToMessageId, файлы в files[]. Можно передать metaFiles — JSON-массив объектов {"index":0,"name":"имя.ext","duration":12.5,"isSpoiler":false}. Допускается до 10 файлов по 50 МБ каждый. Видео получает миниатюру, как в обычных сообщениях. Текст — до 2000 символов; до 30 отправок в минуту. Медленный режим и ограничения сервера действуют и на бота.
curl -X POST 'https://disalive.ru/v1/bots/sendMessage.php' \ -H "Authorization: Bot $DISALIVE_BOT_TOKEN" \ -F 'channelId=78' -F 'replyToMessageId=123' \ -F 'text=Файл для вас' -F 'files[]=@example.pdf'
POST editMessage.php
Тело JSON: {"messageId":124,"text":"Исправленный текст"}. Бот может менять текст только собственного неудалённого сообщения в доступном канале. Вложения остаются на месте. До 30 запросов в минуту.
POST deleteMessage.php
Тело JSON: {"messageId":123}. Удаляет сообщение в доступном текстовом канале установленного сервера. Боту обязательно нужно право manageMessages, в том числе для удаления собственного сообщения. До 60 запросов в минуту.
POST moderateMember.php
Тело JSON: {"serverId":9,"username":"@new_user","action":"mute","expiresAt":"2026-11-09T18:00:00+03:00","reason":"Флуд"}. Укажите ровно один способ выбора цели: userId, username (с @ или без) либо messageId — автора сообщения из доступного боту канала этого сервера. Действия: ban, unban, mute, unmute, kick. Кик исключает участника из сервера, как кнопка исключения в приложении; expiresAt для него не используется. Для бана и мута передайте будущую дату с часовым поясом в expiresAt; если её опустить или передать null, ограничение будет бессрочным. Боту требуется право manageMembers. Нельзя ограничить владельца сервера, самого бота или участника с равными либо более высокими правами. До 20 запросов в минуту.
POST heartbeat.php
Для бота с webhook отправляйте пустой POST с токеном каждые 30 секунд, пока работает ваш процесс. После 90 секунд без heartbeat бот переходит в офлайн. При опросе getUpdates отдельный heartbeat не нужен. Лимит 6 запросов в минуту.
POST disconnect.php
При штатном завершении процесса вызовите метод без тела, чтобы сразу показать бота офлайн. При аварийной остановке сработает таймаут heartbeat.
POST setWebhook.php
Тело JSON: {"url":"https://example.com/disalive-webhook"}. Требуется публичный HTTPS домен на порту 443 с IPv4 адресом. Метод вернёт data.secret один раз — сохраните его в настройках своего сервера. Повторная установка меняет секрет и удаляет ожидающие доставки; {"url":""} отключает webhook. До 6 изменений в минуту. После установки новые сообщения, вступления и реакции отправляются POST запросами на ваш URL. Для статуса онлайн продолжайте вызывать heartbeat.php.
Перевыпуск токена через панель разработчика отключает webhook и очищает его очередь. С новым токеном установите URL заново.
GET getWebhook.php
Возвращает текущий URL и дату его установки без секрета. До 60 запросов в минуту.
Webhook получает один JSON объект события в формате getUpdates.events[]. Заголовки: X-Disalive-Event (тип), X-Disalive-Delivery (ID доставки), X-Disalive-Signature (sha256=...). Подпись — HMAC-SHA256 от неизменённого тела запроса с секретом, возвращённым setWebhook. Сравнивайте подписи безопасным сравнением. Отвечайте кодом 2xx после обработки; при ошибке доставка повторяется до 8 раз. Обработка должна быть идемпотентной: при повторе ID доставки остаётся тем же. Не запускайте одновременно обработку этих же событий из getUpdates.
import hashlib, hmac
expected = "sha256=" + hmac.new(
WEBHOOK_SECRET.encode(), raw_request_body, hashlib.sha256
).hexdigest()
if not hmac.compare_digest(expected, signature_header):
raise ValueError("Неверная подпись webhook")
Оформление и запуск
В панели разработчика откройте «Настроить»: там можно загрузить аватар и баннер бота (JPEG, PNG, WebP, GIF до 10 МБ), удалить их и выбрать основной и дополнительный цвета бейджа.
Получение событий
Выберите способ работы бота. Методы отправки сообщений и модерации выше доступны в обоих режимах.
Long polling
Бот сам запрашивает getUpdates.php и сохраняет три курсора: cursor для сообщений, memberCursor для вступлений и reactionCursor для реакций. Сейчас метод отвечает сразу: пример делает регулярный опрос с паузой, без ожидания нового события на стороне API. Если hasMore=true, запрашивайте следующую страницу сразу; после пустой страницы делайте паузу. Каждый успешный запрос обновляет статус бота онлайн, отдельный heartbeat не нужен. Для остановки можно вызвать disconnect.php.
Пример на Python без зависимостей
Ответ на команду /ping и обработка вступления участника:
import json
import os
import time
import urllib.request
from pathlib import Path
BASE = "https://disalive.ru/v1/bots/"
TOKEN = os.environ["DISALIVE_BOT_TOKEN"]
CURSOR_FILE = Path("bot-cursors.json")
cursors = json.loads(CURSOR_FILE.read_text()) if CURSOR_FILE.exists() else {
"cursor": 0, "memberCursor": 0, "reactionCursor": 0
}
def api(path, data=None):
body = None if data is None else json.dumps(data).encode("utf-8")
request = urllib.request.Request(BASE + path, data=body, headers={
"Authorization": "Bot " + TOKEN,
"Content-Type": "application/json",
})
with urllib.request.urlopen(request, timeout=15) as response:
result = json.load(response)
if not result["success"]:
raise RuntimeError(result.get("error", "Ошибка API"))
return result["data"]
while True:
try:
page = api(
f"getUpdates.php?cursor={cursors['cursor']}"
f"&memberCursor={cursors['memberCursor']}"
f"&reactionCursor={cursors.get('reactionCursor', 0)}&limit=50"
)
for event in page["events"]:
if event["type"] == "member_join":
print("Вступил:", event["serverId"], event["user"]["displayName"])
continue
if event["type"] == "message_reaction":
print("Реакция:", event["action"], event["messageId"], event["nameReaction"])
continue
if event["type"] != "message_create" or event["author"]["isBot"]:
continue
if event.get("text") and event["text"].strip() == "/ping":
api("sendMessage.php", {
"channelId": event["channelId"], "text": "pong",
"replyToMessageId": event["id"]
})
cursors = {"cursor": page["cursor"], "memberCursor": page["memberCursor"],
"reactionCursor": page["reactionCursor"]}
CURSOR_FILE.write_text(json.dumps(cursors))
if not page["hasMore"]:
time.sleep(2)
except Exception as error:
print("Ошибка бота:", error)
time.sleep(5)
Условия удаления сообщений и модерации задавайте в обработчике message_create: проверяйте текст и автора, затем вызывайте deleteMessage.php или moderateMember.php. Для продакшена храните все курсоры и состояние команд в своей БД; проверяйте тип и ID события перед действиями с побочными эффектами.
Webhook
Disalive отправляет события на ваш публичный HTTPS адрес. Домен должен иметь публичный IPv4 и принимать запросы на порту 443. Пример ниже слушает локальный порт 8080; настройте HTTPS сервер или обратный прокси, который передаёт запросы на него. Бот и принимающий сервер должны работать на вашем устройстве или хостинге.
- Передайте URL в
setWebhook.phpс токеном бота и сохранитеdata.secret: он показывается только при установке. Повторная установка меняет секрет и очищает ожидающие доставки. - Проверяйте
X-Disalive-Signatureпо исходным байтам тела запроса до обработки события. Не передавайте токен и секрет в браузер. - Возвращайте 2xx только после успешной обработки. При ошибке Disalive повторит доставку до 8 раз; идентификатор в
X-Disalive-Deliveryостаётся тем же. - Отправляйте
heartbeat.phpкаждые 30 секунд для статуса онлайн. При штатном завершении вызовитеdisconnect.php.
curl -X POST 'https://disalive.ru/v1/bots/setWebhook.php' \
-H "Authorization: Bot $DISALIVE_BOT_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"url":"https://bot.example.com/disalive-webhook"}'
После настройки задайте на своём сервере переменные DISALIVE_BOT_TOKEN и DISALIVE_WEBHOOK_SECRET. Для отключения webhook отправьте {"url":""} в setWebhook.php. Текущий URL можно узнать через getWebhook.php. При перевыпуске токена webhook отключается и его нужно установить заново.
Пример на Python без зависимостей
Обработчик принимает message_create, member_join и message_reaction, отвечает на /ping, проверяет подпись и запоминает ID успешно обработанных доставок в SQLite.
import hashlib
import hmac
import json
import os
import sqlite3
import threading
import time
import urllib.request
from http.server import BaseHTTPRequestHandler, HTTPServer
BASE = "https://disalive.ru/v1/bots/"
TOKEN = os.environ["DISALIVE_BOT_TOKEN"]
SECRET = os.environ["DISALIVE_WEBHOOK_SECRET"].encode("utf-8")
db = sqlite3.connect("webhook-deliveries.sqlite3")
db.execute("CREATE TABLE IF NOT EXISTS deliveries (id TEXT PRIMARY KEY)")
db.commit()
def api(path, data=None):
body = json.dumps(data or {}).encode("utf-8")
request = urllib.request.Request(BASE + path, data=body, headers={
"Authorization": "Bot " + TOKEN,
"Content-Type": "application/json",
})
with urllib.request.urlopen(request, timeout=15) as response:
result = json.load(response)
if not result["success"]:
raise RuntimeError(result.get("error", "Ошибка API"))
return result["data"]
def heartbeat():
while True:
try:
api("heartbeat.php")
except Exception as error:
print("Ошибка heartbeat:", error, flush=True)
time.sleep(30)
class Handler(BaseHTTPRequestHandler):
def do_POST(self):
if self.path != "/disalive-webhook":
self.send_error(404)
return
length = int(self.headers.get("Content-Length", "0"))
if length <= 0 or length > 1048576:
self.send_error(400)
return
raw = self.rfile.read(length)
expected = "sha256=" + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
signature = self.headers.get("X-Disalive-Signature", "")
if not hmac.compare_digest(expected, signature):
self.send_error(401)
return
delivery = self.headers.get("X-Disalive-Delivery", "")
if not delivery:
self.send_error(400)
return
try:
event = json.loads(raw)
if not db.execute("SELECT 1 FROM deliveries WHERE id = ?", (delivery,)).fetchone():
if event.get("type") == "member_join":
print("Вступил:", event["serverId"], event["user"]["displayName"])
elif event.get("type") == "message_reaction":
print("Реакция:", event["action"], event["messageId"], event["nameReaction"])
elif event.get("type") == "message_create":
if not event["author"]["isBot"] and event.get("text") and event["text"].strip() == "/ping":
api("sendMessage.php", {
"channelId": event["channelId"], "text": "pong",
"replyToMessageId": event["id"]
})
db.execute("INSERT INTO deliveries (id) VALUES (?)", (delivery,))
db.commit()
self.send_response(204)
self.end_headers()
except Exception as error:
db.rollback()
print("Ошибка обработки webhook:", error, flush=True)
self.send_error(500)
threading.Thread(target=heartbeat, daemon=True).start()
server = HTTPServer(("127.0.0.1", 8080), Handler)
try:
server.serve_forever()
except KeyboardInterrupt:
pass
finally:
server.server_close()
db.close()
try:
api("disconnect.php")
except Exception as error:
print("Ошибка отключения:", error, flush=True)
Для запуска сохраните пример в файл, настройте HTTPS прокси на 127.0.0.1:8080 и установите URL. SQLite защищает от повторной обработки уже сохранённого ID доставки. Если процесс завершится после внешнего действия, но до сохранения ID, действие может повториться; для строгой идемпотентности учитывайте это в своей логике. Не запускайте параллельно обработку этих же событий через getUpdates.php.