توثيق API وMCP في Circles

• اعرفوا عالمكم. allowed_chats تعرض كل محادثة مفتوحة لكم، وهل يمكنكم الإرسال فيها. المحادثة غير الموجودة في القائمة لا يمكن قراءتها ولا البحث فيها. الطريق الوحيد خارج القائمة هو محادثة جديدة: عندما يكون الإعداد الافتراضي للرقم قراءة وإرسال، تستطيع send أن تبدأ محادثة مع شخص جديد، برقم هاتفه أو بالاسم الدقيق لجهة اتصال محفوظة (GET /recipients?to= عبر HTTP).
• «ماذا فاتني؟» استدعوا activity مع وقت since أولًا (أعداد فقط، وكلفة قليلة)، ثم catch_up للمحادثات التي تحركت. الرسائل الصوتية تصل نصًا في media.transcript.
• الرفض إجابة. يأتي مع isError: false ويذكر ما هو مفتوح أو مسموح. انقلوه إلى الشخص؛ ولا تعيدوا المحاولة.
• الإرسال يتكلم باسم الشخص. طريقة التحقق معه قبل الإرسال أمر بينكم وبينه: بعض الناس يريدون رؤية كل رسالة، وبعضهم أخبركم بما يمكنكم إرساله وحدكم. عند الشك، اعرضوا عليه النص والمحادثة أولًا. confirmed اختياري. لا تُعاد محاولة الإرسال أبدًا: إذا كان التسليم غير مؤكد، اقرؤوا المحادثة قبل أن تقرروا أي شيء.
• الأوقات بتوقيت UTC. لا يعرف Circles أين يوجد الشخص؛ حوّلوا الأوقات له بأنفسكم.
• لم تتصلوا بعد؟ يربط الشخص واتساب ويربطكم باتباع الأدلة في usecircles.app/ar/docs. لا يطلب منكم Circles أبدًا كلمة مروره أو رمز واتساب.

allowed_chats: بلا معاملات. المحادثات المفتوحة للوكلاء، لكل منها name وkind وaccess (read only أو read and send) وarchived حيث يكون مضبوطًا. هذا هو العالم كله: المحادثة غير الموجودة هنا لا يمكن قراءتها ولا البحث فيها ولا الإرسال إليها. تحمل أيضًا connection (not_linked، subscription_ended) وsubscription.ends_at عندما تقترب باقة ملغاة من نهايتها.

activity: since (ISO 8601، مطلوب). أي المحادثات المفتوحة تحركت: عدد الرسائل، وlast_at / last_at_iso، وlast_from. أعداد فقط، بلا نص. الاستدعاء الأول قليل الكلفة لسؤال «ماذا فاتني؟».

catch_up: since (مطلوب)، chat، limit، per_chat، kind. الرسائل منذ وقت معيّن، الأقدم أولًا، والمرسلون بأسمائهم. مع chat: تلك المحادثة، وlimit افتراضيًا 50 وحده الأقصى 200، مع الاحتفاظ بالأحدث. بدونها: كل محادثة مفتوحة تحركت، الأحدث أولًا، وper_chat افتراضيًا 20 وحده الأقصى 50، ضمن مجموع 150؛ والمحادثة التي فيها أكثر تذكر more. قيمة kind هي voice أو audio أو recording (أيٌّ منهما). المرفقات يُعلن عنها فقط. اجلبوا أحدها بـ get_media.

search: query (مطلوب)، chat، days (من 1 إلى 36,500؛ الافتراضي: كل السجل المحفوظ)، kind. بحث نصي لا يميّز بين الأحرف الكبيرة والصغيرة في محادثة مفتوحة واحدة أو فيها كلها، يطابق ما كُتب وما تقوله الرسائل الصوتية والملفات الصوتية. كل نتيجة تذكر محادثتها عند البحث في الكل.

people: since (مطلوب)، limit (افتراضيًا 60، والحد الأقصى 150)، min_messages (افتراضيًا 3). مع من يتحدث الشخص عبر المحادثات المفتوحة: أعداد المحادثات الفردية، والمجموعات المشتركة، والرسائل في كل مجموعة. تعيد أسماء فقط، بلا أرقام وبلا نص.

