Flow JSON

Flow JSON هو الصيغة التي تستخدمها Meta لوصف WhatsApp Flow: ما الشاشات التي يتضمنها، وما الحقول والنصوص التي تظهر فيها، وما وظيفة كل زر. يقرأ WhatsApp هذا الوصف ويعرض النموذج داخل المحادثة.

ما هو Flow JSON؟

خلف كل WhatsApp Flow وصف بصيغة JSON يُسمّى Flow JSON. يحدد هذا الوصف شاشات الـFlow، والمكوّنات الموجودة في كل منها، وما يحدث عند النقر على زر: الانتقال إلى الشاشة التالية، أو إرسال البيانات إلى خادم، أو إكمال الـFlow. ومن هذه المكوّنات العناوين والنصوص وحقول الإدخال وقوائم الاختيار ومنتقي التاريخ ومربعات الـopt-in ورفع الصور أو المستندات.

أهم الأجزاء في المستوى الأعلى:

• version: إصدار الصيغة، وهو الذي يحدد المكوّنات المتاحة.
• screens: قائمة الشاشات ومكوّناتها.
• routing_model: المسارات المسموح بها بين الشاشات، وهو إلزامي في الـFlows التي تستخدم نقطة نهاية للبيانات.
• data_api_version: إصدار واجهة البيانات، وهو أيضًا للـFlows التي تستخدم نقطة نهاية فقط.

مثال: Flow من شاشة واحدة

يصف Flow JSON التالي طلب معاودة اتصال: شاشة واحدة فيها حقل إلزامي لرقم الهاتف، وزر التذييل يُكمل الـFlow ويعيد القيمة المُدخلة:

{
  "version": "7.3",
  "screens": [
    {
      "id": "CALLBACK",
      "title": "معاودة الاتصال",
      "terminal": true,
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextInput",
            "name": "phone",
            "label": "رقم الهاتف",
            "input-type": "phone",
            "required": true
          },
          {
            "type": "Footer",
            "label": "إرسال",
            "on-click-action": {
              "name": "complete",
              "payload": { "phone": "${form.phone}" }
            }
          }
        ]
      }
    }
  ]
}

يتضمن الـFlow الحقيقي عادةً عدة شاشات وحقول اختيار ومربع موافقة. لكن المبدأ يبقى نفسه: كل شاشة عنصر في screens، وكل زر يحمل إجراءً.

الإصدارات والحدود

تواصل Meta تطوير الصيغة، وتأتي المكوّنات الجديدة مع الإصدارات الجديدة. فرفع الصور والمستندات مثلًا يتطلب الإصدار 4.0 أو أحدث، والنص المنسّق يتطلب الإصدار 5.1. وتُجمَّد الإصدارات القديمة في مرحلة ما: فلا يمكن نشر الـFlows المبنية عليها أو تحديثها، لكن يظل بالإمكان إرسالها. وعند انتهاء صلاحية إصدار ما، لا يعود بمقدور العملاء فتح الـFlows المبنية عليه.

وهناك أيضًا حدود ثابتة: لا يتجاوز حجم ملف Flow JSON عشرة ميغابايت (10 MB)، ولا يتجاوز نموذج التوجيه 10 فروع، ولكل شاشة حدود قصوى، مثل 50 مكوّنًا وتذييل واحد يحمل الزر.

Flow JSON وأدوات البناء والرسائل

• Flow JSON يصف النموذج نفسه وبنيته ومنطقه.
• أداة البناء المرئية تولّد هذا الـJSON حتى لا يضطر أحد إلى كتابته يدويًا.
• الرسالة التي توصل الـFlow شيء آخر: رسالة تفاعلية أو قالب يحتوي على زر Flow يشير فقط إلى الـFlow المنشور.

كما أن Flow JSON ليس هو نفسه الأتمتة في Flow Builder؛ فهذه تصف خطوات تعمل في الخلفية، لا نموذجًا داخل المحادثة.

لماذا يهم Flow JSON

• معرفة الحدود: إذا كنت تعرف ما تسمح به الصيغة، فلن تخطط لنماذج سترفضها Meta لاحقًا.
• تشخيص المشكلات: عندما ترفض Meta أحد الـFlows، يكون السبب غالبًا في الـJSON، مثل مكوّن لا يدعمه الإصدار المختار بعد.
• متابعة الإصدارات: عندما تجمّد Meta إصدارًا ما، تحتاج الـFlows المبنية عليه إلى إصدار أحدث قبل تعديلها التالي.

Flow JSON في SendSeven

في منشئ WhatsApp Flows لدى SendSeven (تجريبي) لا تكتب Flow JSON يدويًا. تبني الـFlow في محرر مرئي، ويولّد SendSeven ملف Flow JSON بالإصدار 7.3، وهو الإصدار الذي توصي به Meta حاليًا. ويعرض تبويب JSON نسختين: Builder JSON الذي يمكنك تعديله، وWhatsApp JSON المولَّد منه، وهو للقراءة فقط. كما تقبل واجهة الـAPI صيغة Builder JSON.

لا تلصق Flow JSON جاهزًا من مصادر أخرى، لكن يمكنك استيراد الـFlows التي بنيتها في منشئ Meta نفسه. ويُحدَّد في المنشئ ما إذا كان الـFlow يحتاج إلى نقطة نهاية للبيانات: الـFlows الثابتة متاحة ابتداءً من باقة Basic، والديناميكية ابتداءً من باقة Scale.

WhatsApp Flows في المرحلة التجريبية. وتجد تكلفة الـFlow المُرسَل والـFlow المكتمل في مدخل WhatsApp Flows.

متوافق مع اللائحة العامة لحماية البيانات (GDPR)، مستضاف داخل الاتحاد الأوروبي. جرّبه مجانًا 14 يومًا.