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

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

إعدادات التطبيق

إعدادات التطبيق لعميل الواجهة داخل المواقع في واتساب للأعمال.

المتطلبات

  • يجب إجراء طلبات باستخدام الحساب admin
  • يجب أن تتضمن كل الاستجابات 200 OK HTTPS

القراءة

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

مثال

أرسل طلب GET إلى نقطة النهاية /v1/settings/application للحصول على إعدادات التطبيق الحالية.

GET /v1/settings/application

عند نجاح الأمر، ستحتوي الاستجابة على 200 OK وستتضمن حمولة بيانات JSON كائن application يسرد كل إعدادات التطبيق الحالية وقيمها.

عينة من الاستجابة

{
    "settings": {
        "application": {
            "callback_backoff_delay_ms": 3000,
            "callback_persist": true,
            "garbagecollector_enable": {
                "media": false,
                "messages": true
            },
            "heartbeat_interval": 5,
            "max_callback_backoff_delay_ms": 900000,
            "media": {
                "auto_download": [
                    "image",
                    "video",
                    "voice",
                    "sticker",
                    "audio",
                    "document"
                ]
            },
            "notify_user_change_number": true,
            "show_security_notifications": true,
            "unhealthy_interval": 30,
            "wa_id": "16315551019",
            "webhooks": {
               	"url": "<Webhook URL, https>",
               	"max_concurrent_requests": max-concurrent-requests,
               	"message": { // Available for v2.41.2 and above
                  	"sent": true,
                  	"delivered": true,
                  	"read": false
                 },
             },
             "verbose_logging": false,
             "log_level" : "info"
         },
    },
    "meta": {
        "api_status": "stable",
        "version": "3.0.1"
    }
}

عناصر الربط

عنصر الربطالوصف

/media/providers

يمكن استخدامه لإدارة قائمة موفري خدمات الوسائط من أجل إرسال روابط الوسائط.

تحديث

لتحديث إعدادات التطبيق، أرسل طلب PATCH إلى نقطة النهاية /v1/settings/application مع تضمين كائن JSON يحتوي على أسماء الحقول والقيم التي يجب تعيينها.

بالنسبة لحملات المراسلة التي تتضمن عدد كبير من الرسائل، يوصى بتعطيل التجميع التلقائي للبيانات المهملة عن طريق تعيين garbagecollector_enable.messages على false، وإعادة تمكينها بعد انتهاء الحملة عن طريق تعيينها مجددًا على true.

يمكنك التحقق مما إذا كان التجميع التلقائي للبيانات المهملة معطلاً عن طريق إرسال طلب GET إلى نقطة النهاية /v1/settings/application وقراءة الخاصية garbagecollector_enable.

مثال على الطلب

PATCH /v1/settings/application
{
    "callback_persist": true | false,
    "max_callback_backoff_delay_ms": max-delay-in-ms,
    "media": {
        "auto_download": ["audio", "document", "voice", "video", "image", "sticker"]
    }
    "callback_backoff_delay_ms": "delay-in-ms",
    "heartbeat_interval": heartbeat-interval-in-secs,
    "unhealthy_interval": unhealthy-interval-in-secs,
    "webhooks": { 
        # See the Webhooks Parameters table below for more information
        "max_concurrent_requests": max-concurrent-requests,
        "url": "<Webhook URL, https>",
        "message": {              // Available on v2.41.2 and above
                "sent": false,
                "delivered": true,
                "read": false
           },
    },
    "axolotl_context_striping_disabled": false | true,
    "notify_user_change_number": false | true,
    "show_security_notifications": false | true,
    # Available on v2.49.1 and above
    "garbagecollector_enable": {
        "messages": true | false,
        "media": true | false
    }
    "skip_referral_media_download": true | false,
    "webhook_payload_conversation_pricingmodel_disabled": false | true
    # Available on v2.51.1 and above
    "verbose_logging": false | true,
    "log_level" : log-level-str,
}

عند نجاح الأمر، تحتوي الاستجابة على 200 OK يتضمن null أو كائن JSON.

وإذا كنت تواجه أي أخطاء، فيمكنك الرجوع إلى رسائل الأخطاء والحالة.

المعلمات

تتطلب بعض الإعدادات إعادة تشغيل Coreapp من أجل تطبيق التغييرات. تتمثل هذه الإعدادات في callback_persist وgarbagecollector_enable وverbose_logging وlog_level وwebhooks.max_concurrent_requests.