group_members: chat (مطلوب). أعضاء مجموعة مفتوحة واحدة من قائمة أعضاء واتساب، بمن فيهم من لم يكتب أبدًا. الاسم المحفوظ، وإلا الاسم الذي يكتب به، وإلا اسمه في واتساب مع العلامة ~. المشرفون معلَّمون. 300 اسم على الأكثر؛ الأعضاء الذين ليس لهم اسم ولا رقم يُحسبون في unnamed. كل عضو يحمل phone، رقمه، حيثما يُظهره واتساب.

documents: since (مطلوب). كل ملف PDF وملف Word وجدول أُرسل في المحادثات المفتوحة: اسم الملف، والتاريخ، والمحادثات التي أُرسل إليها (إدخال واحد لكل ملف)، وref وstate. أسماء وتواريخ فقط.

get_media: ref (مطلوب). مرفق واحد، بترميز base64 في bytes_base64، مع mime وfilename وsize_bytes. حتى 50 MB لكل ملف. لملف on_request تطلب من الهاتف إعادة رفعه وتنتظر نحو 25 ثانية. مرجع واحد في كل استدعاء. الوكيل يقرأ الملف بنفسه. Circles لا يشغّل OCR، ولا يصف الصور، ولا يستخرج نص PDF.

send: chat وtext (مطلوبان)، confirmed (اختياري)، file (url، أو mime وdata_base64؛ filename، sha256)، from. رسالة واحدة إلى محادثة مفتوحة للإرسال: نص حتى 65,536 حرفًا، أو ملف (حتى 10 MB عبر رابط، ونحو 3 MB بترميز base64) والنص تعليق عليه (حتى 4,096). أفضل طريقة لإرسال ملف هي الرابط: ضعوه حيث يصل إليه رابط https (ملف Drive مشارك مع كل من لديه الرابط، أو رابط Dropbox أو رابط موقّع مسبقًا) وأعطوا url. يُنزّله Circles وقت الإرسال، ويرسله ولا يحتفظ بشيء؛ والإجابة تذكر الحجم وقيمة SHA-256 لما أُرسل. الرابط الذي يفتح صفحة تسجيل دخول أو صفحة عرض يُرفض. ترميز base64 للملف الصغير الموجود في متناولكم. ملفات JPEG وPNG وWebP تُرسل كصورة، وMP4 و3GP كفيديو، وأي شيء آخر كمستند باسمه. عندما يكون الإعداد الافتراضي للرقم قراءة وإرسال، يمكن أن تكون chat رقم هاتف مع رمز بلده أو الاسم الدقيق لجهة اتصال محفوظة، لبدء محادثة جديدة؛ وfrom تحدد الرقم عندما يصلح أكثر من رقم. لا حصة يومية؛ يُفحص كل استدعاء، ولا تُعاد المحاولة أبدًا. confirmed، عند تقديمه، هو تصريح من الوكيل بأن الشخص راجع هذه الرسالة؛ Circles لا يطلب أي موافقة، ولا يستطيع التحقق منه، ولا يعامله كإذن.

الغلاف. كل أداة تجيب بعنصر نصي واحد. في الإجابة، يكون content[0].text بصيغة JSON (منسّقًا للقراءة). وفي الرفض، يكون جملة عادية. في الحالتين تكون isError هي false: اقرؤوا الرفض وانقلوه. لا تعيدوا المحاولة.

الرفض يذكر ما هو مسموح. «No chat named X is open to agents. What IS open: A, B.» أو «X is open for reading only.» المحادثة المخفية لا يُذكر اسمها أبدًا، لذلك لا يستطيع الرفض أن يخبر الوكيل إن كانت محادثة ما موجودة. «لا توجد رسائل» و«لا يمكنكم رؤية تلك المحادثة» لا يُخلط بينهما أبدًا.

التغطية. عندما يصل طلب إلى ما قبل أقدم ما هو محفوظ، تحمل الإجابة coverage التي تذكر أين يبدأ السجل المحفوظ ولماذا، وتنتهي بـ «Nothing was hidden from you.» غياب coverage يعني أن لا شيء ناقص في النافذة الزمنية.

