‏API داخل المواقع الخاصة بمنصة واتساب للأعمال‏

إعداد الإنتاج: المثيل الفردي

يوضح لك هذا المستند كيفية إعداد مثيل فردي لعميل API الخاصة بواتساب للأعمال في مرحلة الإنتاج.

إذا لم تقم بالفعل بذلك، فيوصى بإعداد مثيل فردي لعميل API الخاصة بواتساب للأعمال على جهاز المطوّر باتباع إرشادات إعداد المطوّر: المثيل الفردي لاختبار الإعداد قبل اتباع هذا المستند لإعداد عميل API الخاصة بواتساب للأعمال في مرحلة الإنتاج.

لإكمال الإعداد الأولي، تحقق من المتطلبات واتبع هذه الخطوات:

  1. إنشاء دليل biz للبرامج النصية للإعداد
  2. الحصول على ملفات تكوين عميل API الخاصة بواتساب للأعمال
  3. إعداد متغير البيئة WA_API_VERSION
  4. إعداد متغيرات بيئة قاعدة البيانات
  5. إعداد وحدة تخزين الوسائط المحلية
  6. بدء عميل API الخاصة بواتساب للأعمال
  7. التحقق من تشغيل الحاويات
  8. إجراء عملية التحقق من سلامة الأداء
  9. تسجيل عميل API الخاصة بواتساب للأعمال
  10. إجراء عملية ثانية للتحقق من سلامة الأداء

بمجرد إكمال إعداد المثيل، يمكنك اختيار ترقيته. لإلغاء تثبيت العميل، اتبع هذه الخطوات.

قبل البدء

إذا قمت بالفعل بتشغيل إعداد المطوّر وكنت تريد استخدام رقم الهاتف في الإنتاج، فيرجى الرجوع إلى دليل الترحيل قبل متابعة بقية محتوى هذا المستند.

يعتمد المحتوى في هذا المستند على افتراض التثبيت الحديث باستخدام رقم هاتف جديد.

ستحتاج إلى ما يلي:

يلزم توفير الإصدار MySQL 5.7xx أو PostgreSQL 13.x/12.x/11.x.

يجب ألا تتضمن كلمة السر الخاصة بقاعدة البيانات الحروف التالية: ?{}&~!()^=

ربما سيتسبب عدم الامتثال بذلك في فشل الإعداد.

توجد أيضًا مشكلة في التوافق مع MySQL 8. يُرجى عدم استخدام الإصدار الأحدث الآن، حيث نعمل على إصلاح هذه المشكلة.

Install Docker Desktop

To install Docker Desktop on your developer machine:

  1. Navigate to the Docker website.
  2. If you do not have an existing Docker account, create one by clicking on Sign Up.
  3. After you have created your account, you will be directed to the Docker download page.
  4. Download Docker Desktop based on your OS (This should be automatically detected and presented as the default option).

The remaining steps are based on macOS and should be very similar for Linux or Windows 10.

To install Docker using macOS:

  1. Install the package (docker.dmg for macOS).
  2. After extraction, Finder will pop-up and you will be presented with a dialog that instructs you to drag the Docker icon to Applications. Drag Docker icon to the Application folder in Finder.
  3. In Applications launch Docker and then click the Open button.
  4. You may be prompted to enter your password Docker needs priviledged/administrator access.
  5. Docker will present you with a tutorial, you can click Start to launch a tutorial or you can click Skip Tutorial to start using Docker.

Verify Docker Compose is installed

Docker Compose is a plugin that is bundled with Docker Desktop and should have installed automatically. For more information about using or Docker Compose, see Overview of Docker Compose. If for some reason Docker Compose was not installed, you can install it by following the instructions located at Install Docker Compose.

الإعداد الأولي لعميل API الخاصة بواتساب للأعمال

الخطوة الأولى: إنشاء دليل biz للبرامج النصية للإعداد

