# وكيلكم الخاص، أو n8n، أو سكربت، متصل بواتساب الخاص بكم بمفتاح واحد.

> المحادثات نفسها بصيغة JSON عبر HTTP. بعدها يقرأ وكيلكم ويبحث ويردّ في المحادثات التي تسمحون بها.

**Circles واجهة HTTP API لرقم واتساب شخصي:** اربطوا رقمكم كجهاز مرتبط، وأنشئوا مفتاحا، واستدعوا `https://app.usecircles.app/api/v1/agent` مع `Authorization: Bearer circ_...`، والواجهة موصوفة بـOpenAPI 3.1 في `https://app.usecircles.app/api/openapi.json`. تقرأ المحادثات التي فتحتموها، مع الرسائل الصوتية كنص، وترسل وتردّ وتتفاعل في المحادثات المفتوحة للإرسال، في كل الباقات. Circles مجاني لـ2 محادثات لمدة تصل إلى 3 أشهر، أو $14.90 شهريا في Plus، أو $29.90 شهريا في Pro، مع 14 يوما من Pro مجانا، بتاريخ نوفمبر 2026.

## ثلاث خطوات

1. **اربطوا واتساب بـ Circles**: يصلكم رابط على واتساب، وتربطون Circles كجهاز مرتبط. رقمكم المعتاد، من دون تثبيت أي شيء.
2. **أنشئوا مفتاحاً**: في صفحة الوكلاء في Circles: New token، اختاروا API with a key وما يسمح به. المفتاح يبدأ بـ `circ_` ويظهر مرة واحدة فقط.
3. **أول طلب**: مع `Authorization: Bearer circ_...`، اطلبوا: `https://app.usecircles.app/api/v1/agent/allowed_chats`

## ثلاثة أسئلة أولى لـ وكيلكم

- allowed_chats: كل محادثة يصل إليها المفتاح
- activity: ما الذي تغيّر منذ الطلب الأخير
- send: ردّ في محادثة مفتوحة للكتابة

