‏API السحابة‏

منصة واتساب للأعمال > API السحابة

نظرة عامة

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

بروتوكول HTTP

تم بناء API السحابة استنادًا إلى Graph API، لذلك يتم التعبير عن الطلبات باستخدام بروتوكول HTTP ومجموعات من معلمات عناوين URL والعناوين ونصوص الطلب. على سبيل المثال، يبدو الاستدعاء الشائع لـ API السحابة من سطر الأوامر المستند إلى UNIX كما يلي:

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

إذا لم تكن على دراية بـ Graph API، فيُرجى الرجوع إلى وثائق Graph API لمعرفة الأساسيات. تتمثل الاختلافات الرئيسية بين Graph API وAPI السحابة في أنواع رموز الوصول التي ستستخدمها عادةً، وأذونات الموارد، وبنية الطلب، وبنية أحداث webhooks. يتم وصف هذه الاختلافات بمزيد من التفصيل في الأقسام المناسبة من مجموعة وثائق API السحابة.

الموارد

هذه هي الموارد الأساسية التي ستتفاعل معها عند استخدام API.

حافظة الأعمال

لاستخدام API، يجب أن تتوفر لديك حافظة أعمال. إذا لم يكن لديك حافظة أعمال، فستتم مطالبتك بإنشاء واحدة كجزء من عملية البدء. تعمل حافظات الأعمال كحاوية لحساب واتساب للأعمال الخاص بك (WABA) وأرقام هواتف النشاط التجاري.

لمعرفة المزيد عن حافظات الأعمال، راجع مقالة مركز المساعدة حول حافظات الأعمال في Meta Business Suite.

حسابات واتساب للأعمال

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

يمكنك إنشاء حساب واتساب للأعمال عن طريق اتباع الخطوات في مستند بدء الاستخدام. لمعرفة المزيد عن حسابات واتساب للأعمال والتقييدات، راجع حسابات واتساب للأعمال.

أرقام الهواتف لحساب واتساب للأعمال

يمثل رقم هاتف واتساب للأعمال (رقم هاتف النشاط التجاري) رقم هاتف حقيقيًا، يمكن استخدامه بمجرد تسجيله للاستخدام مع API السحابة لإرسال الرسائل من وإلى مستخدمي واتساب واستلامها عبر API.

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

يمكنك إنشاء رقم هاتف أعمال من خلال اتباع الخطوات في مستند بدء الاستخدام. لاحظ أن هناك حدود وتقييدات على أرقام هواتف الأعمال واستخداماتها، وهي موضحة بالتفصيل في مستند أرقام هواتف الأعمال.

قوالب رسائل واتساب

قوالب (قالب) رسائل واتساب هي قوالب قابلة للتخصيص يمكنك إنشاؤها عبر API باستخدام مكونات القوالب المختلفة. بمجرد إنشاء القوالب، تتم مراجعتها تلقائيًا، وإذا تمت الموافقة عليها، فسيمكن استخدامها في رسائل القوالب.

هناك نوعان أساسيان من الرسائل التي يمكنك إرسالها عبر API: رسائل الرسائل الحرة ورسائل القوالب. من بين النوعين، تُعد رسائل القوالب هي الأكثر تقييدًا، نظرًا إلى أنها تتطلب استخدام قالب رسالة واتساب معتمد. ومع ذلك، نظرًا إلى أن القوالب يجب أن تخضع للمراجعة وتتم الموافقة عليها قبل استخدامها، فإن رسائل القوالب أقل عرضة لتلقي ملاحظات سلبية من جانب المستلمين، مما قد يهدد قدرتك على مراسلة العملاء بالكامل.

لمعرفة المزيد عن القوالب، يرجى الرجوع إلى مستند القوالب.

Webhooks

أحداث Webhooks هي ببساطة حمولات بيانات بلغة JSON يتم إرسالها باستخدام بروتوكول HTTP إلى نقطة نهاية عامة على الخادم. تعتمد API السحابة بشكل كبير على أحداث webhooks، حيث سيتم إرسال محتويات أي رسائل يتم إرسالها بواسطة مستخدم واتساب إلى رقم هاتف نشاطك التجاري كحدث webhook، ويتم الإبلاغ عن جميع تحديثات حالة تسليم الرسائل الصادرة عبر حدث webhook.

