المحادثات وجهات الاتصال والمجموعات

حيثما وجدت {phone} في مسار، استخدم رقم الشخص بالصيغة الدولية، أو chat_id ينتهي بـ @lid من ويب هوك.

قراءات من الهاتف. جهات اتصال الرقم ومجموعاته وقنواته ورابط دعوة المجموعة والملف الشخصي تُقرأ من الهاتف المربوط وأنت تنتظر. تُحفظ القوائم ورابط الدعوة لمدة 30 ثانية، فالتغيير الذي يتم على الهاتف قد يحتاج هذه المدة ليظهر؛ أما التغيير عبر الـ API فيظهر فورًا. يجيب الرقم عن قراءتين من هذا النوع في الوقت نفسه: الثالثة في اللحظة نفسها تحصل على 429 مع الرمز busy وRetry-After مدته بضع ثوانٍ. اقرأ هذه واحدة تلو الأخرى، لا كلها دفعة واحدة.

المحادثات

محادثاتك: GET /v1/chats يسرد كل شخص تتحدث معه أرقامك، الأحدث أولًا. ومع كل محادثة آخر رسالة (من آخر 30 يومًا، وهي مدة حفظ الرسائل) وwaiting_for_reply (هو من كتب آخر رسالة، ولم يحدد أحد المحادثة كمنتهية في لوحة التحكم). waiting=1 يسرد هؤلاء فقط؛ وinstance_id محادثات رقم واحد.
السجل من الهاتف: GET /v1/instances/{id}/chats/{phone}/history يقرأ الرسائل التي يحتفظ بها واتساب لمحادثة فردية على الهاتف المربوط. وهي ما زامنه الهاتف عند ربطه (نحو يوم قبل الربط) وكل ما بعده، ومنه ما كُتب على الهاتف. الأحدث أولًا، وlimit حجم الصفحة (حتى 100، و50 افتراضيًا؛ وقد تحتوي الصفحة على أقل) وoffset للأقدم. لكل رسالة id الخاص بواتساب، وmessage_id الخاص بنا إن كانت موجودة أيضًا في GET /v1/messages، وfrom_me وbody وhas_media (الملفات غير مضمّنة) وsent_at. فقط لمحادثة لدى الرقم (أي شخص آخر 404)، وليس لمجموعة أبدًا؛ ورموز OTP تُحجب. لا يرسل شيئًا إلى واتساب؛ بحد أقصى 30 صفحة في الدقيقة لكل رقم.
الأرشفة وغير المقروءة: POST /v1/instances/{id}/chats/{phone}/archive أو /unarchive أو /unread، كما في التطبيق.

جهات الاتصال

GET /v1/instances/{id}/contacts يسرد جهات اتصال واتساب على الهاتف المربوط: name كما حُفظ هناك، وpush_name كما يُظهره صاحبه. 100 في الصفحة؛ وقد تحتوي الصفحة على أقل، والصفحة الفارغة هي النهاية.
GET /v1/instances/{id}/contacts/{phone} يعطي شخصًا واحدًا يعرفه الرقم (جهة اتصال على الهاتف، أو شخص له محادثة معه). ومعه picture_url، وهي صورة ملفه الشخصي كما يقدّمها واتساب (تنتهي صلاحيتها؛ وتكون null إن لم تكن له صورة أو أخفاها). أي شخص آخر 404، لأن البحث عن الغرباء هو ما يعدّه واتساب جمعًا للبيانات. يحتاج مفتاحًا يمكنه الإرسال.

البحث عن جهات الاتصال والأرشفة وغير المقروءة تشترك في حد 20 في الدقيقة لكل رقم.

حقول جهات الاتصال

حقول جهات الاتصال هي ما يحتفظ به فريقك عن الأشخاص الذين يكتبون إليك، مثل رقم العميل أو المدينة. ينشئ المسؤول الحقول في صفحة المحادثات بلوحة التحكم، ويملؤها فريقك من داخل المحادثة.

GET /v1/contact-fields يسرد حقولك: لكل منها key وname وkind (text أو number أو date أو list) وoptions للقائمة.
GET /v1/chats/{phone}/contact-fields يعطي ما تقوله عن شخص واحد: كل مفتاح تحت fields، مع null حيث لا شيء محفوظ.
PUT /v1/chats/{phone}/contact-fields يضبطها. أرسل fields كأزواج مفتاح وقيمة. المفتاح الذي تتركه يبقى كما هو، وnull تمسحه. يحتاج مفتاحًا بوصول كامل.

curl -X PUT https://threadwire.net/api/v1/chats/201012345678/contact-fields \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"fields": {"city": "Giza", "renewal": "2026-12-01"}}'

يُكتب التاريخ YYYY-MM-DD، والقائمة تأخذ أحد خياراتها، وتعود القيم كنص. القيمة التي لا يقبلها حقلها تُرد بـ 422 يسمّي المفتاح.