الأوقات بتوقيت UTC: at بالمللي ثانية منذ 1970 وat_iso بصيغة ISO 8601 وتنتهي بـ Z (وكذلك last_at / last_at_iso). لا يعرف Circles أين يوجد الشخص ولا يحوّل شيئًا.

الرسائل الصوتية. قيمة media.kind هي voice لرسالة صوتية في واتساب وaudio لملف صوتي. كلاهما يحمل transcript وtranscript_state: pending (ما زال قيد التفريغ)، done، empty (لم يُقل شيء) أو failed؛ وduration_seconds حيث يقدّمه واتساب. التفريغ تلقائي، بالعبرية والإنجليزية. الرسالة الصوتية التي مضى عليها أكثر من نحو 25 يومًا عند الربط تُفرَّغ بعد جلبها.

حالات المرفقات. لكل ملف مُعلن عنه state:

• available: get_media تعيده الآن.
• downloading: يصل من تلقاء نفسه، عادةً خلال دقيقة. اطلبوه مرة أخرى بعد قليل.
• on_request: لم يعد موجودًا لدى واتساب؛ get_media تطلب من هاتف الشخص إعادة رفعه (يجب أن يكون الهاتف متصلًا بالإنترنت) وتنتظر نحو 25 ثانية.
• fetching: الهاتف لم يرد بعد. الملف لم يضِع: اطلبوه مرة أخرى بالمرجع نفسه بعد دقيقة تقريبًا؛ والتكرار ينضم إلى الطلب الجاري.
• gone: لم يستطع الهاتف إعادة رفعه. قولوا ذلك؛ ولا تعيدوا المحاولة.
• too_large: أكبر من 50 MB، وهو حد الاستدعاء الواحد.
• failed: لم يمكن تنزيله بعد. لا شيء على الشخص فعله.

وفي الرسائل أيضًا: reactions (الرمز التعبيري، ومن، ومتى) بعد أن يتفاعل أحد، من 2026-10-27 فصاعدًا. التعديلات في واتساب تحدّث النص المخزّن؛ و«الحذف لدى الجميع» يزيل الرسالة. المواقع وبطاقات جهات الاتصال والاستطلاعات تُحفظ كرسائل فارغة حتى لا تكون في المحادثة فجوات. معاينات الروابط وسياق الرسائل المقتبسة غير مضمّنة.

مثال مختصر، بأشخاص متخيَّلين (نص الإجابات نفسه بالإنجليزية):

الصلاحية تضيّق ولا توسّع أبدًا. رمز الوصول الذي يحمل كل الصلاحيات يصل مع ذلك فقط إلى المحادثات التي فتحها الشخص، لأن مستويات المحادثات تُقرأ من جديد في كل استدعاء.

كل طلب يحمل Authorization: Bearer <key>: مفتاح circ_ مُنشأ أو رمز OAuth لعميل MCP. لا يُقبل أي شيء آخر، ولا ملفات تعريف الارتباط (cookies).

• القراءة: GET https://app.usecircles.app/api/v1/agent/allowed_chats، /activity، /people، /catch_up، /search، /documents، /group_members، بالمعاملات نفسها التي في الأدوات.
• التفاصيل: GET /chats/{chat_ref} وGET /messages/{message_ref} تعيدان ما هو مسموح (capabilities، مع الأسباب والملاحظات) وactions كاملة.
• الإرسال: POST /chats/{chat_ref}/messages (نص، أو ملف حتى نحو 3 MB مع تعليق اختياري).
• الرد: POST /messages/{message_ref}/replies، رد مقتبس أصلي في واتساب. الرد الذي لا يمكن اقتباسه يُرفض.
• التفاعل: POST /messages/{message_ref}/reactions، تفاعل برمز تعبيري.
• محادثة جديدة: GET /recipients?to= مع رقم هاتف (مع رمز البلد، بترميز URL) أو الاسم الدقيق لجهة اتصال محفوظة؛ ويجيب مثل تفاصيل محادثة.
• إيصال الكتابة: GET /writes/{submission_ref}.
• الملفات: POST /get_media (قد يطلب الملف من الهاتف)، وGET /media/{ref}/status و/content و/view (لا تطلب من الهاتف أبدًا).
• رمز الربط: POST https://app.usecircles.app/api/v1/connect/exchange.

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