لاحظ أننا نقدم عينة من تطبيق webhook يمكنك نسخها على Glitch واستخدامها للاختبار. يقوم التطبيق فقط بتفريغ حمولات أحداث webhooks مباشرةً في وحدة التحكم حتى تتمكن من رؤية محتوياتها. ضع في اعتبارك أنك بحاجة في النهاية إلى إنشاء نقطة نهاية خاصة على الخادم لديك في مرحلة ما والتي تستوعب أحداث webhooks وفقًا لمنطق نشاطك التجاري.

راجع أحداث Webhooks في Meta لمعرفة المزيد عن أحداث webhooks وكيفية استيعابها، ومستند أحداث Webhooks لحسابات واتساب للأعمال.

موارد الاختبار

عندما تكمل الخطوات لأول مرة في مستند بدء الاستخدام، يتم إنشاء حساب واتساب للأعمال اختباري ورقم هاتف أعمال اختباري تلقائيًا.

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

يمكنك حذف حافظة الأعمال وموارد الاختبار الخاصة بها إذا:

  • كنت مسؤولاً في حافظة الأعمال المرتبطة بالتطبيق
  • كان لا توجد تطبيقات أخرى مرتبطة بحافظة الأعمال
  • كانت حافظة الأعمال غير مرتبطة بأي حسابات واتساب للأعمال أخرى
  • كان حساب واتساب للأعمال غير مرتبط بأي أرقام هواتف أعمال أخرى.

لحذف حافظة الأعمال ومواردها الاختبارية:

  1. انتقل إلى لوحة معلومات التطبيق > واتساب > لوحة التكوين.
  2. حدد مكان قسم الحساب الاختباري.
  3. انقر على زر حذف.

المصادقة والتصريح

رموز الوصول

تدعم API ثلاثة أنواع من الرموز:

  • رموز وصول مستخدم النظام
  • رموز وصول مستخدم نظام دمج الأعمال
  • رموز وصول المستخدم

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

الأذونات

تعتمد API على أذونات Graph API التالية. يعتمد المزيج الدقيق من الأذونات التي يحتاجها تطبيقك على نقاط النهاية التي يمكن لتطبيقك الوصول إليها.

  • business_management - مطلوب إذا كنت تتفاعل مع حافظة الأعمال.
  • whatsapp_business_management - مطلوب إذا كان التفاعل مع حساب واتساب للأعمال وتحليلاته، أو أي من قوالب أو أرقام هواتف الأعمال لديك.
  • whatsapp_business_messaging - مطلوب لإرسال الرسائل من وإلى مستخدمي واتساب واستلامها.

عادةً ما يتم منح هذه الأذونات عند إنشاء رموز الوصول في Meta Business Suite. راجع أقسام إنشاء الرمز في مستند رموز الوصول.

تعيين الإصدارات

يستخدم تعيين الإصدارات بروتوكول تعيين الإصدارات في واجهة برمجة التطبيقات (API) الرسم البياني. هذا يعني أنه يمكن أن تتضمن كل طلبات نقاط النهاية رقم الإصدار وسيتوفر كل إصدار لمدة عامين تقريبًا قبل أن يتم إيقاف العمل به ولا يمكن استدعاؤه بعد ذلك.

معدل الإرسال

بالنسبة لكل رقم هاتف نشاط تجاري مسجل، ستدعم API السحابة ما يصل إلى 80 رسالة في الثانية بشكل افتراضي، وما يصل إلى 1000 رسالة في الثانية حسب الترقية التلقائية.

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

إذا حاولت إرسال عدد رسائل أكبر مما يسمح به مستوى معدل الإرسال الحالي، فستعمل API على إرجاع رمز الخطأ 130429 حتى تعود إلى حد المستوى المسموح به مرة أخرى. كما أن معدلات الإرسال تكون مخصصة للحملة الإعلانية التي تستند إلى المراسلات والتي تتضمن أرقام هواتف مختلفة لمستخدمي واتساب. إذا حاولت إرسال عدد كبير من الرسائل لرقم مستخدم واتساب ذاته، فقد تتعرض لخطأ تقييد معدلات الاستدعاء المخصص للإقران.

