> ## 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.

# مرجع التكوين

> جميع متغيرات البيئة وخيارات سطر الأوامر في GOWA، مع قيمها الافتراضية.

تقرأ GOWA التكوين من ثلاثة أماكن:

* **خيارات سطر الأوامر** للأمر `whatsapp rest` (شغّل `./whatsapp rest --help` للاطلاع على القائمة الكاملة).
* **متغيرات البيئة**.
* **ملف `.env`** في مجلد العمل (`src/.env` عند التشغيل من المصدر؛ انسخ `src/.env.example`).

لا يملأ ملف `.env` إلا المتغيرات التي لم تُضبط بالفعل في البيئة.

> [!WARNING]
>
> في الشيفرة الحالية، تُطبَّق متغيرات البيئة (بما فيها `.env`) **بعد** تحليل خيارات سطر الأوامر، لذا تتجاوز قيمة المتغير المضبوط قيمة الخيار المقابل. وتُستثنى من ذلك إعدادات MCP OAuth والخيارات `--allow-unauthenticated` و`--trusted-origins` و`--chatwoot-webhook-allow-unsigned` و`--webhook-all-device-receipts`، إذ تكون الأولوية لخياراتها الصريحة. اضبط كل خيار في موضع واحد فقط. على سبيل المثال، تتجاوز `WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true` القيمة `--webhook-insecure-skip-verify=false`.

يقبل Booleans `true`/`false`. تستخدم فترات بناء الجملة (`30s`, `5m` , `3h`). قيم القائمة مفصولة بفواصل.

## الأوامر

| أمر | الوصف |
| - | - |
| `whatsapp rest` | يبدأ تشغيل REST API ولوحة التحكم وWebSocket ونقطة نهاية MCP. وهو مطلوب منذ v6؛ فتشغيل `whatsapp` وحده لا يبدأ الخادم. |
| `whatsapp version` | طباعة الإصدار والخروج. |
| `whatsapp --help` | قائمة الأوامر والأعلام. |

## خادم

| متغير | العلم | الافتراضي | الوصف |
| - | - | - | - |
| `APP_PORT` | `--port`, `-p` | `3000` | منفذ HTTP. |
| `APP_HOST` | `--host`, `-H` | `0.0.0.0` | رابط العنوان. |
| `APP_DEBUG` | `--debug`, `-d` | `false` | تسجيل فارغ. |
| `APP_OS` | `--os` | `GOWA` | اسم الجهاز يظهر في قائمة **الأجهزة المرتبطة** لـ WhatsApp. |
| `APP_BASIC_AUTH` | `--basic-auth`, `-b` | — | أكمل أزواج `user:pass` مفصولة بفواصل. مطلوب لمستمع غير تكرار ما لم يتم تعيين التجاوز الصريح غير المصدق عليه. |
| `APP_ALLOW_UNAUTHENTICATED` | `--allow-unauthenticated` | `false` | اسمح للمستمع الغير مستمع بدون مصادقة أساسية. استخدم فقط خلف وكيل مصادقة مع وصول مباشر مقيد. |
| `APP_TRUSTED_ORIGINS` | `--trusted-origins` | — | تحديد أصول المتصفح الإضافية المسموح لها بتغيير الحالة وفتح WebSockets. مضيف الطلب ومصدري CORS المحددين أيضا موثوق بهم. |
| `APP_BASE_PATH` | `--base-path` | — | خدمة تحت مسار فرعي، على سبيل المثال `/gowa`. `/health` تبقى في الجذر. |
| `APP_TRUSTED_PROXIES` | `--trusted-proxies` | — | نطاقات عناوين IP للوكلاء الذين تُوثَق ترويسات إعادة التوجيه الواردة منهم، مثل `10.0.0.0/8`. |
| `APP_CORS_ALLOWED_ORIGINS` | `--cors-allowed-origins` | \* (أي منشأ) | منشأ CORS. مصادر محددة تجتاز أيضًا التحقق من منشأ المتصفح. بطاقة برية لا تأذن بإجراء تحولات أو WebSockets. |

## لوحة التحكم