قم بتشغيل الرمز التالي في موقعك المفضل لعميل API الخاصة بواتساب للأعمال:

mkdir ~/biz; cd ~/biz;

الخطوة الثانية: الحصول على ملفات تكوين عميل API الخاصة بواتساب للأعمال

انسخ ملفي التكوين prod-docker-compose.yml وdb.env من دليل التثبيت في مستودع WhatsApp-Business-API-Setup-Scripts GitHub إلى دليل ~/biz الذي أنشأته في الخطوة الأولى.

الخطوة الثالثة: تعيين متغير البيئة WA_API_VERSION

يجب تعيين المتغير البيئي WA_API_VERSION على الإصدار الحالي باستخدام:

export WA_API_VERSION=current-whatsapp-version

الخطوة الرابعة: إعداد متغيرات بيئة قاعدة البيانات

يمكنك تغيير متغيرات بيئة قاعدة البيانات في الملف db.env ضمن الدليل ~/biz لعرض تكوين MySQL/PostgreSQL.

WA_DB_ENGINE=MYSQL | PGSQL
WA_DB_HOSTNAME=your-database-server
WA_DB_PORT=your-database-server-port
WA_DB_USERNAME=your-database-username
WA_DB_PASSWORD=your-database-password

الخطوة الخامسة: إعداد وحدة تخزين الوسائط المحلية

يتم استخدام وحدة تخزين الوسائط المحلية (whatsappMedia:/usr/local/wamedia بشكل افتراضي) في الملف prod-docker-compose.yml لتخزين ملفات الوسائط. يتم افتراضيًا تثبيت وحدة التخزين إلى الدليل في جهاز Docker. بدلاً من ذلك، يمكنك اختيار تثبيت وحدة تخزين الوسائط في دليل المضيف. لتغيير نقطة التثبيت في وحدة تخزين الوسائط، يمكنك تعديل تعريف وحدة التخزين داخل القسم services من whatsappMedia إلى مسار دليل المضيف الذي تستخدمه.

services:
  wacore:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ...          
  waweb:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ...

الخطوة السادسة: بدء تشغيل عميل API الخاصة بواتساب للأعمال

لبدء تشغيل عميل API الخاصة بواتساب للأعمال من خلال حاوية Webapp واحدة وحاوية Coreapp واحدة، قم بتشغيل:

docker-compose -f prod-docker-compose.yml up -d

يجب أن يبدو الإخراج الناتج كما يلي:

Creating biz_wacore_1 ... done
Creating biz_waweb_1  ... done

الخطوة السابعة: التحقق من تشغيل الحاويات

يمكنك التحقق من أن كل الحاويات متوفرة بالحالة UP عن طريق تشغيل:

docker-compose -f prod-docker-compose.yml  ps

يجب أن يبدو الإخراج الناتج كما يلي:

     Name                    Command               State                   Ports
-------------------------------------------------------------------------------------------------
biz_wacore_1   /opt/whatsapp/bin/wait_on_ ...   Up      6250/tcp, 6251/tcp, 6252/tcp, 6253/tcp
biz_waweb_1    /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:9090->443/tcp

سيتم افتراضيًا تشغيل الحاوية Webapp على المنفذ 9090.

الخطوة الثامنة: إجراء التحقق من سلامة الأداء

يمكنك تنزيل مجموعة Postman التي نوفرها وتكوينها للتفاعل مع API الخاصة بواتساب للأعمال إذا كنت لا تريد استخدام سطر الأوامر.

يمكنك إجراء التحقق من سلامة الأداء في عميل API الخاصة بواتساب للأعمال باستخدام استدعاء API إلى العقدة health.

يجب أن يبدو الإخراج الناتج كما يلي:

{
    "health": {
        "gateway_status": "unregistered"
    }
}

تعرض الاستجابة حالة gateway_status لـ unregistered باعتبارها gateway_status نظرًا إلى أنه لم يتم تسجيل عميل API الخاصة بواتساب للأعمال بعد.

