ДОКУМЕНТАЦИЯ

Bot API

Бот — отдельный аккаунт Disalive. Вы управляете им через токен и запускаете код на своём компьютере или сервере. API передаёт сообщения и вступления участников, позволяет отправлять сообщения и файлы, редактировать свои сообщения, удалять сообщения, назначать и снимать роли, а также банить, заглушать и исключать участников. Условия для этих действий вы задаёте в коде своего бота.

Быстрый старт

  1. Войдите в Disalive и откройте панель разработчика.
  2. Создайте бота и сохраните токен. После закрытия токен можно только перевыпустить.
  3. Установите бота на сервер, которым владеете. Чтобы другие владельцы могли добавить бота по его @username, включите «Доступен для установки».
  4. При необходимости выдайте боту роль с правами «Управлять сообщениями», «Управлять участниками» и «Управлять ролями». Для приватного канала добавьте бота или его роль в доступ либо выдайте роль администратора со всеми правами сервера.
  5. Запустите свой код с переменной окружения DISALIVE_BOT_TOKEN на своём устройстве.
  6. Язык разработки бота не важен, главное, чтобы он мог взаимодействовать с 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 события перед действиями с побочными эффектами.