Astral Bot API

Обзор платформы

Astral — независимая платформа для мгновенного обмена сообщениями и голосовой связи. Bot API позволяет создавать автоматизированных ботов, которые могут отправлять сообщения, управлять серверами, модерировать участников и реагировать на события в реальном времени.

Совместимость

Astral API совместим с протоколом Discord v10. Это означает, что вы можете использовать существующие библиотеки:

Для работы с Astral вместо Discord достаточно переопределить base URL API.

Эндпоинты

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

Создайте бота за 5 минут. Ниже — минимальный путь от нуля до работающего бота.

Аутентификация

Все запросы к API должны содержать заголовок Authorization. Astral поддерживает три схемы аутентификации:

curl -H "Authorization: Bot 1234567890.aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  https://api.astral.ru/users/@me

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  https://api.astral.ru/users/@me

Выполнение запросов

Все запросы к API отправляются как HTTP-запросы к base URL.

HTTP-методы

Заголовки

Обязательные заголовки для каждого запроса:

Authorization: Bot <token>
Content-Type: application/json
User-Agent: MyBot/1.0

Формат тела запроса

Тело запроса для POST/PATCH/PUT отправляется в формате JSON. Для отправки файлов используйте multipart/form-data с полем payload_json для JSON-части.

Audit Log Reason

Многие методы модерации поддерживают заголовок X-Audit-Log-Reason. Его значение сохраняется в журнале аудита сервера:

X-Audit-Log-Reason: Нарушение правил сервера

Snowflake ID

Все идентификаторы (ID) в Astral — это snowflake: 64-битные целые числа, передаваемые как строки в JSON. Snowflake содержит метку времени создания, что позволяет сортировать объекты по дате создания.

Формат бот-токена

Бот-токен Astral состоит из двух частей, разделённых точкой:

<application_id>.<secret>

Структура

Пример токена

1476982544653742137.aBcDeFgHiJkLmNoPqRsTuVwXyZaBcDeFgHiJkLmN

Процесс валидации

При каждом запросе с Bot-токеном сервер выполняет следующую цепочку:

• ›1. Парсит application_id из части до точки
• ›2. Загружает приложение из базы по application_id
• ›3. Проверяет, что приложение существует и имеет bot user
• ›4. Проверяет, что у приложения сохранён хеш токена (bot_token_hash)
• ›5. Верифицирует secret через argon2id (argon2.verify(hash, secret))
• ›6. Возвращает bot user ID при успешной верификации

Частые ошибки

Типы данных

Основные объекты, которые возвращает API. Все ID — snowflake (строки в JSON).

Методы — Приложения

Управление OAuth2-приложениями и бот-аккаунтами.

{
  "name": "Мой бот",
  "bot_public": true
}

{
  "id": "1476982544653742137",
  "name": "Мой бот",
  "bot": {
    "id": "1476982544653742137",
    "username": "Мой бот",
    "token": "1476982544653742137.aBcDeFgHiJk..."
  },
  "client_secret": "xYz...",
  "bot_public": true
}

{
  "id": "1476982544653742137",
  "name": "Мой бот",
  "icon": null,
  "description": null,
  "bot_public": true,
  "bot_require_code_grant": false,
  "verify_key": null,
  "flags": 0,
  "bot": {
    "id": "1476982544653742137",
    "username": "Мой бот",
    "discriminator": 7,
    "avatar": null,
    "bot": true
  }
}

[
  { "id": "...", "name": "Bot 1", ... },
  { "id": "...", "name": "Bot 2", ... }
]

{
  "name": "Новое имя",
  "bot_public": false
}

{ ... обновлённый Application ... }

{ "password": "your_password" }

204 No Content

{ "password": "your_password" }

{
  "token": "1476982544653742137.newSecretHere...",
  "id": "1476982544653742137",
  "username": "Мой бот",
  ...
}

{
  "username": "CoolBot",
  "bio": "Бот для модерации"
}

{ ... обновлённый User ... }

Методы — Gateway

Подключение к real-time WebSocket.