`log_level`
الاسمالوصف

axolotl_context_striping_disabled

النوع: Boolean (قيمة منطقية)

يمكن أن يؤثر على تقييدات الاتصال بقاعدة البيانات.


تم تحسين الأداء الصادر والوارد باستخدام الإصدار v2.25. ويعتمد هذا التحسين على إنشاء اتصالات إضافية بقاعدة البيانات. بالنسبة لبعض عمليات النشر، قد يتسبب ذلك في الوصول إلى تقييدات الاتصال بقاعدة البيانات. وفي هذه الحالة، يجب تعيين تكوين axolotl_context_striping_disabled إلى القيمة true لتعطيل ميزة تحسين الأداء هذه. ولا توجد تأثيرات أخرى على إحدى وظائف Coreapp.


القيم:true، false (افتراضي)

يلزم إعادة تشغيل Coreapp.

callback_backoff_delay_ms

النوع: String (سلسلة)

يمثل تأخير التراجع لعملية الاستدعاء الفاشلة بوحدات المللي ثانية.


يُستخدم هذا الإعداد لتكوين مدة تأخير التراجع قبل إعادة محاولة إجراء عملية استدعاء فاشلة. وتزيد مدة تأخير التراجع خطيًا حسب هذه القيمة في كل مرة تفشل فيها عملية الاستدعاء للحصول على استجابة HTTPS 200 OK. ويكون الحد الأقصى لتأخير التراجع مقيّدًا بالإعداد max_callback_backoff_delay_ms. فعلى سبيل المثال، إذا فشل الاستدعاء في المرة الأولى، فستتم إعادة المحاولة في غضون 3000 مللي ثانية (3 ثوانٍ). سيؤدي الفشل لمرة ثانية إلى التأخير لمدة 6000 مللي ثانية (6 ثوانٍ) قبل إعادة المحاولة. ويستمر هذا الأمر حتى ينجح الاستدعاء أو تصل مدة التأخير إلى 900000 مللي ثانية (15 دقيقة)، وبعد هذه المدة، ستستمر إعادة محاولة الاستدعاء، ولكن لن تزيد مدة التأخير عن ذلك.


القيمة الافتراضية: 3000

callback_persist

النوع: Boolean (قيمة منطقية)

يمكن تخزين الاستدعاءات على قرص حتى يقرها حدث Webhook بنجاح، أو يرفضها. يتم تخزين الرسائل والاستدعاءات في قاعدة بيانات محلية للتأكد من عرضها بنجاح قبل إزالتها من قاعدة البيانات المحلية. يحمي هذا عمليات الاستدعاء في حالة تعطل خادم أو عميل API الخاصة بواتساب للأعمال.
تتم إعادة محاولة إرسال الإشعارات غير الناجحة (لا توجد استجابة HTTPS 200) بشكل مستمر. واستخدم هذا الإعداد لتكوين إعادة المحاولة.


القيم:true (افتراضي)، false
يلزم إعادة تشغيل Coreapp.

db_garbagecollector_enable

النوع: Boolean (قيمة منطقية)

تم إيقاف استخدام هذا الحقل في الإصدار 2.49.


يمكن السماح بتجميع البيانات المهملة تلقائيًا لقاعدة بيانات الرسائل للمساعدة في إدارة قاعدة البيانات.


تتوفر هذه المعلمة بالقيمة false للمستخدمين الذين تم تعيين pass_through لديهم إلى القيمة false قبل الإصدار v2.29. نوصيك بتمكين هذا الإعداد لضمان عمل قاعدة بياناتك باستقرار. إذا كنت تريد تعطيل هذا الإعداد، فنوصيك باستخدام نقطة النهاية /services/message/gc لإدارة قاعدة البيانات.


القيم:true (افتراضي)، false

يلزم إعادة تشغيل Coreapp.

garbagecollector_enable

النوع: Garbage collector Object (جامع البيانات المهملة)

يسمح بتجميع البيانات المهملة تلقائيًا للرسائل والوسائط.


يوصى بإعداد جامع البيانات المهملة للرسائل والوسائط لضمان إزالة الصفوف والملفات القديمة/غير المستخدمة. إذا تم التعطيل، فقد تتم تهيئة جامع البيانات المهملة باستخدام نقاط النهاية /services/message/gc و/services/media/gc. راجع جدول معلمات جامع البيانات المهملة للقيم.


