المتطلبات
- يمكن الوصول إلى GOWA من Chatwoot عبر عنوان URL عام (لرد وكيل على webhooks).
- حساب Chatwoot مع وصول المشرف و رمز وصول API للمستخدم.
- جهاز واحد على الأقل مسجل الدخول في WhatsApp.
إعداد
1
إنشاء صندوق الوارد لقناة API
في Chatwoot، انتقل إلى إعدادات → علب الوارد → إضافة علبة الوارد → API. لاحظ معرف علبة الوارد الرقمية من عنوان البريد الوارد، و سر الويبهوك مسلسلات الدردشة للقناة. وبدلا من ذلك، دعوا GOWA تنشئ صندوق الوارد (انظر Auto-provisioning).
2
جمع المعرفات و الرمز المميز
معرف الحساب هو الرقم في
/app/accounts/<id>/.... انسخ رمز الوصول للمستخدم من إعدادات الملف الشخصي. يجب أن يكون كل من المعرفين المعرفين الرقميين، وليس القناة identifier أو hmac_token.3
تكوين GOWA
.env
4
نقطة الدردشة في GOWA
عيّن عنوان URL لقناة API webhook إلى
https://gowa.example.com/chatwoot/webhook (مع APP_BASE_PATH، تضمين المسار الأساسي). هذا المسار عام: فهو محمي من قبل سر ويبهوك وليس من قبل المصادقة الأساسية.5
اختبار
رسالة رقم WhatsApp من هاتف آخر؛ يجب أن يظهر في علبة الوارد. الرد من Chatwoot والتحقق منه يصل على WhatsApp.
الإعدادات
ومعظم الإعدادات لها أيضا علم
--chatwoot-* وCHATWOOT_URL وCHATWOOT_API_TOKEN وCHATWOOT_ACCOUNT_ID وCHATWOOT_INBOX_ID هي بيئية-فقط. انظر هيئة الإعداد.
على فرع GOWA main بعد v9.9.0، اضبط CHATWOOT_EVENTS=message لمواصلة نسخ الرسائل إلى Chatwoot مع تصفية عمليات تسليم webhooks العادية بشكل منفصل. يسمح المحدِّد message أيضًا بمرور التفاعلات وإيصالات الاستلام والتعديلات وعمليات الحذف عبر مرشّح Chatwoot. وتظل إعدادات القراءة والتعديل والحذف المنفصلة سارية.
اترك CHATWOOT_EVENTS فارغًا ليرث إعداد WHATSAPP_WEBHOOK_EVENTS. إذا كان المرشّح الفعلي فارغًا، فإنه يسمح بجميع الأحداث المدعومة. وإذا كان يستبعد message، يسجّل GOWA تحذيرًا عند بدء التشغيل ويتوقف عن نسخ رسائل WhatsApp إلى Chatwoot.
على هذه الإنشاءات، ترسل GOWA الرمز المميز لمستخدم Chatwoot في رأس api-access-token حتى يتمكن nginx من مروره بإعدادات الترويسة الافتراضية.
سر Webhook
يرفض سر الويب الفعال الفارغ التوصيل.CHATWOOT_WEBHOOK_ALLOW_UNSIGNED=true يسمح صراحة بالتسليم غير الموقع عندما يكون السر الفعلي فارغاً. ويجب على كل طلب، مع تكوين سري، أن يثبت ذلك بواحد من:
- توقيع Chatwoot (
X-Chatwoot-Signature+X-Chatwoot-Timestamp)، وهو الخيار الموصى به. استخدم سر webhook الخاص بقناة API نفسها. يتحقق GOWA من قيمة HMAC-SHA256 لـ<timestamp>.<raw body>ويرفض الطوابع الزمنية التي تقع خارج هامش التفاوت المُعدّ. X-Hub-Signature-256HMAC التابع للجسم.- السر في ترويسة
X-Chatwoot-Webhook-SecretأوX-Gowa-Chatwoot-Secret. ?secret=في موقع webhook URL، فقط لنسخ Chatwoot التي لا يمكن توقيع أو إضافة الرؤوس. ثم يظهر السر في سجلات الوصول.
401؛ ويسجّل GOWA السبب (signature does not match يعني أن السر غير صحيح، وtimestamp outside the tolerance window يعني وجود انحراف في الساعة).
ويستبدل webhook_secret في الجهاز السر العام لذلك الجهاز على كل من نقطتي النهاية المشتركة والجهازية. بدون أسرار الجهاز، ينطبق السر العام. تقوم GOWA بالتحقق من سر الجهاز الموجه قبل إرسال البيانات أو حذفها أو وضع علامة على القراءة أو كتابتها. تفضيل رابط رد الاتصال لكل جهاز عندما تستخدم عدة أجهزة نفس معرفات الحساب و علبة الوارد.
يُقرّ الطلب المتكرر الموقّع من Chatwoot، والذي سبق أن تلقّى 2xx، بالرمز 200 ويُتجاوز ضمن نافذة الطابع الزمني. تظل الطلبات الفاشلة قابلة لإعادة المحاولة. وقد يعيد طلب مطابق لا يزال قيد المعالجة الرمز 503 بعد انتظار يصل إلى 30 ثانية. تُحفظ ذاكرة منع إعادة الإرسال محليًا داخل العملية، وتُفقد عند إعادة التشغيل، ويبلغ حدّها 65,536 طلبًا مقبولًا. ولا تُشارك بين مثيلات GOWA. قد تؤدي عمليتا تسليم للرسالة نفسها من Chatwoot، لكل منهما توقيع مستقل، إلى إرسال الرسالة مرتين. لا توفّر قيم HMAC التي تغطي جسم الطلب فقط، ولا ترويسات السر، ولا الأسرار في معاملات الاستعلام، آلية منع تكرار التسليم هذه.
التوفير التلقائي
عند ضبطCHATWOOT_AUTO_CREATE=true وعدم تحديد CHATWOOT_INBOX_ID، يبحث GOWA عند بدء التشغيل عن صندوق وارد من نوع API باسم CHATWOOT_INBOX_NAME ويعيد استخدامه، أو ينشئ صندوقًا يستخدم CHATWOOT_WEBHOOK_URL كعنوان webhook الخاص به.
صندوق الوارد واحد لكل جهاز
تشكل متغيرات البيئة وجهة واحدة تشترك فيها جميع الأجهزة. لتوجيه كل جهاز إلى صندوق الوارد الخاص به، الحساب أو خادم Chatwoot الخاص به، قم بتخزين تكوينات لكل جهاز (طلبات المصادقة الأساسية):webhook_url (<base>/chatwoot/webhook/<device_id>)؛ قم بتعيينه كـ webhook. طرق أخرى: GET /chatwoot/configs, GET وDELETE /devices/{device_id}/chatwoot/config.
- يتم تخزين
api_tokenفي قاعدة بيانات GOWA، ويتم إخفاؤه في القراءات؛webhook_secretلا يتم إعادته أبدا. - يجب أن يستخدم
chatwoot_urlبروتوكول HTTP أو HTTPS دون بيانات اعتماد. في غيابCHATWOOT_ALLOWED_HOSTS، تُرفض العناوين الخاصة وعناوين الاسترجاع المحلي والعناوين المحلية للرابط وعناوين البيانات الوصفية. يُوثق بأي مضيف مُدرج صراحةً ومطابق فيCHATWOOT_ALLOWED_HOSTS، ويمكنه استهداف Chatwoot مستضاف ذاتيًا على شبكة خاصة. لا تُدرج في قائمة السماح هذه إلا المضيفين الذين تتحكم بهم. - تغيير
chatwoot_urlأوaccount_idأوinbox_idبعد المحادثات يتم ربط الإرجاع409؛ حذف وإعادة إنشاء config بدلا من ذلك. - يمكن إنشاء تكوين قبل أزواج الجهاز.
- يعمل الاستيراد المباشر لقاعدة البيانات فقط في وضع تكوين واحد (البيئة).
الردود والتنسيق
عندما يستخدم وكيل ردّ في Chatwooot، تقوم GOWA باقتباس رسالة WhatsApp الأصلية عندما يمكنها حلها في المتجر المحلي للجهاز المرسل وفي نفس المحادثة. ينطبق هذا على النص وكل مرفق، بما في ذلك الارتداد الصوتي إلى الملف. يبقى التسمية التوضيحية على المرفق الأول فقط. للحصول على رسالة واردة من WhatsApp ، تقوم GOWA بتحديد البادئةin_reply_to_external_id مع WAID:<id>. بالنسبة لرد وكيل سابق، فإن in_reply_to الرقمي يحل من خلال رابط رسالة دائم في نفس الجهاز، والمحادثة، والحساب، علبة البريد الوارد، والتكييف. رسالة مع مرفقات متعددة تستشهد بملفها الأول. إذا تعذر حل الهدف، يتم تسليم الرد بدون اقتباس.
تُربط ردود WhatsApp الواردة وتفاعلاته بالرسالة المشار إليها ضمن سلسلة محادثتها في Chatwoot. تُحوَّل روابط Markdown وتنسيقات التوكيد في ردود موظفي الدعم إلى نص مقروء في WhatsApp. وتُحفظ القوائم وفواصل الأسطر والشيفرة. وتُزال فواصل التوقيع الفارغة. يضيف CHATWOOT_SIGN_MSG اسم موظف الدعم في البداية بعد هذا التحويل.
يتم إرسال رسائل الوكيل العام الصادر المؤهلة فقط. لا يتم إرسال الملاحظات الخاصة والمحادثات المستثناة. تستخدم GOWA الجهاز المكون وهوية الحساب/علبة الوارد لتوجيه المكالمات المشتركة. المكالمات لكل جهاز توفر مسارا لا لبس فيه.
استطلاعات الرأي ووكيل يحذف
على فرع GOWAmain بعد v9.9.0، ينسخ Chatwoot إنشاء استطلاعات الرأي وتعديلاتها والخيارات المضافة إليها. لمعالجة الأصوات الفردية، اشترك في message ضمن webhooks الخاصة بـ WhatsApp واقرأ بيانات الاستطلاع المنظّمة.
على هذه الإنشاءات، اضبط CHATWOOT_REVOKE_ON_DELETE=true لمزامنة حذف من Chatwoot إلى WhatsApp فقط. يجب أن يتطابق الحذف مع الروابط الدائمة للرسائل الصادرة في إطار تكوين Chatwoot النشط. تقوم GOWA بإلغاء كل رسالة مرتبطة بـ WhatsApp، بما في ذلك المرفقات المرسلة بشكل منفصل. مع CHATWOOT_FORWARD_DELETES=true، حذف من WhatsApp لا تزال تظهر كملاحظات خاصة. استخدم CHATWOOT_MESSAGE_DELETE=true لحذف الرسائل المرتبطة في كلا الاتجاهين.
سجل الاستيراد
days_limit=3, include_media=true, و include_groups=true. المزامنة تقرأ وحدة تخزين المحادثة المحلية لـ GOWA، وتعمل في الخلفية. يمكن لكل جهاز تشغيل مزامنة واحدة في كل مرة.
على نظام GOWA main بعد v9.0، يمكن لمزامنة التاريخ أن تطلب من الهاتف إعادة تحميل الوسائط التي انتهت صلاحيتها. يجب أن يكون الهاتف على الإنترنت ولا يزال لديه الملف. إذا فشل الهاتف في الإجابة في غضون 30 ثانية، فإن المزامنة تخطي المزيد من طلبات إعادة تحميل لهذا التشغيل ومواصلة استيراد الرسائل. يتم استيراد الرسالة التي يبقى ملفها غير متوفر بدون المرفق.
مسار “ريست” لا يمكن تعيين علامات التوقيت الأصلية؛ الرسائل المستوردة تحصل على وقت الاستيراد. للChatwoot الذي يستضيف ذاتياً، يكتب CHATWOOT_IMPORT_DB_URI مباشرة إلى PostgreSQL Chatwot ويحافظها.
مع CHATWOOT_REOPEN_CONVERSATION=true على GOWA بعد main بعد v9.0، لا يؤدي مزامنة التاريخ إلا إلى إعادة فتح محادثة تم حلها عندما يكون لديها رسالة جديدة للاستيراد. سيعيد مزامنة REST فتح المحادثة قبل النشر وإعادة المحاولة في المحادثة في المزامنة التالية إذا فشلت إعادة الفتح. استيراد PostgreSQL المباشر يعيد فتحه في نفس المعاملة ككتابة الرسالة. مع إيقاف التشغيل، مزامنة REST تنشئ محادثة جديدة للرسائل الجديدة، في حين يستمر الاستيراد المباشر في استخدام المحادثة التي تم حلها.
التسليم وإعادة المحاولات
الرسائل الحية التي تصيب خطأ مؤقت في Chatwoot (خطأ في الشبكة، HTTP 429 أو 5xx) في قائمة الانتظار في التخزين المحلي ثم يعاد تجربتها في الخلفية مع وجود خلفية أسطحية متصاعدة. أخطاء 4xx الأخرى تم تسجيلها وإسقاطها.استكشاف الأخطاء
تشغيل مع
APP_DEBUG=true والبحث عن خطوط تسجيل بدءاً بـ Chatwoot: وChatwoot Webhook:. ويغطي دليل Chatwoot قواعد الاستيراد والتنسيق المباشرة لقاعدة البيانات بتعمق أكبر.