الشخص نفسه له الحقول نفسها على كل أرقامك، سواء سمّيته برقم هاتفه أو بـ chat_id الذي أعطاه ويب هوك. التغييرات التي تتم بمفتاح تظهر في سجل النشاط لديك سطرًا واحدًا في الساعة لذلك المفتاح، مهما كان عدد من غيّرهم. وهي فقط لمن كتب إليك: أي شخص آخر 404، ولا يوجد استيراد. ويصلح مفتاح الحقل أيضًا حقلًا في نص رسالة جماعية.

التصنيفات (تطبيق WhatsApp Business فقط)

GET وPOST /v1/instances/{id}/labels (name، وcolor من 0 إلى 19).
PUT أو DELETE /v1/instances/{id}/labels/{label}؛ والتصنيف المحذوف يُزال من كل محادثة.
GET /v1/instances/{id}/labels/{label}/chats: المحادثات التي عليها تصنيف.
GET أو PUT /v1/instances/{id}/chats/{phone}/labels: تصنيفات محادثة. PUT يأخذ القائمة الكاملة لقيم id الخاصة بالتصنيفات؛ وما تُرك منها يُزال.

يعرضها الهاتف أيضًا.

الحالات

POST /v1/instances/{id}/statuses ينشر حالة واتساب (قصة تراها جهات اتصالك لمدة 24 ساعة). وهي إما text على background_color (وfont من 0 إلى 5)، أو image أو video أو voice عبر url أو base64 في data، مع text كتعليق. (وبصيغة data تُحتسب للحساب ضمن الملفات بصيغة base64 في اليوم.) audience (أرقام هواتف) يحدد من يراها. يرد بـ queued، وتصبح posted عندما تصل إلى واتساب.

كل من في audience يجب أن يعرف الرقم (راسله، أو محفوظ كجهة اتصال على الهاتف) وألا يكون قد كتب "STOP". فالحالة التي تأتي من رقم لا يعرفه الشخص هي ما يبلّغ عنه الناس، لذا الطلب الذي يسمّي أي شخص آخر يرد بـ 422 مع ذكرهم. التحقق من كون شخص جهة اتصال محفوظة يسأل واتساب، فيمكن التحقق من 20 شخصًا على الأكثر في الدقيقة ممن لم يكتبوا قط (429 بعد ذلك).
بحد أقصى 30 في اليوم لكل رقم.
GET يسردها مع views وأرقام هواتف viewers؛ وDELETE /v1/instances/{id}/statuses/{status} يحذف واحدة؛ ولا تُحذف إلا حالة منشورة (409 في غير ذلك).

الطلبات والمنتجات

الطلب الذي يرسله شخص من كتالوج WhatsApp Business لديك يصل بـ type قيمته order (ومعه order: order_id وtitle وitems وtotal وcurrency)، والمنتج المشارَك بـ type قيمته product. إدارة الكتالوج نفسه غير متاحة بعد.

المجموعات

GET /v1/instances/{id}/groups يسرد المجموعات التي فيها الرقم، مع chat_id لكل منها.
POST ينشئ مجموعة بـ subject وparticipants.
GET، أو PATCH (subject، description، messages_admin_only: المشرفون فقط يكتبون، info_admin_only: المشرفون فقط يغيّرون اسمها ووصفها)، /v1/instances/{id}/groups/{group}.
POST …/participants مع action قيمته add أو remove أو promote أو demote.
GET …/invite يعطي رابط الدعوة؛ وPOST …/invite/revoke ينشئ رابطًا جديدًا، فيتوقف القديم عن العمل.
POST …/leave يغادرها؛ وPOST /v1/instances/{id}/groups/join مع invite ينضم إلى مجموعة.

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

الحدود لكل رقم: بحد أقصى 5 مجموعات تُنشأ، و5 يُنضم إليها، و50 شخصًا يُضافون في اليوم.

القنوات

GET /v1/instances/{id}/channels (role قيمته owner أو admin أو subscriber)؛ وPOST ينشئ قناة بـ name (بحد أقصى 2 في اليوم)؛ وGET أو DELETE /v1/instances/{id}/channels/{channel}.

الإرسال إلى مجموعة أو قناة

POST /v1/messages مع chat_id (وهو …@g.us لمجموعة أو …@newsletter لقناة) بدلًا من to. تُرسل بتمهّل مثل أي رسالة؛ بحد أقصى 200 رسالة للمجموعات و30 منشورًا في القنوات يوميًا لكل رقم، و20 في الساعة للمجموعة الواحدة.

رسائل المجموعات التي يكتبها الناس تصل كويب هوك group.message (المجموعة هي chat_id، والكاتب participant؛ والملفات المنشورة في المجموعات تُذكر لكنها لا تُحفظ)، والتغييرات على مجموعة تصل كـ group.update. حدّد الاثنين من للمطورين ← الويب هوك ← الأحداث لتستقبلهما. من كتب في مجموعة لم يكتب إلى رقمك: فالرسالة إليه وحده تبقى رسالة أولى.

المحادثات وجهات الاتصال والمجموعات