معدل الإرسال العالي

إذا كنت تفي بمتطلبات الأهلية، فسنعمل على ترقية رقم هاتف النشاط التجاري تلقائيًا إلى 1,000 رسالة في الثانية بدون أي رسوم. لا يتم فرض رسوم إضافية على معدل الإرسال العالي ولا يؤثر على التسعير.

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

متطلبات الأهلية

Webhooks

يجب أن تكون خوادم حدث webhook قادرة على استيعاب 3 أضعاف كمية بيانات الرسائل الصادرة وضعف كمية بيانات الرسائل الواردة المتوقعة. على سبيل المثال، إذا أرسلت 1,000 رسالة في الثانية بمعدل استجابة متوقع 30%، يجب أن تكون خوادمك قادرة على معالجة ما يصل إلى 3000 حدث webhooks لحالة الرسالة بالإضافة إلى 300 حدث webhooks لرسالة إضافية واردة.

نحاول أن نعرض أحداث webhooks في وقت واحد، لذلك نوصي بتكوين واختبار تحميل خادم webhook لمعالجة الطلبات المتزامنة من خلال معيار زمن الاستجابة التالي:

  • يجب ألا يتجاوز متوسط زمن الاستجابة 250 ملي ثانية.
  • يمكن أن يتجاوز زمن الاستجابة ثانية واحدة في أقل من 1% من الطلبات.

سنحاول أن نعيد عرض أحداث webhooks غير الناجحة لما يصل إلى 7 أيام، بتراجع مطرد.

رسائل الوسائط

للاستفادة بالكامل من معدل الإرسال العالي، نوصي بتحميل أصول الوسائط إلى الخوادم واستخدام معرفات الوسائط التي تم إرجاعها في رسائل الوسائط بدلاً من استضافة الأصول على الخوادم الخاصة واستخدام عناوين URL أصل الوسائط. إذا كنت تفضل (أو يجب) استضافة الأصول على الخوادم الخاصة، فنوصي باستخدام التخزين المؤقت للوسائط.

الحصول على مستوى معدل الإرسال

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

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

الترحيل

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

تقييدات معدلات الاستدعاء

راجع تقييدات معدلات استدعاء API إدارة واتساب للأعمال.

بالإضافة إلى تقييدات معدلات الاستدعاء هذه، لدينا المزيد من التقييدات الدقيقة على الموارد الفردية، مثل رسائل القوالب وأرقام هواتف النشاط التجاري الاختبارية:

أدوات القياس المتوفرة

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

التوسيع

تتوسع API السحابة وتتكيف تلقائيًا داخل البنية الأساسية في Meta لمعالجة عبء العمل، بموجب تقييد معدلات الاستدعاء (حجم المراسلة وعدد حسابات واتساب للأعمال).

خصوصية البيانات والأمان

راجع نظرة عامة على الخصوصية والأمان للحصول على المعلومات.

التشفير

من خلال API السحابة، تظل كل رسالة واتساب محمية بواسطة تشفير بروتوكول Signal الذي يؤمّن الرسائل قبل إرسالها من الجهاز. هذا يعني أن الرسائل التي تحتوي على حساب واتساب للأعمال يتم تسليمها بأمان إلى الوجهة التي يختارها كل نشاط تجاري.

تستخدم API السحابة تقنيات تشفير قياسية في هذا المجال لحماية البيانات أثناء النقل وفي حالة الثبات. تعتمد API على Graph API لإرسال الرسائل بينما تعتمد على أحداث Webhooks لاستلام الأحداث، ويعمل كلاهما عبر استدعاءات HTTPS القياسية والمحمية بواسطة TLS. راجع المستند التقني "نظرة عامة على التشفير" لمزيد من التفاصيل.

