> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# تكامل Chatwoot

> مرآة محادثات WhatsApp في صندوق الوارد لChatwoot وترك الوكلاء يستجيبون من Chatwoot.

مع تمكين Chatwooot، توجه GOWA رسائل WhatsApp (واردة ، والمصدرين المرسلين من الهاتف) إلى صندوق الوارد \*\*قناة API في Chatwoot، وإرسال ردود الوكيل من Chatwoot إلى WhatsApp. النصوص والصور والصور والصوت والفيديو والوثائق والملصقات والمواقع وجهات الاتصال مدعومة؛ وتظهر المحادثة الجماعية كمحادثة واحدة لكل مجموعة، مع تحديد اسم المرسل مسبقا.

```mermaid theme={null}
flowchart LR
  WA[WhatsApp] -- messages --> G[GOWA]
  G -- Chatwoot REST API --> CW[Chatwoot inbox]
  CW -- webhook /chatwoot/webhook --> G
  G -- agent reply --> WA
```

## المتطلبات

* يمكن الوصول إلى GOWA من Chatwoot عبر عنوان URL عام (لرد وكيل على webhooks).
* حساب Chatwoot مع وصول المشرف و رمز وصول API للمستخدم.
* جهاز واحد على الأقل مسجل الدخول في WhatsApp.

## إعداد

**1. إنشاء صندوق الوارد لقناة API**

