> ## 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) أو برنامجك الخاص.

```
عميل الذكاء الاصطناعي  ──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...` | للمصادقة، انظر أدناه |

### استعراض الواجهات واختبارها في وحدة التحكم

افتح علامة تبويب «المستندات» لهذا التطبيق لعرض معلمات الطلب وبنية الاستجابة لجميع عمليات REST الـ14، بالإضافة إلى أمثلة بلغات مثل 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 <你的访问令牌>
```

> **ملاحظة: تقبل هذه الخدمة المصادقة عبر رؤوس الطلبات فقط، ولا تدعم طريقة إلحاق الرمز بعنوان الموقع مثل `?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 }
```

أثناء الاتصال، أو عند عدم صلاحية بيانات الاعتماد، أو عند انقطاع الاتصال، يعيد الفحص المباشر لـ Kubernetes على Pod قيمة 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` | بدء محادثة خاصة فردية، وإرجاع معرّف القناة |
| `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}` | بدء محادثة خاصة، وإرجاع معرّف القناة |
| `POST /api/dms/send` | `{recipient_id, content}` | إرسال رسالة خاصة |

### كيفية الحصول على معرّف القناة ومعرّف المستخدم

في عميل Discord، افتح بالتتابع **إعدادات المستخدم → الإعدادات المتقدمة**، ثم فعّل **وضع المطور**. بعد ذلك، انقر بزر الماوس الأيمن على أي قناة أو مستخدم، وستظهر «نسخ المعرّف» في القائمة.

يمكنك أيضًا استدعاء `GET /api/guilds` و`GET /api/guilds/{guild_id}/channels` مباشرةً للتعداد.

## الأسئلة الشائعة

**إرجاع `401 unauthorized`**

رمز الوصول غير صحيح، أو تم تمريره باستخدام طريقة `?token=`. يُرجى التأكد من تمرير الرمز عبر ترويسة الطلب `Authorization: Bearer &lt;令牌>`، وأنه يطابق المعروض في وحدة التحكم.

**إرجاع `503`**

لم يتم إنشاء الاتصال مع Discord بعد. قم أولًا بزيارة `/readyz` للتحقق من `gateway_ready`، وإذا بقيت القيمة `false` لفترة طويلة، فعادةً ما تكون بيانات اعتماد الحساب غير صالحة، لذا يُرجى الحصول عليها من جديد وإعادة النشر.

**إرجاع `403` أو `404`**

لا يملك الحساب نفسه الصلاحية المقابلة (على سبيل المثال، ليس موجودًا في ذلك الخادم أو لا يملك صلاحية التحدث في تلك القناة)، أو تم إدخال المعرّف بشكل خاطئ. تأتي هذه الأخطاء من 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.