| متغير | العلم | الافتراضي | الوصف |
| - | - | - | - |
| `APP_UI_ENABLED` | `--ui-enabled` | `true` | خدمة لوحة معلومات جوا - وي في `/`. |
| `APP_UI_AUTO_UPDATE` | `--ui-auto-update` | `true` | ينزّل أحدث إصدار من لوحة التحكم عند بدء التشغيل وبشكل دوري. عطّله على المضيفات المعزولة عن الشبكة مع تجهيز ذاكرة التخزين المؤقت `storages/ui` مسبقًا. |
| `APP_UI_REPO` | `--ui-repo` | `aldinokemal/gowa-ui` | مستودع GitHub للتحميل منه. |
| `APP_UI_ASSET_NAME` | `--ui-asset-name` | `gowa-ui.html` | تحرير الأصل للتنزيل. |
| `APP_UI_UPDATE_INTERVAL` | `--ui-update-interval` | `3h` | الفاصل بين التحديثات. |
| `APP_UI_GITHUB_TOKEN` | — | — | رمز GitHub لارتفاع حد معدل API. |
| `APP_UI_ASSET_SHA256` | `--ui-asset-sha256` | — | فقط قم بتقديم لوحة تحكم مع SHA-256. |

## MCP

| متغير | العلم | الافتراضي | الوصف |
| - | - | - | - |
| `MCP_ENABLED` | `--mcp-enabled` | `true` | خدمة نقطة النهاية MCP في `/mcp`. |
| `MCP_OAUTH_ENABLED` | `--mcp-oauth-enabled` | `false` | تمكين OAuth 2.1 لـ `/mcp`. يتطلب `APP_BASIC_AUTH`. |
| `MCP_OAUTH_ISSUER_URL` | `--mcp-oauth-issuer-url` | — | عنوان URL لمصدر HTTPS العام. مطلوب مع OAuth. |
| `MCP_OAUTH_RESOURCE_URL` | `--mcp-oauth-resource-url` | المصدر + المسار الأساسي + `/mcp` | MCP URL. |
| `MCP_OAUTH_DB_URI` | `--mcp-oauth-db-uri` | `file:storages/oauth.db` | متجر SQLite لعملاء OAuth و تجزئة الرموز. |