14 يوماً مع كل المحادثات، ثم 2 محادثات مجاناً لمدة تصل إلى 3 أشهر. Plus بسعر $14.90 شهرياً لـ 10 محادثات، وPro بسعر $29.90 لكل المحادثات التي تسمحون بها. [الأسعار](https://usecircles.app/ar/pricing)

المصدر: https://usecircles.app/ar/whatsapp-api-personal-number · آخر تحديث 2026-11-01

## الواجهة في لمحة

|  | Circles HTTP API |
| --- | --- |
| العنوان الأساسي (Base URL) | `https://app.usecircles.app/api/v1/agent` |
| المصادقة | `Authorization: Bearer `: مفتاح يُنشأ في صفحة Agents (`circ_...`) أو رمز OAuth الخاص بعميل MCP. بلا ملفات تعريف ارتباط (cookies). |
| المواصفات | OpenAPI 3.1 في `https://app.usecircles.app/api/openapi.json`؛ ومرجع سهل القراءة في `https://app.usecircles.app/api` |
| الصيغة | JSON. الأوقات بتوقيت UTC، بالمللي ثانية (`at`) وبصيغة ISO 8601 (`at_iso`) |
| الصفحات | اتبعوا `pagination.next_url` حتى تصبح قيمته null؛ و`has_more` يوضح إن كان هناك المزيد. كل صفحة تعيد التحقق مما يمكن للمفتاح الوصول إليه. |
| مثل MCP | العمليات التسع، والمحادثات نفسها، والأذونات نفسها |
| فقط في API | الردود مع اقتباس، والتفاعلات بالرموز التعبيرية، وإيصالات الكتابة، وإيجاد محادثة أو بدؤها برقم |
| رقمكم | واتساب الشخصي الخاص بكم، كجهاز مرتبط. بلا WhatsApp Business، وبلا رقم ثانٍ. |

## من التسجيل إلى الاستدعاء الأول

1. **اربطوا واتساب في Circles**: ابدأوا فترة التجربة، ثم اربطوا رقمكم كجهاز مرتبط: رمز تكتبونه على هاتفكم، أو رمز QR على حاسوبكم. الرقم نفسه، وواتساب نفسه على هاتفكم. يصل السجل خلال 10 إلى 15 دقيقة تقريبا، ويمكنكم ربط وكيلكم في هذه الأثناء.
2. **أنشئوا مفتاحا**: في صفحة Agents في Circles، اختاروا *New token*، واختاروا الوكيل (أو Other)، واختاروا *API with a key*، وما يسمح به المفتاح، ومدة عمله: بلا حد، أو 90 يوما، أو سنة.
3. **سلّموه في رسالتين**: يعطيكم Circles التعليمات من دون المفتاح، ثم المفتاح وحده، حتى يذهب المفتاح فقط إلى أسرار الوكيل. ولسكربت أو لـn8n، الصقوا المفتاح مباشرة في بيانات الاعتماد لديكم.
4. **نفّذوا الاستدعاء الأول**: `GET https://app.usecircles.app/api/v1/agent/allowed_chats` مع `Authorization: Bearer circ_...`. هذه القائمة هي كل ما يمكن للمفتاح الوصول إليه.

عمليتا قراءة، والمفتاح في متغير بيئة:

```
curl -s "https://app.usecircles.app/api/v1/agent/allowed_chats" \
  -H "Authorization: Bearer $CIRCLES_KEY"

curl -s "https://app.usecircles.app/api/v1/agent/catch_up?since=2026-10-26T00:00:00Z" \
  -H "Authorization: Bearer $CIRCLES_KEY"
```

## نقاط النهاية

كلها تحت `/api/v1/agent` ما لم يُذكر غير ذلك. وثيقة OpenAPI تضم كل معامل وكل استجابة.

| نقطة النهاية | ما تفعله |
| --- | --- |
| `GET allowed_chats` | المحادثات المفتوحة لهذا المفتاح وما يمكنه فعله في كل منها. هذا كل عالمه. |
| `GET activity` | المحادثات التي تحرّكت منذ وقت معيّن: الأعداد، وآخر وقت، وآخر مرسل، بلا نص |
| `GET catch_up` | الرسائل منذ وقت معيّن، في محادثة واحدة أو في جميعها، مع أسماء المرسلين، والرسائل الصوتية مع تفريغها النصي. `kind=voice\|audio\|recording` للتصفية. |
| `GET search` | بحث نصي في محادثة واحدة أو في جميعها، بما في ذلك ما قيل في الرسائل الصوتية |
| `GET people` | من تتحدثون معهم عبر المحادثات المفتوحة، وأين |
| `GET group_members` | أعضاء مجموعة مفتوحة واحدة، بالأسماء، مع تمييز المشرفين، ومن دون أرقام أبدا |
| `GET documents` | كل ملف PDF وWord وجدول بيانات أُرسل في المحادثات المفتوحة، مع حالته |
| `POST get_media` | مرفق واحد؛ ويطلب من هاتفكم إعادة رفع مرفق أقدم عند الحاجة |
| `GET media/{ref}/status`، `content`، `view` | حالة المرفق، أو محتواه، أو الملف لعرضه في المتصفح |
| `GET chats/{chat_ref}`، `messages/{message_ref}` | التفاصيل، مع قائمة `actions` الكاملة لما يمكنكم فعله هناك |
| `POST chats/{chat_ref}/messages` | إرسال نص، أو ملف، أو ملف مع تعليق |
| `POST messages/{message_ref}/replies` | رد أصلي مع اقتباس. في API فقط. |
| `POST messages/{message_ref}/reactions` | تفاعل برمز تعبيري. في API فقط. |
| `GET writes/{submission_ref}` | إيصال عملية الكتابة، للقراءة فقط |
| `GET recipients?to=` | إيجاد محادثة برقم أو باسم محفوظ مطابق، أو بدء محادثة، عندما يسمح رقمكم ببدء المحادثات |
| `POST /api/v1/connect/exchange` | يستبدل رمز اتصال لمرة واحدة بمفتاح (هكذا يتصل Instinct). الاستدعاء الوحيد من دون Authorization. |

## الإرسال والردود والتفاعلات

تفاصيل المحادثة أو الرسالة تحمل `actions` الخاصة بها: طلبات كاملة بالطريقة والعنوان والترويسات والمحتوى. نفّذوا الطلب كما هو، وأضيفوا ترويسة `Authorization`، واملأوا فقط النص أو الملف أو الرمز التعبيري.

- **بلا تكرار (idempotent).** كل عملية كتابة تحمل مرجع إرسال أصدره Circles، مرتبطا بهدفها. إعادة استخدامه خلال 24 ساعة لا يمكن أن ترسل مرة أخرى.
- **بلا إعادة محاولة أبدا.** إذا كان الرد `delivery_unknown`، فتحققوا من الإيصال في `writes/{submission_ref}` ومن المحادثة قبل أن تقرروا الإرسال مجددا. الرسالة التي ربما خرجت لا يرسلها Circles مرتين أبدا.
- **فقط حيث يُسمح.** الإرسال والردود والتفاعلات كلها تحتاج إذن الإرسال للمفتاح ومحادثة مفتوحة للإرسال، ويُتحقق من ذلك في كل طلب. لا توجد حصة يومية. ورسالة الرفض تذكر ما ينقص وما لا يزال مسموحا.
- **الاقتباسات تفشل بأمان.** الرد الذي لا يمكن اقتباسه يُرفض.
- **غير مدعوم:** التصويت في الاستطلاعات، وإزالة تفاعل، واقتباس رسالة ليست نصا.

إرسال ملف: ضعوه حيث يصل إليه رابط https (ملف في Drive مشارك مع أي شخص لديه الرابط، أو رابط Dropbox، أو رابط موقّع مسبقا) وأضيفوا `url` الخاص به إلى المحتوى الذي يعطيكم إياه إجراء الإرسال. يُنزّل Circles الملف وقت الإرسال، حتى 10,000,000 بايت (نحو 10 MB)، ويرسله ولا يحتفظ بشيء. الرابط الذي يفتح صفحة تسجيل دخول أو صفحة عرض يُرفض. ويمكن إرسال ملف صغير موجود لديكم بصيغة base64 بدلا من ذلك. ملفات JPEG وPNG وWebP تصل كصورة، وملف MP4 كفيديو، وأي شيء آخر كمستند باسم ملفه.

```
"text": "Signed copy attached",
"file": {
  "url": "https://drive.google.com/file/d/<id>/view",
  "filename": "nda.pdf"
}
```

## الرسائل الصوتية والملفات

الرسالة الصوتية (`kind: voice`) أو الملف الصوتي (`kind: audio`) يحمل `transcript` الخاص به، مفرّغا نصيا تلقائيا بالعبرية والإنجليزية، فتقرأون ما قيل من دون جلب الصوت. ويُظهر `transcript_state` القيمة `pending` ما دام التفريغ جاريا.

المرفقات الأخرى تأتي كإعلان: اسم الملف، ونوعه، وحجمه، و`status_url`، إضافة إلى `content_url` بمجرد أن يحتفظ Circles بالملف. Circles يقدّم المحتوى، والكود الخاص بكم يقرأ ملف PDF أو الصورة. الملفات الأقدم من نحو 25 يوما عند الربط تأتي من هاتفكم عند الطلب: أرسلوا POST إلى `acquire_url`، فيعيد الهاتف رفع الملف، إذا كان متصلا.

## الحدود

| الحد | القيمة |
| --- | --- |
| رسالة نصية | حتى 65,536 حرفا |
| تعليق | حتى 4,096 حرفا |
| ملف للإرسال | نحو 3 MB |
| ملف للجلب | حتى 50 MB لكل ملف |
| عدم تكرار الكتابة | 24 ساعة لكل مرجع إرسال |
| مدة صلاحية المفتاح | بلا حد (افتراضيا)، أو 90 يوما، أو سنة؛ ويمكن إلغاؤه فورا |
| رمز اتصال لمرة واحدة | استخدام واحد، ساعة واحدة، عشر محاولات في الدقيقة لكل عنوان |

المزيد عن الحدود والأخطاء: [توثيق API وMCP](https://usecircles.app/ar/api-mcp-docs#limits).

## n8n، والسكربتات، والوكلاء الذين بنيتموهم

- **n8n:** عقدة HTTP Request مع بيانات اعتماد في الترويسة، `Authorization: Bearer circ_...`. هذا يصل إلى محادثاتكم الشخصية. عقدة واتساب الخاصة بـn8n مخصصة لحسابات WhatsApp Business.
- **السكربتات:** ملخص صباحي لثلاث مجموعات، أو تصدير لكل مستند أُرسل في محادثة مشروع، أو إحصاء أسبوعي لمن سألكم ماذا. طلبات GET بسيطة، وJSON في الرد.
- **وكيلكم الخاص:** أي شيء يستدعي HTTP. التعليمات التي يعطيها Circles مع المفتاح تشرح للوكيل كيف يقرأ، وكيف يتنقل بين الصفحات، وكيف يتصرف، وأن الإرسال لا تُعاد محاولته أبدا.
- **Dots** يتصل بهذه الطريقة أيضا: التعليمات أولا، ثم مفتاحه في رسالة منفصلة.

تفضّلون MCP؟ المحادثات والأذونات نفسها متاحة في `https://app.usecircles.app/api/mcp`: [مركز WhatsApp MCP](https://usecircles.app/ar/whatsapp-mcp).

## تغيير الصلاحيات، الباقات والدعوات

**تغيير ما يمكن للوكلاء فعله.** كل وكيل تربطونه يقرأ ويكتب افتراضياً في المحادثات التي تبقى مفتوحة، منذ البداية. للتقليل من ذلك، اجعلوا المحادثة للقراءة فقط أو أخفوها في صفحة المحادثات في تطبيق Circles، أو اكتبوا إلى خدمة عملاء Circles، الخدمة الافتراضية على رقم Circles: [wa.me/972553091640](https://wa.me/972553091640). اكتبوا إليها من واتساب الخاص بكم. يمكن للوكيل أن يصيغ لكم الرسالة. لا يمكنه فتح تلك المحادثة أو القراءة فيها أو الإرسال فيها، لأنها تحتوي على روابط تسجيل الدخول الخاصة بكم.

**الباقات.** كل باقة تقرأ وتكتب وترى كل السجل المتاح: 2 محادثات في Free، لمدة تصل إلى 3 أشهر من الربط، و10 في Plus، وكل المحادثات التي تسمحون بها في Pro. كل تسجيل يبدأ بـ 14 يوماً من Pro، من دون بطاقة. لا يُدفع أي مبلغ من دون أن تختاروا باقة. [الباقات والأسعار](https://usecircles.app/ar/pricing).

**الدعوات.** الصديق الذي تدعونه يحصل على 28 يوماً من Pro بدلاً من 14، من يوم ربطه لواتساب. وتحصلون أنتم على 14 يوماً عندما يقرأ وكيله لأول مرة عبر Circles، لما يصل إلى 10 أصدقاء في الأسبوع. اطلبوا رابط الدعوة من خدمة عملاء Circles.

## أسئلة وأجوبة

### هل لواتساب الشخصي API؟

يقدّم واتساب API رسميا فقط لـWhatsApp Business. Circles يعطي رقمكم الشخصي واجهة HTTP API بربطه كجهاز مرتبط وتقديم المحادثات التي تفتحونها فقط، مع مفتاح.

### هل هذا هو WhatsApp Business API؟

لا. Business API هو الطريقة الرسمية من Meta لتراسل الشركات عملاءها، على رقم تجاري. Circles يعمل مع رقمكم الشخصي ومحادثاتكم الحالية. [الفرق بالتفصيل](https://usecircles.app/ar/compare/whatsapp-business-api).

### هل يمكنني استخدامه مع n8n؟

نعم. استخدموا عقدة HTTP Request مع الترويسة `Authorization: Bearer circ_...` والعنوان الأساسي `https://app.usecircles.app/api/v1/agent`. عقدة واتساب المدمجة في n8n مخصصة لحسابات Business.

### هل ترسل إعادة المحاولة الرسالة نفسها مرتين؟

لا. كل عملية كتابة تحمل مرجع إرسال، وإعادة استخدامه خلال 24 ساعة لا يمكن أن ترسل مرة أخرى. وإذا كان التسليم غير مؤكد، يقول Circles ذلك ولا يعيد المحاولة من تلقاء نفسه أبدا.

### هل يمكن أن يفصل واتساب رقمي بسبب هذا؟

الوصول عبر جهاز مرتبط من عميل غير رسمي يقع خارج شروط واتساب، ولا يمكن لأحد أن يضمن ألا يُسجَّل خروج جهاز أبدا. يرسل Circles رسالة واحدة في كل مرة، ولا يرسل رسائل جماعية أبدا، ويربط كل عميل عبر عنوان IP مخصص لا يشاركه أي عميل آخر.

### كم التكلفة؟

API موجودة في كل باقات Circles: Free لمدة تصل إلى 3 أشهر، وPlus بسعر $14.90 شهريا، وPro بسعر $29.90 شهريا، مع 14 يوما من Pro مجانا. كل باقة تقرأ وتكتب عبر API.

## تابعوا القراءة

- [الرقم الشخصي مقابل Business API](https://usecircles.app/ar/compare/whatsapp-business-api): لمن يناسب كل واحد منهما.
- [توثيق API وMCP](https://usecircles.app/ar/api-mcp-docs): للوكلاء: الأدوات، والإجابات، والحدود، والمصادقة، وAPI.
- [ما يمكن للمفتاح الوصول إليه](https://usecircles.app/ar/security): أذونات لكل محادثة، سجل النشاط.

---

14 يوماً لتجربة كل شيء، مجاناً ومن دون بطاقة ائتمان. بعدها تختارون الباقة حسب ما استخدمتموه فعلاً. ابدأوا: https://usecircles.app/start?lang=en