> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Документація з використання Discord Agent Proxy

> Discord Agent Proxy API guide - Ace Data Cloud

Discord Agent Proxy — це сервіс з **окремим розгортанням**: він зберігає облікові дані вашого власного Discord-акаунта, підтримує постійне з’єднання з Discord і відкриває можливості цього акаунта через два інтерфейси — **MCP** та **REST API**, дозволяючи ШІ або програмам керувати Discord замість вас.

Контейнер **не містить жодної ШІ-моделі**, він відповідає лише за виконання — виклики здійснюються вашим ШІ-клієнтом (Claude, Cursor тощо) або власною програмою.

```
AI 客户端  ──MCP /mcp──┐
                       ├─→ Discord Agent Proxy ──→ Discord
你的程序 ──REST /api───┘      （保管你的账号凭据）
```

## ⚠️ Обов’язково прочитайте перед використанням

Автоматизація операцій з **особистим акаунтом** (self-bot) за допомогою програм порушує Умови надання послуг Discord, і існує ризик блокування акаунта. Це є невід’ємною передумовою цього сервісу: ви надаєте облікові дані власного акаунта та самостійно берете на себе ризики.

**Наполегливо рекомендується використовувати спеціально створений додатковий акаунт, а не ваш основний акаунт.**

## Розгортання сервісу