الخطوة التاسعة: تسجيل عميل API الخاصة بواتساب للأعمال

يمكنك تسجيل عميل API الخاصة بواتساب للأعمال باستخدام استدعاء API في العقدة account.

الخطوة العاشرة: إجراء عملية ثانية للتحقق من سلامة الأداء

قم بإجراء التحقق من سلامة الأداء مرة أخرى في عميل API الخاصة بواتساب للأعمال باستخدام استدعاء API إلى العقدة health بعد إكمال التسجيل.

يجب أن يبدو الإخراج الناتج كما يلي:

{
    "health": {
        "gateway_status": "connected"
    }
}

يشير تعيين gateway_status على connected إلى قدرة حاوية Coreapp على الاتصال بخادم واتساب لإجراء التحقق من جهات الاتصال وإرسال الرسائل.

يوصى بإعداد التحقق في عميل API الخاصة بواتساب للأعمال للإنتاج.

ترقية عميل API الخاصة بواتساب للأعمال

ستواجه مشكلة زمن التوقف أثناء عملية الترقية.

يوصى بشدة بإجراء نسخ احتياطي لإعدادات التطبيق الحالية لديك قبل الترقية للتأكد من أنه يمكنك نسخ الإعدادات احتياطيًا وتشغيلها سريعًا. يُرجى اتباع وثائق النسخ الاحتياطي والاستعادة.

نوصي دائمًا بتنفيذ الترقيات خلال الساعات الأقل نشاطًا.

الخطوة الأولى: تغيير متغير البيئة WA_API_VERSION إلى الإصدار الجديد

يجب تحديث المتغير البيئي WA_API_VERSION إلى رقم الإصدار الجديد باستخدام:

export WA_API_VERSION=new-whatsapp-version

الخطوة الثانية: إعادة تشغيل حاويات Docker

أعد تشغيل حاويات Docker من خلال تشغيل:

docker-compose -f prod-docker-compose.yml up -d

بالنسبة لمستخدمي قاعدة بيانات MySQL الذين يقومون بالترقية إلى الإصدار v2.23.x والإصدارات الأحدث

ويمكنك الآن الاستفادة من خدمة ترقية قاعدة البيانات التي ستتيح لك ترقية قاعدة البيانات بينما لا يزال تطبيقك قيد التشغيل لتجنب زمن التوقف.

الخطوة الأولى: تنزيل ملف التكوين

يتضمن الملف dbupgrade-compose.yml حقولاً تشير إلى إصدار الحاوية.

المثال:

services:
  dbupgrade:
    image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.3}

الخطوة الثانية: بدء تشغيل الحاوية

لترقية عملية تثبيت، يمكنك بدء تشغيل الحاوية dbupgrade-service مع تعيين متغير البيئة WA_API_VERSION إلى أحدث إصدار:

WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml up -d

ملاحظة: إذا كنت تستخدم تزامنًا يعيد تشغيل الحاوية عند الخروج بغض النظر عن الرمز للخروج، يمكنك بدء تشغيل الخدمة من خلال تعيين متغير البيئة EXIT_ON_SUCCESS إلى القيمة FALSE لتجنب الخروج من الحاوية عندما يكون الرمز للخروج بالقيمة 0.

الخطوة الثالثة: السماح بإكمال الترقية

إذا تمت ترقية قاعدة البيانات بنجاح، فستخرج الحاوية بالرمز 0. يمكنك استخدام أمر Docker التالي لتتبع الحالة:

docker wait your-database-upgrade-container-name

سيؤدي ذلك إلى عرض رمز الخروج الخاص بحاوية dbupgrade-service.

الخطوة الرابعة: إعادة تشغيل حاويات Coreapp وWebapp

أعد تشغيل حاويات Docker في Coreapp وWebapp مع تعيين متغير البيئة WA_API_VERSION إلى أحدث إصدار:

WA_API_VERSION=new-whatsapp-version docker-compose -f prod-docker-compose.yml up -d

بالنسبة لمستخدمي عميل API الخاصة بواتساب للأعمال الذين يقومون بالترقية إلى الإصدار 2.29.3 والإصدارات الأحدث

إذا كنت تقوم بالترقية من v2.29.1 وv2.29.2أو واجهت مشكلات أثناء الترقية إلى هذه الإصدارات وكان عليك الرجوع إلى إصدار قديم من للحصول على أداء ثابت، فنوصي بالترقية إلى v2.29.3 ثم تشغيل الأمر التالي في حاوية Webapp Docker:

chown -R root your-media-directory/incoming your-media-directory/outgoing your-media-directory/shared

ما لم تقم بتغييره، فإن دليل الوسائط الافتراضي هو /usr/local/wamedia.

ملاحظة:

  • نظرًا إلى أن هذا الأمر يمكن أن يستغرق بعض الوقت حتي يكتمل استنادًا إلى حجم وحدة تخزين الوسائط الموجودة مسبقًا، نوصي ببدء هذا الأمر بمجرد الترقية أثناء فترة الصيانة.
  • يعمل هذا الأمر فقط على تعديل ملكية وحدات تخزين الوسائط في الخلفية (لا يوجد تأثير/زمن توقف لعمليات الوسائط أو تأخر استجابة/أداء أثناء التشغيل).
  • هذا مسار ترقية لمرة واحدة فقط لإصلاح مشكلات التوافق مع الإصدارات السابقة في v2.29.1 وv2.29.2.

إلغاء تثبيت عميل API الخاصة بواتساب للأعمال

نوصي بشدة بإجراء نسخ احتياطي لإعدادات التطبيق الحالية قبل إلغاء التثبيت. يُرجى اتباع وثائق النسخ الاحتياطي والاستعادة.

إذا كنت تريد إعادة تعيين بيئة التطوير عن طريق إزالة جميع الحاويات، فقم بتشغيل الأمر التالي من المسار الذي يتضمن ملف prod-docker-compose.yml:

docker-compose -f prod-docker-compose.yml down

يجب أن يبدو الإخراج الناتج كما يلي:

Stopping biz_waweb_1  ... done
Stopping biz_wacore_1 ... done
Removing biz_waweb_1  ... done
Removing biz_wacore_1 ... done

لإزالة كل وحدات التخزين المحددة في الملف prod-docker-compose.yml وكذلك الحاويات، يمكنك تشغيل الأمر down باستخدام المعلمة -v:

docker-compose -f prod-docker-compose.yml down -v

استكشاف الأخطاء وإصلاحها

نوصي باستخدام WADebug لاستكشاف الأخطاء وإصلاحها بشكل أكثر فعالية. أداة WADebug عبارة عن أداة سطر أوامر للمساعدة في العثور على المشكلات المحتملة المتعلقة بإعداد API الخاصة بواتساب للأعمال وجعل عملية طلب المساعدة من دعم واتساب أكثر فعالية.

في الحالات التي يتعذر فيها استخدام WADebug أو يؤدي تشغيل الأداة إلى إرجاع أخطاء، يمكنك تشغيل الأمر التالي لتجميع السجلات من كل الحاويات:

docker-compose -f prod-docker-compose.yml logs > debug_output.txt

لتجميع السجلات الخاصة بخدمة معينة، يمكنك إلحاق اسم الخدمة (waweb أو wacore) بالأمر docker-compose logs:

docker-compose -f prod-docker-compose.yml logs waweb > debug_output.txt

يمكنك العثور على السجلات في الملف debug_output.txt في الدليل الحالي.

يستخدم هذا البرنامج الرمز FFmpeg المُرخص بموجب رخصة جنو العمومية الصغرى (LGPL) بالإصدار 2.1 ويمكن تنزيل مصدره من هنا.