يلزم إعادة تشغيل Coreapp.

heartbeat_interval

النوع: Integer (عدد صحيح)

يمثل الفاصل الزمني الذي تستغرقه العقدة Master في التحقق من عُقد Coreapp بالثواني.


القيمة الافتراضية: 5
تنطبق على عمليات إعداد الاتصال المتعدد.

max_callback_backoff_delay_ms

النوع: String (سلسلة)

يمثل الحد الأقصى للتأخير بالنسبة لعملية الاستدعاء الفاشلة بوحدات المللي ثانية. ولمزيد من المعلومات، اقرأ وصف callback_backoff_delay_ms أدناه.


القيمة الافتراضية: 900000

media

النوع: Array (مصفوفة)

يمثل قائمة الوسائط المطلوب تنزيلها تلقائيًا. لمزيد من المعلومات، يمكنك الرجوع إلى إعدادات تنزيل الوسائط تلقائيًا.

notify_user_change_number

النوع: Boolean (قيمة منطقية)

يمكن أن يؤثر على إشعار النظام user_changed_number.


القيم:true، false (افتراضي)

pass_through

النوع: Boolean (قيمة منطقية)

بدءًا من الإصدار 2.35، لن يمكنك إعادة تمكين إعداد pass_through بعد الآن لعملاء واجهة API الخاصة بتطبيق WhatsApp للأعمال.


يمكن السماح بحذف الرسائل الفردية أو تخزينها في أية قاعدة بيانات محلية بعد استلامها أو قراءتها.


عند إرسال الرسائل، يتم تخزينها في قاعدة بيانات محلية. تُستخدم قاعدة البيانات هذه كسجل للتطبيق. وبما أن النشاط التجاري يحتفظ بسجله الخاص، يمكنك تحديد ما إذا كنت تريد إرسال pass_through أم لا.

  • عند التعيين إلى القيمة true، تتم إزالة الرسائل من قاعدة البيانات المحلية بعد أن يستلمها المستلم أو يقرأها.
  • عند التعيين على القيمة false، يتم حفظ جميع الرسائل بوحدة التخزين المحلية حتى يتم حذفها تلقائيًا (أي، تكون db_garbagecollector_enable بالقيمة true) أو يتم حذفها بشكل صريح (أي، تكون db_garbagecollector_enable بالقيمة false). لمزيد من المعلومات، يمكنك الرجوع إلى وثائق الخدمات.

نوصيك بتعطيل pass_through بحيث يعمل الاستدعاء بالحالة status كما هو متوقع.


القيم:true، false (افتراضي)

يلزم إعادة تشغيل Coreapp.

show_security_notifications

النوع: Boolean (قيمة منطقية)

إذا تم التمكين، فستتلقى إشعارًا بحدث Webhook user_identity_changed عندما يكتشف عميل واجهة API الخاصة بتطبيق WhatsApp للأعمال عن احتمالية تغيير أي مستخدم تجري محادثة معه. وعند حدوث ذلك، سيتم حظر كل الرسائل الصادرة إلى هذا المستخدم حتى تقر بتغيير هوية هذا المستخدم باستخدام نقطة النهاية identity.


القيم:true، false (افتراضي)

skip_referral_media_download

النوع: Boolean (قيمة منطقية)

في حالة التعيين إلى القيمة true، لن يتم تنزيل الصورة أو الفيديو الذي نقر عليه المستخدم في إعلان النقر لفتح محادثة في WhatsApp.


القيمة الافتراضية:false

unhealthy_interval

النوع: Integer (عدد صحيح)

يمثل الحد الأقصى للمدة التي تنتظرها العقدة Master بالثواني حتى تستجيب عقدة Coreapp لإشارة الاتصال قبل اعتبارها غير صالحة وبدء عملية تجاوز الفشل.


القيمة الافتراضية: 30
تنطبق على عمليات إعداد الاتصال المتعدد.

webhook_payload_conversation_pricingmodel_disabled

النوع: Boolean (قيمة منطقية)

تم إيقاف استخدام هذا الحقل في الإصدار 2.39.

يمكن التحكم في تضمين المحادثة وحمولات بيانات معلومات الأسعار في إشعارات حالة الرسالة.


القيم:true، false (افتراضي)

لا يلزم إعادة تشغيل Coreapp.

webhooks

النوع: Webhooks Object (كائن Webhooks)

مطلوب عند استخدام Webhooks.