{
  "url": "wss://gateway.astral.ru",
  "shards": 1,
  "session_start_limit": {
    "total": 1000,
    "remaining": 999,
    "reset_after": 14400000,
    "max_concurrency": 1
  }
}

Протокол Gateway

После подключения к WebSocket бот следует стандартному протоколу:

• ›1. Получить HELLO с heartbeat_interval
• ›2. Отправить IDENTIFY с токеном и intents
• ›3. Получить READY — бот онлайн
• ›4. Отправлять HEARTBEAT каждые heartbeat_interval мс
• ›5. Получать события: MESSAGE_CREATE, GUILD_MEMBER_ADD и т.д.

Основные Gateway-события

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

[
  {
    "id": "1234567890",
    "channel_id": "9876543210",
    "author": { "id": "...", "username": "User" },
    "content": "Привет!",
    "timestamp": "2026-02-28T00:00:00.000Z"
  }
]

{ ... объект Message ... }

{
  "content": "Привет от бота!"
}

{ ... объект Message ... }

{
  "content": "Обновлённый текст"
}

{ ... обновлённый Message ... }

204 No Content

Методы — Серверы (Guilds)

{
  "name": "Мой сервер"
}

{ ... объект Guild ... }

{
  "id": "...",
  "name": "Мой сервер",
  "icon": "abc123",
  "owner_id": "...",
  "member_count": 42
}

{
  "name": "Обновлённое название"
}

{ ... обновлённый Guild ... }

[
  { "id": "...", "name": "Server 1" },
  { "id": "...", "name": "Server 2" }
]

204 No Content

Методы — Участники

[
  {
    "user": { "id": "...", "username": "User" },
    "nick": "Никнейм",
    "roles": ["..."],
    "joined_at": "2026-01-01T00:00:00.000Z"
  }
]

{ ... объект Member ... }

{
  "nick": "Новый ник"
}

{ ... обновлённый Member ... }

204 No Content

Методы — Каналы

{
  "id": "...",
  "type": 0,
  "name": "general",
  "guild_id": "...",
  "position": 0,
  "topic": "Общий чат"
}

Дополнительные методы каналов (создание, обновление, удаление, permission overwrites) совместимы с Discord API v10. Подробности в спецификации Discord.

Методы — Роли

204 No Content

204 No Content

Методы — Баны

[
  {
    "user": { "id": "...", "username": "BadUser" },
    "reason": "Спам"
  }
]

{
  "delete_message_days": 1,
  "reason": "Нарушение правил"
}

204 No Content

204 No Content

Методы — Приглашения

Для приглашения бота на сервер сформируйте URL:

https://astral.ru/oauth2/authorize?client_id=<APP_ID>&scope=bot&permissions=<PERMISSIONS>

Параметры URL

Основные permissions

OAuth2

Astral поддерживает OAuth2 Authorization Code Flow для действий от имени пользователя.

Авторизация (шаг 1)

Перенаправьте пользователя на:

GET https://astral.ru/oauth2/authorize
  ?client_id=<APP_ID>
  &redirect_uri=<ENCODED_URI>
  &response_type=code
  &scope=identify guilds
  &state=<RANDOM_STATE>

Обмен кода на токен (шаг 2)

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<AUTH_CODE>
&redirect_uri=<SAME_URI>
&client_id=<APP_ID>
&client_secret=<CLIENT_SECRET>

Ответ:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "dGhp...",
  "scope": "identify guilds"
}

Обновление токена

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<REFRESH_TOKEN>
&client_id=<APP_ID>
&client_secret=<CLIENT_SECRET>

Отзыв токена

POST /oauth2/token/revoke
Content-Type: application/x-www-form-urlencoded

token=<ACCESS_OR_REFRESH_TOKEN>
&client_id=<APP_ID>
&client_secret=<CLIENT_SECRET>

Доступные скоупы

Rate Limits

API применяет ограничения частоты запросов к каждому эндпоинту. Лимиты возвращаются в заголовках ответа.

Заголовки ответа

Обработка 429

При получении HTTP 429 Too Many Requests:

