/devices/{device_id}/webhook.
كيفية عمل التوصيل
كل عنوان URL مستهدف يتم تسليمه بشكل مستقل، مع سريه الخاص و رجاعته.تكوين
--webhook, --webhook-secret, --webhook-events, --webhook-ignore-jids, --webhook-insecure-skip-verify, --webhook-all-device-receipts.
عيّن مفتاح توقيع خاصًا بشكل صريح. إذا لم يُعيَّن المفتاح أو استُخدمت القيمة القديمة المنشورة secret، فسينشئ GOWA مفتاحًا عشوائيًا يتغير عند إعادة التشغيل ويسجّل تحذيرًا. تحتاج الجهات المستقبِلة إلى مفتاح مشترك مُعيَّن صراحةً للتحقق من التوقيعات عبر عمليات إعادة التشغيل. يجري التحقق من شهادات HTTPS افتراضيًا.
الأحداث
أسماء الأحداث في قائمة المسموح بها حساسة لحالة الأحرف.
حمولة
كل طلب له نفس الظرف :
الردود تضيف
replied_to_id وquoted_body. الايصالات تستخدم ids (الصفيفة) وreceipt_type. أحداث المشاركين في المجموعة تحمل شكل chat_id، و type، و jids. تغيير اسم المجموعة يستخدم شكل group.info منفصل.
sender_display_name يظهر فقط عندما يكون from سلسلة غير فارغة. لمرسل آخر، تفضل GOWA اسم جهة الاتصال المحفوظة، اسم الدفع للحدث المباشر، اسم الدفع المخزن، اسم الأعمال، ثم جزء المستخدم JID. بالنسبة للحساب النشط، يفضل اسم الدفع للحساب، ثم هوية الإشراف عليه. الحل هو أفضل جهد. الإرث from_name يبقى اسم دفع حدث الرسالة.
قد تتضمن الرسائل الواردة is_business: true وverified_name وverified_level عندما يوفّر WhatsApp شهادة اسم موثَّق. تُحذف هذه الحقول في الحالات الأخرى. لا يثبت غيابها ما إذا كان المرسِل نشاطًا تجاريًا، وتمثّل verified_level القيمة الخام الواردة من المصدر، ولا تضمن وجود شارة رسمية.
الوسائط
معWHATSAPP_AUTO_DOWNLOAD_MEDIA=true (الافتراضي)، يتم حفظ الوسائط تحت statics/media/ ويحتفظ حقل الوسائط بالمسار:
{"path": "...", "caption": "..."} ويَرِد التعليق التوضيحي أيضًا في body. عند إيقاف التنزيل التلقائي، يكون الحقل {"url": "https://mmg.whatsapp.net/...", "caption": "..."}؛ ويمكن جلب الملف لاحقًا باستخدام GET /message/{message_id}/download?phone=<chat>.
الفهرس الكامل للحمولات (استطلاعات الرأي، المواقع، جهات الاتصال، المشاهدة، الإحالات الإعلانية والمزيد) موجود في أعلى مرجع تحميل webhook payload.
الألبومات والرسائل المنظمة
يصل الألبوم في صورة عدة أحداثmessage. لا تحتوي ترويسة الألبوم على متن رسالة، وتحمل الأعداد المتوقعة للعناصر:
album_id: "ALBUM_HEADER_ID". مجموعة العناصر بواسطة هذا المعرف. الترويسة ليست عنصر وسائط قابل للتنزيل ولا يتم إرساله إلى Chatwoot.
يستخدم إنشاء استطلاعات الرأي والتصويت وتعديل الاستطلاعات وإضافة الخيارات حدث message أيضًا. افحص كائن poll المنظَّم بدلًا من الاعتماد على body. تجزئات الخيارات هي تجزئات SHA-256 سداسية عشرية بأحرف صغيرة لأسماء الخيارات كما هي تمامًا. تتلقى الاشتراكات الحالية في WHATSAPP_WEBHOOK_EVENTS=message هذه التفاعلات.
التواجد عبر الإنترنت ودون اتصال
اشترك لكل جهة اتصال فردية باستخدام نفس الجهاز الذي يتلقى الأحداث:results.subscribed: true و results.jid. الاشتراك لا يتجاوز إعدادات وجود جهازك. للحصول على تحديثات مستمرة، ابدأ GOWA بما يلي:
state هي available أو unavailable. يُحذف last_seen عندما يكون غير معروف أو مخفيًا بإعدادات خصوصية جهة الاتصال. يُدرَج from_lid عند انطباقه. تظل الكتابة والتسجيل حدثين منفصلين من نوع chat_presence ولا يستخدمان هذا الاشتراك.
تغيير اسم المجموعة
name_set_by من LID إلى JID الهاتف عندما يكون ذلك ممكنا وحذف عندما لا يقوم WhatsApp بتحديد الممثل. اشترك في group.info صراحة إذا كانت قائمة السماح للحدث الخاص بك تستثني أحداث أخرى.
تحديثات عداد النشرة الإخبارية
يُبلغnewsletter.message عن العدادات المباشرة، ولا يضمن تضمين متن منشور جديد. تتضمن الإدخالات دائمًا server_id. تُحذف message_id وtype وtimestamp عندما لا يوفّرها WhatsApp. وقد تُحذف العدادات ذات القيمة صفر أو غير المتوفرة.
reaction_counts يحتوي على إحصائيات رد فعل WhatsApp. استهلك التحديثات بواسطة معرف النشرة الإخبارية ومعرّف الخادم. لا تعامل عداد المفقودين كإعادة تعيين إلى الصفر.
قيود الحساب وتسجيل الخروج
أحداث الجهاز تحمل دائماsession_id، لذا تبقى الفتحات التي تستخدم نفس رقم WhatsApp قابلة للتمييز. يستخدم الحدث تكوين webhook الخاص بخانة الانبعاثات. تسجيل الخروج عن بعد يحتفظ بالفتحة لإعادة الاقتران والإبلاغ عن الهوية من قبل تسجيل الخروج. خيارات إعدادات webhook تبقى على قيد الحياة إعادة الإقران. هذه الأحداث لا ترسل إلى Chatwooot.
تُمرَّر الرموز دون تغيير ويأتي نص السبب من whatsmeow. تستمر الرموز غير المعروفة في الوصول أيضًا. لا يحدّد رمزا تسجيل الخروج
403 و406 وحدهما السبب الدقيق. تعني مدة حظر مؤقت قدرها صفر أن WhatsApp لم يحدّد موعد انتهاء. يقيّد القفل الزمني للتواصل بدء محادثات جديدة وقد يؤدي إلى خطأ الإرسال 463.
التحقق من التوقيعات
ويحمل كل طلبX-Hub-Signature-256: sha256=<hex>، وهو من HMAC-SHA256 من جسم الطلب الخام المفتاح مع سر ويبهوك. حسبها على وحدات البايت التي تم تلقيها بالضبط، قبل تحليل JSON.
التسليم وإعادة المحاولات
- كل محاولة تنتهي بعد 10 ثوان.
- تتم محاولة أي رد غير 2xx أو خطأ في الشبكة. وتتألف GOWA من 5 محاولات، تنتظر 1 و 2 و 4 و 8 ثوان فيما بينها. والموعد النهائي لمعالج الأحداث يمكن أن يتوقف عن التسليم قبل اكتمال جميع المحاولات.
- بعد الفشل الأخير، يتم إسقاط الحدث وتسجيله. لا يوجد قائمة انتظار مستمرة أو متجر أحرف ميتة.
- يتم تسليم العديد من عناوين المواقع بشكل مستقل.
2xx بعد قبول الحدث في قائمة انتظار المعالجة الدائمة لديك. صمّم المعالجات بحيث لا يؤدي تكرار التنفيذ إلى آثار إضافية، لأن الحدث المُعاد إرساله قد يصل أكثر من مرة.
إيصالات الجهاز المرتبط
بشكل افتراضي، توجه GOWA تعبيرات الاتصال من الأجهزة الرئيسية فقط لتقليل التكرار. ويمر الإيصالات الخاصة بالحساب الحاليread و read-self من جميع أجهزته. بالنسبة لإيصالات الحساب الخاص هذه، payload.from هو حساب JID و payload.ids تحدد الرسائل الواردة التي تم قراءتها.
اضبط WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true أو --webhook-all-device-receipts=true لتلقي إيصالات جهات الاتصال من الأجهزة المرتبطة أيضًا، بما في ذلك عندما يكون هاتف جهة الاتصال غير متصل. يتجاوز خيار سطر الأوامر إعداد البيئة، حتى عند تعيينه صراحةً إلى false.
يمكن لهذا الخيار أن ينتج تعبيرات مكررة أو خارجة عن الطلب. تطبيق التحديثات بدقة، لكل حساب، ودردشة، ومعرّف الرسالة. لا تقلل أبدا من قيمة الرسالة المقروءة التي يتم تسليمها عند وصول إيصال قديم. تحتفظ معرفات الرسائل و JIDs المرسل بنسختها الكلاسيكية بدون ملحقات الجهاز.
تصفية الأحداث
بحسب النوع: يمرّرWHATSAPP_WEBHOOK_EVENTS=message,message.ack هذه الأحداث فقط.
بواسطة الدردشة أو المرسل: يتطابق WHATSAPP_WEBHOOK_IGNORE_JIDS مع chat_id، from، chat_lid وfrom_lid. المدخلات التي تبدأ بـ @ هي بطاقات برية لكامل مساحة العناوين (@g.us، @s.whatsapp.net، @lid)؛ وأي شيء آخر هو JID.
@s.whatsapp.net تطابق أيضا رسائل المجموعة، لأن from هي JID. استخدم @g.us لكتم المجموعات. الفلاتر مجتمعة: الحدث لا يتم إرساله إلا إذا كان نوعه مسموحاً به و لم يتم تجاهل إجابته في الإصدار.
كل جهازك
إعطاء فتحة خاصة به على شبكة الويبوك، سرية وقائمة السماح للحدث:POST /devices. اقرأ الإعداد الحالي مع GET /devices/{device_id}/webhook. أرسل "webhook_url": "" لمسالته.
إذا كانت قيمة webhook_secret أو webhook_events الخاصة بالجهاز فارغة، فيُستخدم الإعداد العام المقابل. تحل القيمة المنطقية المخزّنة للجهاز في webhook_insecure_skip_verify محل إعداد TLS العام. وعلى وجه التحديد، تُبقي القيمة false التحقق من الشهادات مفعّلًا حتى عند تفعيل التجاوز العام.
بشكل افتراضي عنوان URL لكل جهاز يستبدل عنوان WHATSAPP_WEBHOOK العام لهذا الفتح. مع WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true، يتم إضافة إلى عناوين URL العالمية بدلاً من ذلك: يستخدم عنوان URL الجهاز سر الجهاز وقائمة السماح، عناوين URL العالمية تحافظ على عناوين الإنترنت، و عنوان URL موجود في كليهما يتلقى الحدث مرة واحدة. وتنطبق قواعد تجاهل التنفيذ على كليهما.
اختبار محليا
أتِح الوصول إلى مستقبِل محلي عبر نفق (مثلngrok http 8080) واضبط WHATSAPP_WEBHOOK على عنوان URL للنفق. عند ضبط --debug=true، يسجّل GOWA كل محاولة تسليم وكل إخفاق.
طرق أخرى لتلقي الأحداث
- WebSocket في
/ws?device_id=<id>يدفع أزواج أحداث الحالة إلى عملاء لوحة المعلومات. استخدم webhooks لإيصال الرسائل. - الاقتراع:
GET /chatsوGET /chat/{chat_jid}/messagesقراءة وحدة تخزين الدردشة المحلية لـ GOWA. انظر تلقي الرسائل.