كتابة لا تتكرر (idempotent). كل عملية كتابة تحمل مرجع إرسال يصدره الخادم ومرتبطًا بالهدف. إعادة استخدامه لا يمكن أن ترسل مرة أخرى، لمدة 24 ساعة. التسليم غير المؤكد يعيد delivery_unknown ولا تُعاد محاولته أبدًا: اقرؤوا الإيصال والمحادثة قبل تقديم إرسال جديد ومقصود.

الترقيم. إجابات القوائم تحمل pagination.next_url وhas_more في المستوى الأعلى. اتبعوا next_url حتى يصبح null؛ وكل صفحة تعيد فحص التفويض. صفحات catch_up تبدأ من أحدث الرسائل وترجع إلى الوراء.

الأخطاء. الخطأ 401 يعني أن المفتاح لم يعد يعمل. الخطأ 403 scope_required يعني أن الشخص لم يمنح تلك الصلاحية. المعامل غير الصالح يُذكر اسم حقله ونطاقه المسموح.

غير مدعوم: التصويت في الاستطلاعات، وإزالة تفاعل، واقتباس رسالة ليست نصًا.

• 2026-11-01: القراءة والكتابة افتراضيًا: الرقم المرتبط حديثًا يفتح محادثاته للقراءة والإرسال، وربط الوكيل الجديد يحمل صلاحية الإرسال. كل باقة تكتب، ولا توجد حصة إرسال يومية، وأداة الإرسال تظهر لأي وكيل مربوط مع الإرسال. عقد MCP بالإصدار 0.19.0 وHTTP API بالإصدار 2.1.0. الوكيل الذي خزّن قائمة أدواته يطلبها من جديد (tools/list) ليرى send.
• 2026-10-27: يتصل Instinct برمز لمرة واحدة يُرسل من واتساب، دون عرض أي مفتاح أو لصقه.
• 2026-10-27: يمكن أن تكون الرسالة بالطول الذي يسمح به واتساب: 65,536 حرفًا.
• 2026-10-27: التفاعلات تُحفظ على رسالتها وتظهر في كل قراءة.
• 2026-10-27: المحادثات الفردية تُفتح للقراءة افتراضيًا في رقم جديد.
• 2026-10-27: HTTP API بالإصدار 2.0.0: أُزيل وكلاء المتصفح؛ وAPI الوكلاء يقبل مفتاح Bearer فقط.
• 2026-10-26: الاشتراك الملغى يستمر في العمل حتى نهاية الفترة المدفوعة، وallowed_chats تخبر الوكيل بالتاريخ.
• 2026-10-23: يمكن للوكلاء مراسلة شخص لا توجد معه محادثة بعد، برقم الهاتف أو باسم جهة الاتصال المحفوظة.
• 2026-10-19: يمكن للوكلاء إرسال ملف من أي نوع: PDF، أو مستند، أو فيديو، أو صورة.
• 2026-10-19: التسجيلات: مرشحات kind=voice|audio|recording وduration_seconds؛ وكل وقت يُذكر بتوقيت UTC.
• 2026-10-19: يتصل Claude بالعنوان، مع الموافقة في صفحة Circles.
• 2026-10-18: تُفرَّغ الرسائل الصوتية تلقائيًا، ويقرأ الوكلاء النص على الرسالة.
• 2026-10-18: السجل الكامل هو الافتراضي، للأرقام الجديدة والحالية.
• 2026-10-16: HTTP API مع ردود أصلية وتفاعلات؛ وتُطبَّق التعديلات وعمليات الحذف التي تتم في واتساب.

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

الباقات. كل باقة تقرأ وتكتب وترى كل السجل المتاح: 2 محادثات في Free، لمدة تصل إلى 3 أشهر من الربط، و10 في Plus، وكل المحادثات التي تسمحون بها في Pro. كل تسجيل يبدأ بـ 14 يوماً من Pro، من دون بطاقة. لا يُدفع أي مبلغ من دون أن تختاروا باقة. الباقات والأسعار.

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