في Chatwoot، انتقل إلى **إعدادات → علب الوارد → إضافة علبة الوارد → API**. لاحظ **معرف علبة الوارد الرقمية** من عنوان البريد الوارد، و **سر الويبهوك** مسلسلات الدردشة للقناة. وبدلا من ذلك، دعوا GOWA تنشئ صندوق الوارد (انظر [Auto-provisioning](#%D8%A7%D9%84%D8%AA%D9%88%D9%81%D9%8A%D8%B1-%D8%A7%D9%84%D8%AA%D9%84%D9%82%D8%A7%D8%A6%D9%8A)).

**2. جمع المعرفات و الرمز المميز**

**معرف الحساب** هو الرقم في `/app/accounts/<id>/...`. انسخ **رمز الوصول** للمستخدم من **إعدادات الملف الشخصي**. يجب أن يكون كل من المعرفين المعرفين الرقميين، وليس القناة `identifier` أو `hmac_token`.

**3. تكوين GOWA**

```bash .env theme={null}
CHATWOOT_ENABLED=true
CHATWOOT_URL=https://chatwoot.example.com
CHATWOOT_API_TOKEN=your_user_access_token
CHATWOOT_ACCOUNT_ID=1
CHATWOOT_INBOX_ID=3
CHATWOOT_DEVICE_ID=my-device              # required with more than one device
CHATWOOT_WEBHOOK_SECRET=secret-shown-by-chatwoot
CHATWOOT_WEBHOOK_URL=https://gowa.example.com/chatwoot/webhook
```

إعادة تشغيل GOWA: طرق الدردشة مسجلة عند بدء التشغيل.

**4. نقطة الدردشة في GOWA**

عيّن عنوان URL لقناة API webhook إلى `https://gowa.example.com/chatwoot/webhook` (مع `APP_BASE_PATH`، تضمين المسار الأساسي). هذا المسار عام: فهو محمي من قبل سر ويبهوك وليس من قبل المصادقة الأساسية.

**5. اختبار**

رسالة رقم WhatsApp من هاتف آخر؛ يجب أن يظهر في علبة الوارد. الرد من Chatwoot والتحقق منه يصل على WhatsApp.

## الإعدادات

| متغير | الافتراضي | الوصف |
| - | - | - |
| `CHATWOOT_ENABLED` | `false` | مفتاح التبديل الرئيسي. |
| `CHATWOOT_URL` | — | رابط قاعدة الدردشة، لا يوجد خط فاصل. |
| `CHATWOOT_API_TOKEN` | — | رمز وصول API للمستخدم. |
| `CHATWOOT_ACCOUNT_ID` | — | رقم معرف الحساب. |
| `CHATWOOT_INBOX_ID` | — | رقم معرف البريد الوارد. اختياري مع `CHATWOOT_AUTO_CREATE=true`؛ عندما يتم تعيينه يفوز دائما. |
| `CHATWOOT_DEVICE_ID` | — | الجهاز (معرف الفتحة أو JID) الذي يرسل إجابات الوكيل. مطلوب عند وجود أكثر من جهاز. |
| `CHATWOOT_WEBHOOK_URL` | — | رابط ويب GOWA العام؛ يستخدم عند إنشاء صندوق الوارد تلقائيا. |
| `CHATWOOT_WEBHOOK_SECRET` | — | التحقق من وصول Chatwoot. يرفض سر فارغ فعلي المكالمات ما لم يتم تمكين التجاوز الصريح غير الموقع. |
| `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED` | `false` | قبول الطلبات بدون سرية فعالة. تقييد هذا إلى شبكة موثوقة. |
| `CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE` | `5m` | الحد الأقصى للسن / انحراف الساعة من `X-Chatwoot-Timestamp`. |
| `CHATWOOT_AUTO_CREATE` | `false` | إعادة استخدام أو إنشاء صندوق إدخال API يسمى `CHATWOOT_INBOX_NAME` عند بدء التشغيل. |
| `CHATWOOT_INBOX_NAME` | `WhatsApp` | اسم صندوق الوارد للتوفير التلقائي. |
| `CHATWOOT_IMPORT_MESSAGES` | `false` | استيراد المحفوظات تلقائياً عند توصيل الجهاز. |
| `CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES` | `3` | أيام من التاريخ للاستيراد. |
| `CHATWOOT_IMPORT_DB_URI` | — | Chatwoot PostgreSQL URI لاستيراد التاريخ المباشر (يحتفظ بالعلامات الزمنية الأصلية). |
| `CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE` | `true` | الاستيراد المباشر: أدخل `[image]`-modle posites للوسائط التي لا يمكن تحميلها. |
| `CHATWOOT_IMPORT_MEDIA_WITH_REST` | `false` | الاستيراد المباشر: تحميل الوسائط من خلال REST API حتى يتم إنشاء المرفقات. |
| `CHATWOOT_REOPEN_CONVERSATION` | `true` | إعادة فتح محادثة تم حلها عند كتابة جهة الاتصال مرة أخرى. |
| `CHATWOOT_CONVERSATION_PENDING` | `false` | أنشئ المحادثات الجديدة بالحالة `pending` بدلًا من `open`. |
| `CHATWOOT_IGNORE_JIDS` | — | لم تتر أبداً أي بطاقات هجومية أو بطاقات برية مفصولة بفواصل (`@g.us`، `@s.whatsapp.net`، `@lid`). |
| `CHATWOOT_SIGN_MSG` | `false` | رد الوكيل البادئة مع اسم الوكيل. |
| `CHATWOOT_SIGN_DELIMITER` | `\n\n` | الفصل بين التوقيع والرسالة. |
| `CHATWOOT_FORWARD_EDITS` | `true` | مرآة تعديلات واتساب كملاحظات خاصة. |
| `CHATWOOT_FORWARD_DELETES` | `true` | مرآة حذف للجميع كملاحظات خاصة. |
| `CHATWOOT_EVENTS` | يتبع `WHATSAPP_WEBHOOK_EVENTS` | أحداث مفصولة بفاصلة للانتقال إلى Chatwoot. |
| `CHATWOOT_MESSAGE_READ` | `false` | مزامنة حالة القراءة في كلا الاتجاهين. |
| `CHATWOOT_MESSAGE_DELETE` | `false` | حذف الرسالة المرتبطة على الجانب الآخر. |
| `CHATWOOT_REVOKE_ON_DELETE` | `false` | إلغاء الرسائل الصادرة عن WhatsApp عندما يقوم وكيل بحذف رسالة Chatwoot الخاصة به. |
| `CHATWOOT_ALLOWED_HOSTS` | — | قائمة المضيفين المسموح لقيمة `chatwoot_url` الخاصة بكل جهاز باستهدافهم. |

ومعظم الإعدادات لها أيضا علم `--chatwoot-*` و`CHATWOOT_URL` و`CHATWOOT_API_TOKEN` و`CHATWOOT_ACCOUNT_ID` و`CHATWOOT_INBOX_ID` هي بيئية-فقط. انظر [هيئة الإعداد](https://gowa-docs.mintlify.site/ar/configuration.md).

على فرع 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` يسمح صراحة بالتسليم غير الموقع عندما يكون السر الفعلي فارغاً. ويجب على كل طلب، مع تكوين سري، أن يثبت ذلك بواحد من:

1. **توقيع Chatwoot** (`X-Chatwoot-Signature` + `X-Chatwoot-Timestamp`)، وهو الخيار الموصى به. استخدم سر webhook الخاص بقناة API نفسها. يتحقق GOWA من قيمة HMAC-SHA256 لـ `<timestamp>.<raw body>` ويرفض الطوابع الزمنية التي تقع خارج هامش التفاوت المُعدّ.
2. `X-Hub-Signature-256` HMAC التابع للجسم.
3. السر في ترويسة `X-Chatwoot-Webhook-Secret` أو `X-Gowa-Chatwoot-Secret`.
4. `?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 الخاص به، قم بتخزين تكوينات لكل جهاز (طلبات المصادقة الأساسية):

```bash theme={null}
curl -u admin:changeme -X PUT http://localhost:3000/devices/sales/chatwoot/config \
  -H "Content-Type: application/json" \
  -d '{
    "chatwoot_url": "https://chatwoot.example.com",
    "account_id": 1,
    "inbox_id": 7,
    "api_token": "token-for-this-inbox",
    "webhook_secret": "secret-of-this-api-channel",
    "enabled": true
  }'
```

يتضمن الرد `webhook_url` (`<base>/chatwoot/webhook/<device_id>`)؛ قم بتعيينه كـ webhook. طرق أخرى: `GET /chatwoot/configs`, `GET` و`DELETE /devices/{device_id}/chatwoot/config`.

> [!WARNING]
>
> بمجرد وجود اعدادات **أي** لكل جهاز، لم يعد الوجهة `CHATWOOT_*` تستخدم كأسطورة. الأجهزة بدون اعدادات ليست مرآة.

* يتم تخزين `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 الجهاز المكون وهوية الحساب/علبة الوارد لتوجيه المكالمات المشتركة. المكالمات لكل جهاز توفر مسارا لا لبس فيه.

### استطلاعات الرأي ووكيل يحذف

على فرع GOWA `main` بعد v9.9.0، ينسخ Chatwoot إنشاء استطلاعات الرأي وتعديلاتها والخيارات المضافة إليها. لمعالجة الأصوات الفردية، اشترك في `message` ضمن [webhooks الخاصة بـ WhatsApp](https://gowa-docs.mintlify.site/ar/concepts/webhooks.md#%D8%A7%D9%84%D8%A3%D9%84%D8%A8%D9%88%D9%85%D8%A7%D8%AA-%D9%88%D8%A7%D9%84%D8%B1%D8%B3%D8%A7%D8%A6%D9%84-%D8%A7%D9%84%D9%85%D9%86%D8%B8%D9%85%D8%A9) واقرأ بيانات الاستطلاع المنظّمة.

على هذه الإنشاءات، اضبط `CHATWOOT_REVOKE_ON_DELETE=true` لمزامنة حذف من Chatwoot إلى WhatsApp فقط. يجب أن يتطابق الحذف مع الروابط الدائمة للرسائل الصادرة في إطار تكوين Chatwoot النشط. تقوم GOWA بإلغاء كل رسالة مرتبطة بـ WhatsApp، بما في ذلك المرفقات المرسلة بشكل منفصل. مع `CHATWOOT_FORWARD_DELETES=true`، حذف من WhatsApp لا تزال تظهر كملاحظات خاصة. استخدم `CHATWOOT_MESSAGE_DELETE=true` لحذف الرسائل المرتبطة في كلا الاتجاهين.

## سجل الاستيراد

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/chatwoot/sync \
  -H "Content-Type: application/json" \
  -d '{"device_id": "my-device", "days_limit": 7, "include_media": true, "include_groups": true}'

curl -u admin:changeme "http://localhost:3000/chatwoot/sync/status?device_id=my-device"
```

الافتراضي هو `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 الأخرى تم تسجيلها وإسقاطها.

## استكشاف الأخطاء

| الأعراض | تحقق |
| - | - |
| لم يتم تسليم ردود الوكيل | `CHATWOOT_DEVICE_ID` والجهاز مسجل الدخول؛ عنوان webhook URL صحيح وعام؛ `DEVICE_NOT_AVAILABLE` في السجلات يعني عدم وجود جهاز قابل للاستخدام. |
| `401` على `/chatwoot/webhook` | عدم تطابق سري أو انحراف الساعة (انظر أعلاه). |
| رسائل WhatsApp مفقودة من Chatwoot | تحقق من `CHATWOOT_ENABLED`، ورمز المستخدم، ومعرّفي الحساب وصندوق الوارد، والاتصال بـ `CHATWOOT_URL`. في الإصدارات الأحدث، تحقق من أن مرشّح الأحداث الفعلي يتضمن `message`. |
| `CHATWOOT_NOT_CONFIGURED` | عنوان URL، الرمز المميز، معرف الحساب أو معرف علبة الوارد مفقود. |

تشغيل مع `APP_DEBUG=true` والبحث عن خطوط تسجيل بدءاً بـ `Chatwoot:` و`Chatwoot Webhook:`. ويغطي [دليل Chatwoot](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/chatwoot.md) قواعد الاستيراد والتنسيق المباشرة لقاعدة البيانات بتعمق أكبر.


## Related topics

- [الحصول على بيانات تعريف الخادم](https://gowa-docs.mintlify.site/ar/api-reference/app/الحصول-على-بيانات-تعريف-الخادم.md)
- [نقطة نهاية Chatwoot](https://gowa-docs.mintlify.site/ar/api-reference/chatwoot/نقطة-نهاية-chatwoot.md)
- [نقطة نهاية Chatwoot للجهاز](https://gowa-docs.mintlify.site/ar/api-reference/chatwoot/نقطة-نهاية-chatwoot-للجهاز.md)
- [مزامنة سجل الرسائل إلى Chatwoot](https://gowa-docs.mintlify.site/ar/api-reference/chatwoot/مزامنة-سجل-الرسائل-إلى-chatwoot.md)
- [قائمة تكوينات Chatwoot لكل جهاز](https://gowa-docs.mintlify.site/ar/api-reference/chatwoot/قائمة-تكوينات-chatwoot-لكل-جهاز.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.