Перейдіть до [Консоль → Застосунки](https://platform.acedata.cloud/console/applications), знайдіть Discord Agent Proxy та створіть застосунок. Після створення спочатку активуйте підписку, а потім перейдіть на сторінку конфігурації, введіть облікові дані вашого Discord-акаунта та виконайте розгортання. Ресурси інстансу автоматично налаштовуються платформою, вибирати конфігурацію не потрібно.

Після надсилання розгортання ви перейдете на сторінку керування застосунком із таким самим макетом «Огляд / Журнали / Документація», як для розгортання Telegram і WeChat. «Огляд» відображає стан інстансу та підписки, а також підтверджує, чи підключено Discord, через запит до акаунта; нормальна робота контейнера не обов’язково означає, що акаунт підключений.

Картка Discord-акаунта в «Огляді» надає два пункти інформації для підключення:

| Пункт | Приклад | Призначення |
| - | - | - |
| Адреса підключення MCP | `https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp` | Налаштування в ШІ-клієнті |
| Токен доступу | `V0p7kAWY...` | Для автентифікації, див. нижче |

### Перегляд і тестування інтерфейсів у консолі

Відкрийте вкладку «Документація» цього застосунку, щоб переглянути параметри запитів, структури відповідей для всіх 14 REST-операцій, а також приклади для Shell, Python, JavaScript та інших мов. Адреса інстансу й токен доступу буде заповнено автоматично; токен за замовчуванням приховано.

Виберіть `GET /api/whoami` і натисніть «Тест», щоб підтвердити акаунт, підключений проксі. Операції надсилання, редагування або видалення повідомлень впливають на реальний Discord-акаунт, тому перед тестуванням підтвердьте вміст запиту.

«Завантажити OpenAPI (JSON)» дозволяє експортувати повне визначення інтерфейсу. Файл містить адресу інстансу, але не містить токена доступу. Якщо потрібно змінити облікові дані Discord-акаунта, виберіть «Повторне розгортання» в «Огляді», введіть нові облікові дані та надішліть їх.

### Як отримати облікові дані Discord-акаунта

1. Увійдіть у Discord у браузері на комп’ютері ([discord.com/app](https://discord.com/app))
2. Натисніть `F12`, щоб відкрити інструменти розробника, і перейдіть на панель **Network (Мережа)**
3. Довільно натисніть будь-який канал у Discord і перегляньте список запитів
4. Відкрийте будь-який запит, надісланий до `discord.com/api`, і знайдіть поле `authorization` у **Request Headers (Заголовки запиту)**
5. Скопіюйте його значення

Цей рядок облікових даних еквівалентний стану входу у ваш акаунт, **не діліться ним ні з ким**. Якщо він витече, зміна пароля в Discord негайно зробить його недійсним.

## Спосіб автентифікації

Усі інтерфейси, крім `/health` і `/readyz`, вимагають передавання токена доступу в **заголовку запиту**:

```
Authorization: Bearer <你的访问令牌>
```

> **Увага: цей сервіс приймає автентифікацію лише через заголовок запиту та не підтримує спосіб додавання токена після URL, як-от `?token=xxx`.** Безпосереднє відкриття адреси інтерфейсу в браузері поверне `401 unauthorized`, це нормальне явище й не означає збою розгортання. Щоб підтвердити, що процес активний, перейдіть до `/health`; щоб підтвердити, що Discord-з’єднання здатне обробляти запити, перейдіть до `/readyz`. Обидві ці перевірки не потребують автентифікації. Якщо токен доступу проксі не налаштовано, захищені інтерфейси повертають `503` і не відкриваються анонімно.

## Перевірка стану сервісу

```bash theme={null}
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/health
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/readyz
```

`/health` лише означає, що HTTP-процес активний:

```json theme={null}
{ "status": "ok" }
```

`/readyz` означає, чи доступний Discord Gateway. За нормального з’єднання повертається HTTP 200:

```json theme={null}
{ "status": "ready", "gateway_ready": true }
```

Під час з’єднання, за недійсних облікових даних або розриву з’єднання пряме зондування Pod з боку Kubernetes повертає HTTP 503, а бекенд інстансу автоматично повторює спробу. У цей час Pod тимчасово вилучається з публічного Service, тому не гарантується можливість прочитати цей діагностичний JSON через доменне ім’я інстансу; перегляньте стан Deployment у консолі та викликайте MCP / REST після відновлення Ready.

## Використання в ШІ-клієнті (MCP)

На прикладі Claude Code:

```bash theme={null}
claude mcp add --transport http discord \
  https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp \
  --header "Authorization: Bearer <你的访问令牌>"
```

Для клієнтів на кшталт Cursor, які підтримують статичні заголовки запитів, налаштуйте адресу Streamable HTTP відповідно до їхньої поточної документації. Клієнти, що приймають наведену нижче структуру, можуть використовувати її:

```json theme={null}
{
  "mcpServers": {
    "discord": {
      "type": "http",
      "url": "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <你的访问令牌>"
      }
    }
  }
}
```

Це не універсальний формат конфігурації для всіх MCP-клієнтів. Віддалений конектор Claude Desktop / Claude.ai встановлюється з хмари й не зчитує жодних HTTP-заголовків запиту з локального `claude_desktop_config.json`; якщо наразі потрібен статичний Bearer-заголовок, використовуйте Claude Code або клієнт, який явно підтримує цю можливість.

Після завершення налаштування можна безпосередньо керувати Discord через ШІ природною мовою, наприклад:

> Перевір, чи є нові повідомлення в моєму каналі «Обговорення проєкту», і якщо хтось запитував про дату випуску, допоможи мені відповісти, що це буде цієї п’ятниці.

### Доступні інструменти

| Інструмент MCP | Призначення |
| - | - |
| `discord_whoami` | Переглянути, який обліковий запис зараз представляє агент |
| `discord_list_guilds` | Перелічити всі сервери, до яких приєднався обліковий запис |
| `discord_list_channels` | Перелічити канали певного сервера |
| `discord_create_text_channel` | Створити текстовий канал |
| `discord_list_members` | Перелічити учасників сервера |
| `discord_send_message` | Надіслати повідомлення (можна вказати відповідь на певне повідомлення) |
| `discord_read_messages` | Прочитати останні повідомлення каналу |
| `discord_edit_message` | Редагувати власне надіслане повідомлення |
| `discord_delete_message` | Видалити повідомлення |
| `discord_search_messages` | Шукати повідомлення в каналі |
| `discord_add_reaction` | Додати реакцію-емодзі до повідомлення |
| `discord_pin_message` | Закріпити повідомлення |
| `discord_create_dm` | Відкрити приватний чат один на один, повернути ID каналу |
| `discord_send_dm` | Надіслати приватне повідомлення певному користувачу |

## Використання в програмі (REST API)

Усі REST-інтерфейси розміщені під `/api`, тіло відповіді уніфіковано як `{"data": ...}`, а у разі помилки — `{"error": "..."}`.

### Перегляд поточного облікового запису

```bash theme={null}
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer <你的访问令牌>"
```

### Надсилання повідомлення

```bash theme={null}
curl -X POST https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/messages \
  -H "Authorization: Bearer <你的访问令牌>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <本次发送的唯一操作 ID>" \
  -d '{"channel_id": "1234567890", "content": "你好"}'
```

Під час повторної спроби того самого надсилання повторно використовуйте той самий `Idempotency-Key`, процес поверне перший результат без повторного надсилання. Перезапуск екземпляра очистить до 5 000 записів дедуплікації в пам’яті, тому викликачеві все одно потрібно самостійно відстежувати довгостроковий статус доставки.

Необов’язковий параметр `reply_to` використовується для відповіді на вказане повідомлення:

```json theme={null}
{ "channel_id": "1234567890", "content": "收到", "reply_to": "9876543210" }
```

### Читання повідомлень

```bash theme={null}
curl "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/channels/1234567890/messages?limit=20" \
  -H "Authorization: Bearer <你的访问令牌>"
```

### Повний список інтерфейсів

| Метод і шлях | Параметри | Призначення |
| - | - | - |
| `GET /api/whoami` | — | Інформація про обліковий запис, який представляє агент |
| `GET /api/guilds` | — | Список серверів, до яких приєднався обліковий запис |
| `GET /api/guilds/{guild_id}/channels` | — | Список каналів сервера |
| `POST /api/guilds/{guild_id}/channels` | `{name}` | Створити текстовий канал |
| `GET /api/guilds/{guild_id}/members` | `?limit=`（за замовчуванням 100） | Список учасників сервера |
| `POST /api/messages` | `{channel_id, content, reply_to?}` | Надіслати повідомлення |
| `GET /api/channels/{channel_id}/messages` | `?limit=`（за замовчуванням 50, максимум 100） | Прочитати останні повідомлення |
| `GET /api/channels/{channel_id}/messages/search` | `?q=`（обов’язково）`&limit=`（за замовчуванням 25） | Шукати повідомлення |
| `PATCH /api/channels/{channel_id}/messages/{message_id}` | `{content}` | Редагувати повідомлення |
| `DELETE /api/channels/{channel_id}/messages/{message_id}` | — | Видалити повідомлення |
| `POST /api/channels/{channel_id}/messages/{message_id}/reactions` | `{emoji}` | Додати реакцію-емодзі |
| `POST /api/channels/{channel_id}/messages/{message_id}/pin` | — | Закріпити повідомлення |
| `POST /api/dms` | `{recipient_id}` | Відкрити приватний чат, повернути ID каналу |
| `POST /api/dms/send` | `{recipient_id, content}` | Надіслати приватне повідомлення |

### Як отримати ID каналу та ID користувача

У клієнті Discord послідовно відкрийте **Налаштування користувача → Розширені налаштування**, увімкніть **Режим розробника**. Після цього клацніть правою кнопкою миші на будь-якому каналі або користувачі — у меню з’явиться «Копіювати ID».

Також можна безпосередньо викликати `GET /api/guilds` і `GET /api/guilds/{guild_id}/channels` для переліку.

## Поширені запитання

**Повертається `401 unauthorized`**

Токен доступу неправильний або був переданий способом `?token=`. Будь ласка, підтвердьте, що токен передається через заголовок запиту `Authorization: Bearer &lt;токен>` і збігається з тим, що відображено в консолі.

**Повертається `503`**

З’єднання з Discord ще не встановлено. Спочатку відкрийте `/readyz`, щоб переглянути `gateway_ready`; якщо протягом тривалого часу значення — `false`, найімовірніше, облікові дані облікового запису стали недійсними, отримайте їх знову та повторно розгорніть.

**Повертається `403` або `404`**

Сам обліковий запис не має відповідних дозволів (наприклад, не перебуває на цьому сервері або не має права писати в цьому каналі), або ID введено неправильно. Такі помилки надходять від Discord, а не є проблемою проксі-сервісу.

**Повертається `429`**

Було активовано обмеження частоти Discord, поле `retry_after` у відповіді містить рекомендовану кількість секунд очікування. Будь ласка, зменште частоту викликів.

**Обліковий запис заблоковано після надсилання повідомлення**

Як уже зазначалося, автоматизовані операції з особистими обліковими записами порушують умови надання послуг Discord. Будь ласка, використовуйте спеціальний додатковий обліковий запис і контролюйте частоту операцій, уникаючи чутливих дій, як-от масове надсилання повідомлень.

## Обсяг перевірки

Виробничий smoke від 1 серпня 2026 року перевірив за допомогою спеціального облікового запису обліковий запис, сервери, канали, учасників, читання повідомлень, пошук, надсилання, редагування, реакції та видалення. Автоматизовані тести охоплюють автентифікацію, перевірку параметрів, зіставлення помилок і сигнатури поточної бібліотеки залежностей; після змін worker або chart smoke все одно слід виконати повторно, не можна вважати історичну перевірку доказом постійної доступності.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.