راجع المستند التقني "نظرة عامة على التشفير" لمزيد من التفاصيل.

تقييدات معدلات الاستدعاء المخصصة للإقران

يتم تقييد أرقام هواتف النشاط التجاري بحيث ترسل رسالة واحدة كل 6 ثوانٍ إلى رقم هاتف مستخدم واتساب ذاته (0.17 من الرسائل/ثانية). هذا يعادل تقريبًا 10 رسائل في الدقيقة أو 600 رسالة في الساعة. إذا تجاوزت هذا التقييد، فسترجع API رمز الخطأ 131056 حتى تصبح ضمن التقييد مرة أخرى.

إذا لزم الأمر، فيمكنك إرسال ما يصل إلى 45 رسالة في غضون 6 ثوانٍ كدفعة. إذا أرسلت دفعة، فأنت تقترض بشكل أساسي من تقييد معدلات الاستدعاء المخصص للإقران، لذلك سيتم منعك من إرسال رسائل لاحقة للمستخدم ذاته حتى يمر الوقت الذي يستغرقه عادةً إرسال هذا العدد من الرسائل "غير المتسلسلة" إلى المستخدم. على سبيل المثال، يستغرق الأمر دقيقتين تقريبًا لإرسال 20 رسالة "غير متسلسلة" إلى المستخدم، لذلك إذا أرسلت دفعة من 20 رسالة، فستحتاج إلى الانتظار دقيقتين تقريبًا قبل أن تتمكن من إرسال رسالة أخرى إلى المستخدم.

لتجنب الاضطرار إلى حساب أوقات انتظار الرسائل بعد إرسال رسالة متسلسلة، نوصي بأنه في حالة فشل طلب إرسال رسالة بعد إرسال رسالة متسلسلة، حاول مرة أخرى بعد 4^X ثانية، حيث X = 0، ويزيد بمقدار 1 بعد كل محاولة فاشلة، حتى نجاح الطلب.

الأدوات

مدير واتساب

مدير واتساب هو تطبيق على الويب يسمح لك بإدارة موارد واتساب يدويًا، مثل حسابات واتساب للأعمال وأرقام هواتف النشاط التجاري والقوالب ويوفر طريقة سهلة لعرض الرؤى وتقييمات الجودة والتقييدات على هذه الموارد. تتوفر أيضًا معظم الوظائف المقدمة من مدير واتساب عبر API مع وجود بعض الاستثناءات الطفيفة.

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

عبر Meta Business Suite

  1. قم بتسجيل الدخول إلى Meta Business Suite.
  2. إذا كان لديك عدة حافظات أعمال، فاستخدم القائمة المنسدلة على اليمين لتحديد الحساب الذي يملك حساب واتساب للأعمال الذي تريد تحميله في مدير واتساب أو يمكنه الوصول إليه.
  3. في القائمة على اليمين، انتقل إلى الحسابات > حسابات واتساب.
  4. حدد حساب واتساب للأعمال.
  5. في علامة تبويب الملخص، انقر على الزر مدير واتساب.

عبر لوحة معلومات التطبيق

  1. انتقل إلى تطبيقاتي.
  2. حدّد التطبيق المرتبط بحساب واتساب للأعمال الذي تريد تحميله في مدير واتساب.
  3. في القائمة على اليمين، انتقل إلى واتساب > البدء السريع.
  4. انقر على المربع معلومات الحساب في القسم واتساب للأعمال.

عبر عنوان URL

يمكنك الانتقال مباشرةً إلى نظرة عامة على مدير واتساب، والتي تعرض كل حسابات واتساب للأعمال المملوكة لحافظة أعمال محددة أو التي تمت مشاركتها معها، عن طريق زيارة:

https://business.facebook.com/wa/manage/home/

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

بدلاً من ذلك، إذا كان لديك حافظات أعمال متعددة، فيمكنك إلحاق معرف الحساب بنهاية عنوان URL ووضع إشارة مرجعية له لوصول أسهل:

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

لدينا مجموعة Postman لـ API السحابة تحتوي على استفسارات شائعة في مساحة عمل منصة واتساب للأعمال.