• ›1. Прочитайте заголовок Retry-After
• ›2. Подождите указанное количество секунд
• ›3. Повторите запрос

HTTP/1.1 429 Too Many Requests
Retry-After: 5

{
  "code": "RATE_LIMITED",
  "message": "You are being rate limited",
  "retry_after": 5.0
}

Коды ошибок

API возвращает структурированные JSON-ошибки:

{
  "code": "ACCESS_DENIED",
  "message": "Access denied"
}

Пример — Python (discord.py)

discord.py по умолчанию подключается к discord.com. Для Astral переопределите base URL:

import discord
import os

# === Переопределяем эндпоинт на Astral ===
discord.http.Route.BASE = "https://api.astral.ru"

intents = discord.Intents.default()
intents.message_content = True

bot = discord.Bot(intents=intents)

@bot.event
async def on_ready():
    print(f"[Astral] Бот {bot.user} подключён!")
    print(f"[Astral] Серверов: {len(bot.guilds)}")

@bot.event
async def on_message(message):
    if message.author.bot:
        return

    if message.content == "!ping":
        await message.channel.send("Pong!")

    if message.content == "!serverinfo":
        guild = message.guild
        embed = discord.Embed(
            title=guild.name,
            description=f"Участников: {guild.member_count}"
        )
        if guild.icon:
            embed.set_thumbnail(url=guild.icon.url)
        await message.channel.send(embed=embed)

# Токен из переменной окружения
bot.run(os.environ["ASTRAL_BOT_TOKEN"])

Для форков discord.py

Пример — JavaScript (discord.js)

Для discord.js v14+ передайте api в опции rest:

const { Client, GatewayIntentBits } = require('discord.js');

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
  ],
  rest: {
    api: 'https://api.astral.ru',
  },
});

client.on('ready', () => {
  console.log(`[Astral] Бот ${client.user.tag} подключён!`);
  console.log(`[Astral] Серверов: ${client.guilds.cache.size}`);
});

client.on('messageCreate', async (message) => {
  if (message.author.bot) return;

  if (message.content === '!ping') {
    await message.reply('Pong!');
  }

  if (message.content === '!serverinfo') {
    const guild = message.guild;
    const embed = {
      title: guild.name,
      description: `Участников: ${guild.memberCount}`,
      thumbnail: guild.iconURL() ? { url: guild.iconURL() } : undefined,
    };
    await message.channel.send({ embeds: [embed] });
  }
});

client.login(process.env.ASTRAL_BOT_TOKEN);

Пример — curl

Базовые запросы через командную строку для быстрого тестирования.

Проверить токен

curl -s -H "Authorization: Bot $TOKEN" \
  https://api.astral.ru/users/@me | jq .

Получить информацию о приложении

curl -s -H "Authorization: Bot $TOKEN" \
  https://api.astral.ru/applications/@me | jq .

Получить Gateway URL

curl -s -H "Authorization: Bot $TOKEN" \
  https://api.astral.ru/gateway/bot | jq .

Отправить сообщение

curl -X POST \
  -H "Authorization: Bot $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Привет из curl!"}' \
  https://api.astral.ru/channels/<CHANNEL_ID>/messages | jq .

Забанить пользователя

curl -X PUT \
  -H "Authorization: Bot $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Audit-Log-Reason: Спам" \
  -d '{"delete_message_days": 1}' \
  https://api.astral.ru/guilds/<GUILD_ID>/bans/<USER_ID>

Переменные окружения

Рекомендуемый .env файл:

# === Обязательные ===

# Бот-токен Astral
ASTRAL_BOT_TOKEN=<application_id>.<secret>

# Base URL API
ASTRAL_API_BASE=https://api.astral.ru

# === Опциональные ===

# Gateway URL (обычно автоопределяется из /gateway/bot)
ASTRAL_GATEWAY_URL=wss://gateway.astral.ru

# CDN для аватаров и вложений
ASTRAL_CDN_URL=https://cdn.astral.ru

# Логирование (debug, info, warn, error)
LOG_LEVEL=info

Безопасность

FAQ