يجب توفير عنوان URL لـ Webhook. وإذا لم يتم تعيين عنوان URL لـ Webhook، فسيتم إسقاط الاستدعاءات. للحصول على طريقة بسيطة لعرض أحداث Webhooks واختبارها، راجع عينة التطبيق الاختباري.


يمكنك التحقق من صحة أحداث Webhook من خلال تحديد مفتاح سري تمت مشاركته كمعلمة استعلام عند تعيين عنوان URL لحدث Webhook. المثال: https://url?auth='[shared_secret]'.

يمثل عنوان URL لحدث Webhook. فعلى سبيل المثال: https://spotless-process.glitch.me/webhook.


إذا لم يتم تعيين عنوان URL لحدث Webhook، فمن ثمّ سيتم إصدار الاستدعاءات. وتكون الاستدعاءات عبارة عن قناة مهمة لعرض الإشعارات في الوقت المناسب، بالإضافة إلى الأخطاء خارج النطاق، وبالتالي نوصيك بشدة بتكوين نقطة نهاية عنوان URL لحدث Webhook. للحصول على تفاصيل حول حقول حدث Webhook، يمكنك الرجوع إلى جدول معلمات أحداث Webhooks أدناه.

verbose_logging

النوع: Boolean (قيمة منطقية)

تعمل على تمكين التسجيل التفصيلي في coreapps. يجب ألا يتم استخدام مستوى التسجيل هذا إلا لأغراض الاختبار بسبب حجم الإخراج العالي. إذا تم التعيين على true، فسيتم تجاهل الإسناد log_level.


القيم:true، false (افتراضي)

log_level

النوع: Webhooks Object (كائن Webhooks)

يعمل على تكوين مستوى التسجيل في coreapps. يعمل كل مستوى تدريجيًا على تقليل عدد نتائج السجلات: info تحتوي على معظم المعلومات، بينما تحتوي على fatal أخطاء فادحة فقط.


القيم:info (افتراضي) وwarning وerror وfatal

معلمات Webhooks

الاسمالوصف

max_concurrent_requests

النوع: Integer (عدد صحيح)

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


القيم:6 (افتراضي) أو 12 أو 18 أو 24
يلزم إعادة تشغيل Coreapp.

url

النوع: String (سلسلة)

يتم توجيه الإشعارات الواردة والصادرة إلى عنوان URL هذا. ولمزيد من المعلومات، يمكنك الرجوع إلى وثائق أحداث Webhooks.


يلزم توفير نقطة نهاية قائمة على HTTPS؛ وإلا، فلن يعمل HTTP.
المثال:https://spotless-process.glitch.me/webhook

message

النوع: Messages Object (كائن رسائل)

متوفر في الإصدار 2.41.2 والإصدارات الأحدث

من خلال التضمين في كائن webhooks يمكن للعملاء تعيين إشعارات webhook ذات الصلة بالرسالة التي يريدون تلقيها من هذه القائمة: sent، delivered، read. يمكن العثور على المزيد من المعلومات حول تلك الحالات هنا.


يمكن للنشاط التجاري اختيار تلقي إشعارات webhook هذه أو عدم تلقيها عن طريق تعيين القيم على true (افتراضي) أو false.

معلمات الوسائط

الاسمالوصف

auto_download

النوع: Array (مصفوفة)

يمكن تحديد أنواع الوسائط المطلوب تنزيلها تلقائيًا.


القيم:audio، document، voice، video، image، sticker

معلمات جامع البيانات المهملة

الاسمالوصف

messages

النوع: Bool (قيمة منطقية)

تعمل على تكوين تجميع بيانات الرسائل المهملة.


القيم:true (افتراضي)، false
يلزم إعادة تشغيل Coreapp.

media

النوع: Bool (قيمة منطقية)

تعمل على تكوين تجميع بيانات الوسائط المهملة.


القيم:true، false(افتراضي)
يلزم إعادة تشغيل Coreapp.

إعادة التعيين إلى الإعدادات الافتراضية

لإعادة تعيين كل إعدادات التطبيق إلى القيم الافتراضية، أرسل طلب DELETE إلى نقطة النهاية /v1/settings/application.

مثال على الطلب

DELETE /v1/settings/application

عند نجاح الأمر، ستحتوي الاستجابة على 200 OK يتضمن null أو {}.

إذا كنت تواجه أي أخطاء، فيمكنك الرجوع إلى رسائل الأخطاء والحالة.