انظر [MCP server](https://gowa-docs.mintlify.site/ar/integrations/mcp.md).

## التخزين

| متغير | العلم | الافتراضي | الوصف |
| - | - | - | - |
| `DB_URI` | `--db-uri` | `file:storages/whatsapp.db` | Session store: SQLite (`file:...`) or PostgreSQL (`postgres://...`). |
| `DB_KEYS_URI` | `--db-keys-uri` | نفس `DB_URI` | مخزن منفصل اختياري لذاكرة التخزين المؤقت لمفتاح التشفير. تجنب المتاجر في الذاكرة قيد الإنتاج. |
| `CHAT_STORAGE_MAX_OPEN_CONNS` | — | `5` | الحد الأقصى لاتصالات SQLite لتخزين الدردشة. قم برفع وقت الإرسال تحت تحميل ثقيل. |

وحدة تخزين الدردشة (المحادثات، الرسائل، الجداول) تعيش دائما في `storages/chatstorage.db` وغير قابلة للتكوين.

يتم إنشاء قواعد بيانات SQLite للجلسات، وتخزين الدردشة، و OAuth بأذونات `0600`. تنشئ دلائل GOWA لهذه الملفات باستخدام `0700`. الدلائل الموجودة تحتفظ بالأذونات الخاصة بها. يتم تسجيل تغييرات الأذونات التي لا يدعمها نظام الملفات كتحذيرات.

بالنسبة إلى مخازن الجلسات والمفاتيح في PostgreSQL، تكون القيمة الافتراضية لـ `sslmode` عند إغفاله أو تركه فارغًا هي `verify-full` لوجهات الاتصال البعيدة. أما `localhost` وعناوين IP للاسترجاع المحلي ومقابس Unix، فقيمتها الافتراضية `disable`. تظل إعدادات URI الصريحة و`PGSSLMODE` وتهيئة الخدمة سارية. ويمكن لإدخال `PGSERVICE` تجاوز المضيف ووضع TLS المحددين في URI. عند استخدام PostgreSQL مُدار، حدّد `sslmode=verify-full` وتهيئة جهة إصدار الشهادات CA المطلوبة صراحةً.

## سلوك WhatsApp

| متغير | العلم | الافتراضي | الوصف |
| - | - | - | - |
| `WHATSAPP_AUTO_REPLY` | `--autoreply` | — | تم إرسال رد ثابت إلى كل رسالة واردة. |
| `WHATSAPP_AUTO_MARK_READ` | `--auto-mark-read` | `false` | ضع علامة على الرسائل الواردة مقروءة. |
| `WHATSAPP_AUTO_DOWNLOAD_MEDIA` | `--auto-download-media` | `true` | يحفظ الوسائط الواردة في `statics/media`. |
| `WHATSAPP_IGNORE_STATUS_MEDIA` | `--ignore-status-media` | `false` | تخطي تنزيل وسائط الحالة. |
| `WHATSAPP_AUTO_REJECT_CALL` | `--auto-reject-call` | `false` | رفض المكالمات الواردة. |
| `WHATSAPP_ACCOUNT_VALIDATION` | `--account-validation` | `true` | التحقق من المستلمين على WhatsApp قبل الإرسال. |
| `WHATSAPP_PRESENCE_ON_CONNECT` | `--presence-on-connect` | `unavailable` | حالة التواجد المُرسلة عند الاتصال: `available` أو `unavailable` أو `none`. |
| `WHATSAPP_PRESENCE_PULSE_ENABLED` | `--presence-pulse-enabled` | `true` | انتقل بشكل دوري عبر الإنترنت بإيجاز، ثم دون اتصال مرة أخرى. |
| `WHATSAPP_PRESENCE_PULSE_INTERVAL` | `--presence-pulse-interval` | `24h` | الوقت بين النبضة. |
| `WHATSAPP_PRESENCE_PULSE_DURATION` | `--presence-pulse-duration` | `5m` | كم من الوقت يبقى كل نبض على الإنترنت. |
| `WHATSAPP_PROXY` | `--whatsapp-proxy` | — | الوكيل لاتصال WhatsApp : `socks5://`، `http://` أو `https://`. `HTTP_PROXY` لا ينطبق عليه. |

## الوب

| متغير | العلم | الافتراضي | الوصف |
| - | - | - | - |
| `WHATSAPP_WEBHOOK` | `--webhook`, `-w` | — | Webhook URL، مفصولة بفاصلة. |
| `WHATSAPP_WEBHOOK_SECRET` | `--webhook-secret` | عشوائي لكل عملية | مفتاح HMAC للترويسة `X-Hub-Signature-256`. اضبط مفتاحًا ثابتًا تنشئه بنفسك. تؤدي القيمة الفارغة أو `secret` أو `super-secret-key` أو `your-private-key` إلى إنشاء مفتاح مؤقت بدلًا منها. |
| `WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY` | `--webhook-insecure-skip-verify` | `false` | تخطي التحقق TLS (التطوير فقط). |
| `WHATSAPP_WEBHOOK_EVENTS` | `--webhook-events` | \* (جميع) | قائمة السماح للحدث، مثل `message,message.ack`. |
| `WHATSAPP_WEBHOOK_IGNORE_JIDS` | `--webhook-ignore-jids` | — | لم يتم إرسال بطاقات JIDs أو Wildcards (`@g.us`، و `@s.whatsapp.net`، و `@lid`). |
| `WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL` | `--webhook-device-merge-global` | `false` | إرسال أحداث الجهاز إلى عناوين URL العالمية وكذلك الويب الخاص به. |
| `WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS` | `--webhook-all-device-receipts` | `false` | إعادة توجيه الإيصالات من الأجهزة المرتبطة بجهات الاتصال وكذلك من جهازها الرئيسي. قد تنتج تعهدات متعددة لرسالة واحدة. |

انظر [Webhooks](https://gowa-docs.mintlify.site/ar/concepts/webhooks.md).

## Chatwoot

| متغير | العلم | الافتراضي |
| - | - | - |
| `CHATWOOT_ENABLED` | `--chatwoot-enabled` | `false` |
| `CHATWOOT_URL` | — | — |
| `CHATWOOT_API_TOKEN` | — | — |
| `CHATWOOT_ACCOUNT_ID` | — | — |
| `CHATWOOT_INBOX_ID` | — | — |
| `CHATWOOT_DEVICE_ID` | `--chatwoot-device-id` | — |
| `CHATWOOT_ALLOWED_HOSTS` | `--chatwoot-allowed-hosts` | — |
| `CHATWOOT_IMPORT_MESSAGES` | `--chatwoot-import-messages` | `false` |
| `CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES` | `--chatwoot-days-limit-import-messages` | `3` |
| `CHATWOOT_IMPORT_DB_URI` | `--chatwoot-import-db-uri` | — |
| `CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE` | `--chatwoot-import-placeholder-media-message` | `true` |
| `CHATWOOT_IMPORT_MEDIA_WITH_REST` | `--chatwoot-import-media-with-rest` | `false` |
| `CHATWOOT_AUTO_CREATE` | `--chatwoot-auto-create` | `false` |
| `CHATWOOT_INBOX_NAME` | `--chatwoot-inbox-name` | `WhatsApp` |
| `CHATWOOT_WEBHOOK_URL` | `--chatwoot-webhook-url` | — |
| `CHATWOOT_WEBHOOK_SECRET` | `--chatwoot-webhook-secret` | — |
| `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED` | `--chatwoot-webhook-allow-unsigned` | `false` |
| `CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE` | `--chatwoot-webhook-signature-tolerance` | `5m` |
| `CHATWOOT_REOPEN_CONVERSATION` | `--chatwoot-reopen-conversation` | `true` |
| `CHATWOOT_CONVERSATION_PENDING` | `--chatwoot-conversation-pending` | `false` |
| `CHATWOOT_IGNORE_JIDS` | `--chatwoot-ignore-jids` | — |
| `CHATWOOT_SIGN_MSG` | `--chatwoot-sign-msg` | `false` |
| `CHATWOOT_SIGN_DELIMITER` | `--chatwoot-sign-delimiter` | `\n\n` |
| `CHATWOOT_FORWARD_EDITS` | `--chatwoot-forward-edits` | `true` |
| `CHATWOOT_FORWARD_DELETES` | `--chatwoot-forward-deletes` | `true` |
| `CHATWOOT_EVENTS` | `--chatwoot-events` | متابعة `WHATSAPP_WEBHOOK_EVENTS` عندما تكون فارغة |
| `CHATWOOT_MESSAGE_READ` | `--chatwoot-message-read` | `false` |
| `CHATWOOT_MESSAGE_DELETE` | `--chatwoot-message-delete` | `false` |
| `CHATWOOT_REVOKE_ON_DELETE` | `--chatwoot-revoke-on-delete` | `false` |

خيار تصفية الحدث وإلغاء اتجاه واحد متاح على نظام GOWA `main` بعد v9.9.0. انظر [Chatwoot Integration](https://gowa-docs.mintlify.site/ar/integrations/chatwoot.md#%D8%A7%D9%84%D8%A5%D8%B9%D8%AF%D8%A7%D8%AF%D8%A7%D8%AA) للاطلاع على السلوك والأمثلة.

## حدود ثابتة

يتم تجميع هذه التجميع ولا يمكن تغييرها عن طريق التكوين:

| الحد | القيمة |
| - | - |
| تحميل الصورة | 20 ميغابايت |
| تحميل المستند | 50 ميغابايت |
| تحميل الفيديو وجهاز طلب HTTP | 100 ميغابايت |
| تحميل الوسائط الواردة | 500 ميغابايت |
| مهلة الطلب | 45 ثانية (`504 GATEWAY_TIMEOUT`) |
| توصيل Webhook | 10 ث في كل محاولة، 5 محاولات |

## تنزيلات رابط الوسائط

إرسال الطلبات التي تجلب الوسائط أو المستندات أو معاينات الارتباط تقبل HTTP و HTTPS URLs. يرفض جلب عنوان URL العام حلقة الظهور، الخاص، وصلة - محلية، وبيانات تعريفية، ومتعدد البث، والوجهات المحجوزة. يتم تحديد إعادة توجيه وعنوان الاتصال الفعلي. هذه التنزيلات تتصل مباشرة ولا تستخدم `HTTP_PROXY` أو `HTTPS_PROXY`.

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

## غير مستخدم

قائمتا `src/.env.example` `WHATSAPP_WEBHOOK_INCLUDE_OUTGOING` و`WHATSAPP_CHAT_STORAGE`، ولكن الرمز الحالي لا يقرأ أيضا.

## مثال

```bash .env theme={null}
APP_PORT=3000
APP_OS=MyCompany
APP_BASIC_AUTH=admin:a-long-random-password
APP_TRUSTED_PROXIES=10.0.0.0/8
DB_URI=postgres://gowa:replace-with-password@db.example.com:5432/gowa?sslmode=verify-full
WHATSAPP_WEBHOOK=https://example.com/wa-hook
WHATSAPP_WEBHOOK_SECRET=another-long-random-secret
WHATSAPP_WEBHOOK_EVENTS=message,message.ack
WHATSAPP_AUTO_MARK_READ=false
```

الأعلام المتساوية:

```bash theme={null}
./whatsapp rest --port=3000 --os=MyCompany \
  --basic-auth=admin:a-long-random-password \
  --webhook=https://example.com/wa-hook \
  --webhook-secret=another-long-random-secret \
  --webhook-events=message,message.ack
```


## Related topics

- [البداية السريعة](https://gowa-docs.mintlify.site/ar/quickstart.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)
- [مرجع API](https://gowa-docs.mintlify.site/ar/api-reference/introduction.md)
- [احصل على تكوين دردشة الجهاز](https://gowa-docs.mintlify.site/ar/api-reference/chatwoot/احصل-على-تكوين-دردشة-الجهاز.md)


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