التدفقات

شغّل أتمتة منشئ التدفقات لعميل.

التدفقات هي المحادثات التي تبنيها في منشئ التدفقات: الأسئلة والأزرار والانتظار والشروط والتحويل إلى فريقك. تشغّلها الواجهة البرمجية من أنظمتك وتخبرك كيف انتهت، فيستطيع حدثٌ في متجرك أو نظام CRM أن يفتح محادثة حقيقية.

كيف يعمل: التدفقات والأتمتةاجعل التدفق قابلًا للتشغيل · شغّل تدفقًا لعميل · تابع التشغيل · نماذج واتساب (WhatsApp Flows)

اجعل التدفق قابلًا للتشغيل#

في منشئ التدفقات امنح التدفق مشغّل API / ويب هوك ثم انشره. بعدها يعرضه GET /flows?startable_via_api=true مع startable_via_api: true. أما المسودة أو التدفق بمشغّل آخر (كلمة مفتاحية أو محادثة جديدة…) فيرد بـ flow_not_triggerable.

شغّل تدفقًا لعميل#

POST /flows/{id}/runs:

JSON

{
  "to": "+966501234567",
  "variables": { "order_id": "10482", "delivery_date": "الخميس" },
  "reference": "order-10482"
}

تصبح variables متغيرات التشغيل الأولى: يقرؤها التدفق كـ {{order_id}}، إلى جانب ما يعرفه عن جهة الاتصال (الاسم والحقول المخصصة).
reference معرّفك الخاص، يعود في التشغيل وفي كل أحداث flow.run.*.
تتبع أول رسالة في التدفق قواعد واتساب: خارج نافذة الـ24 ساعة يجب أن تكون قالبًا معتمدًا، فابدأ التدفقات الموجهة لعملاء لم يراسلوك مؤخرًا بخطوة قالب.

يبدأ التشغيل فورًا، ويوضح الرد موضعه الحالي (غالبًا waiting_input بانتظار رد العميل).

تابع التشغيل#

يعرض GET /flow_runs/{id} حالة التشغيل state والمتغيرات variables التي جمعها حتى الآن: الإجابات واختيارات الأزرار والقيم الواردة من أنظمتك. ويعرض GET /flows/{id}/runs تشغيلات التدفق حسب الحالة أو العميل.

الحدث	متى
`flow.run.started`	بدأ تشغيل (من الواجهة أو مشغّل أو صندوق الوارد)
`flow.run.handed_off`	حوّل التدفق العميل إلى فريقك
`flow.run.completed`	وصل التشغيل إلى نهايته، وتحمل `variables` كل ما جمعه
`flow.run.expired`	توقف التدفق عن انتظار عميل لم يرد في الوقت المحدد

مثال تكامل شائع: شغّل تدفق تقييم التوصيل من نظام الطلبات، وعند flow.run.completed احفظ التقييم من variables مع الطلب الذي يحدده reference.

نماذج واتساب (WhatsApp Flows)#

نماذج واتساب هي استمارات تُفتح داخل المحادثة: حجز أو تسجيل أو استبيان. يصلك كل إرسال كحدث flow.response يحمل إجابات العميل answers، ويعرضها GET /flow_responses حسب النموذج (whatsapp_flow_id) أو التاريخ.

نقاط الواجهة

getعرض ردود نماذج واتساب/flow_responses
getجلب تشغيل تدفق/flow_runs/{id}
getعرض التدفقات/flows
getجلب تدفق/flows/{id}
getعرض تشغيلات تدفق/flows/{id}/runs
postتشغيل تدفق لعميل/flows/{id}/runs

عرض ردود نماذج واتساب

gethttps://api.saei.automize.sa/v1/flow_responses

الصلاحية: flows:read
لمفاتيح التشغيل فقط

الإجابات التي أرسلها العملاء في نماذج واتساب (Flows) التي تُفتح داخل المحادثة، الأحدث أولًا. يصل كل رد جديد أيضًا كحدث flow.response.

معاملات الاستعلام

limitintegerاختياري
عدد العناصر المطلوبة، من 1 إلى 100.
cursorstringاختياري
قيمة next_cursor من الصفحة السابقة.
whatsapp_flow_idstringاختياري
الردود على هذا النموذج فقط (معرّف النموذج لدى Meta).
sincestringاختياري

حقول الاستجابة200· صفحة من الردود.

object"list"مطلوب
dataarray<FlowResponse>مطلوب
الحقول الفرعية (10)
- idstringمطلوب
- object"flow_response"مطلوب
- whatsapp_flow_idstring | nullاختياري
- flow_namestring | nullاختياري
- customerobjectاختياري
  الحقول الفرعية (2)
  contact_idstring | nullاختياري
  addressstring | nullاختياري
- campaign_idstring | nullاختياري
- template_idstring | nullاختياري
- answersobjectمطلوب
  حقول النموذج وما أدخله العميل، بأسماء الحقول المحددة في نموذج واتساب.
- file_countintegerاختياري
- submitted_atstring | nullاختياري
has_morebooleanمطلوب
next_cursorstring | nullمطلوب

الأخطاء المحتملة3

403test_mode_unsupportedغير متاح في وضع الاختبار
422parameter_invalidحقل غير صالح
429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/flow_responses \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

صفحة من الردود.

{
  "object": "list",
  "data": [
    {
      "id": "fres_77",
      "object": "flow_response",
      "whatsapp_flow_id": "string",
      "flow_name": "string",
      "customer": {
        "contact_id": "string",
        "address": "string"
      },
      "campaign_id": "string",
      "template_id": "string",
      "answers": {},
      "file_count": 0,
      "submitted_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}

جلب تشغيل تدفق

gethttps://api.saei.automize.sa/v1/flow_runs/{id}

الصلاحية: flows:read
لمفاتيح التشغيل فقط

موضع عميل واحد داخل التدفق، والمتغيرات التي جمعها التدفق حتى الآن (الإجابات، الاختيارات، القيم الواردة من أنظمتك).

معاملات المسار

idstringمطلوب
معرّف العنصر.

حقول الاستجابة200· التشغيل.

idstringمطلوب
object"flow_run"مطلوب
flow_idstringمطلوب
customerobjectاختياري
الحقول الفرعية (2)
- contact_idstring | nullاختياري
- addressstring | nullاختياري
channelstringاختياري
statestringمطلوب
waiting_input ينتظر رد العميل، وpaused ينتظر خطوة تأخير، وhanded_off حُوّل إلى فريقك، وexpired توقف عن الانتظار.
إحدى القيمactivewaiting_inputpausedhanded_offcompletedexpired
current_stepstring | nullاختياري
referencestring | nullاختياري
variablesobjectاختياري
started_atstring | nullاختياري
completed_atstring | nullاختياري
updated_atstring | nullاختياري

الأخطاء المحتملة3

403test_mode_unsupportedغير متاح في وضع الاختبار
404resource_missingغير موجود
429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/flow_runs/id_123 \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

التشغيل.

{
  "id": "run_9021",
  "object": "flow_run",
  "flow_id": "string",
  "customer": {
    "contact_id": "string",
    "address": "string"
  },
  "channel": "string",
  "state": "active",
  "current_step": "string",
  "reference": "string",
  "variables": {},
  "started_at": "2026-10-01T09:30:00Z",
  "completed_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

عرض التدفقات

gethttps://api.saei.automize.sa/v1/flows

الصلاحية: flows:read
يعمل في وضع الاختبار

تدفقات الأتمتة المبنية في منشئ التدفقات. يحدّد startable_via_api التدفقات المنشورة ذات المشغّل "API / ويب هوك"، والتي يمكن تشغيلها لعميل عبر POST /v1/flows/{id}/runs.

معاملات الاستعلام

limitintegerاختياري
عدد العناصر المطلوبة، من 1 إلى 100.
cursorstringاختياري
قيمة next_cursor من الصفحة السابقة.
statusstringاختياري
إحدى القيمdraftpublishedarchived
startable_via_apibooleanاختياري
true لعرض التدفقات التي يمكن تشغيلها عبر الواجهة فقط.

حقول الاستجابة200· صفحة من التدفقات.

object"list"مطلوب
dataarray<Flow>مطلوب
الحقول الفرعية (11)
- idstringمطلوب
- object"flow"مطلوب
- namestringمطلوب
- descriptionstring | nullاختياري
- statusstringمطلوب
  إحدى القيمdraftpublishedarchived
- triggerstring | nullاختياري
  ما يبدأ التدفق، مثل webhook أو keyword أو inbound-message أو contact-added.
- startable_via_apibooleanمطلوب
- number_idstring | nullاختياري
- published_atstring | nullاختياري
- created_atstring | nullاختياري
- updated_atstring | nullاختياري
has_morebooleanمطلوب
next_cursorstring | nullمطلوب

الأخطاء المحتملة2

422parameter_invalidحقل غير صالح
429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/flows \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

صفحة من التدفقات.

{
  "object": "list",
  "data": [
    {
      "id": "flow_18",
      "object": "flow",
      "name": "string",
      "description": "string",
      "status": "draft",
      "trigger": "string",
      "startable_via_api": false,
      "number_id": "string",
      "published_at": "2026-10-01T09:30:00Z",
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}

جلب تدفق

gethttps://api.saei.automize.sa/v1/flows/{id}

الصلاحية: flows:read
يعمل في وضع الاختبار

معاملات المسار

idstringمطلوب
معرّف العنصر.

حقول الاستجابة200· التدفق.

idstringمطلوب
object"flow"مطلوب
namestringمطلوب
descriptionstring | nullاختياري
statusstringمطلوب
إحدى القيمdraftpublishedarchived
triggerstring | nullاختياري
ما يبدأ التدفق، مثل webhook أو keyword أو inbound-message أو contact-added.
startable_via_apibooleanمطلوب
number_idstring | nullاختياري
published_atstring | nullاختياري
created_atstring | nullاختياري
updated_atstring | nullاختياري

الأخطاء المحتملة2

404resource_missingغير موجود
429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/flows/flow_18 \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

التدفق.

{
  "id": "flow_18",
  "object": "flow",
  "name": "متابعة بعد الشراء",
  "description": "يسأل العميل عن تجربته بعد 3 أيام من التسليم",
  "status": "published",
  "trigger": "webhook",
  "startable_via_api": true,
  "number_id": "num_3",
  "published_at": "2026-09-01T08:00:00Z",
  "created_at": "2026-08-28T12:00:00Z",
  "updated_at": "2026-09-01T08:00:00Z"
}

عرض تشغيلات تدفق

gethttps://api.saei.automize.sa/v1/flows/{id}/runs

الصلاحية: flows:read
لمفاتيح التشغيل فقط

معاملات المسار

idstringمطلوب
معرّف العنصر.

معاملات الاستعلام

limitintegerاختياري
عدد العناصر المطلوبة، من 1 إلى 100.
cursorstringاختياري
قيمة next_cursor من الصفحة السابقة.
statestringاختياري
إحدى القيمactivewaiting_inputpausedhanded_offcompletedexpired
tostringاختياري
تشغيلات هذا العميل فقط (الهاتف بأي صيغة).

حقول الاستجابة200· صفحة من التشغيلات.

object"list"مطلوب
dataarray<FlowRun>مطلوب
الحقول الفرعية (12)
- idstringمطلوب
- object"flow_run"مطلوب
- flow_idstringمطلوب
- customerobjectاختياري
  الحقول الفرعية (2)
  contact_idstring | nullاختياري
  addressstring | nullاختياري
- channelstringاختياري
- statestringمطلوب
  waiting_input ينتظر رد العميل، وpaused ينتظر خطوة تأخير، وhanded_off حُوّل إلى فريقك، وexpired توقف عن الانتظار.
  إحدى القيمactivewaiting_inputpausedhanded_offcompletedexpired
- current_stepstring | nullاختياري
- referencestring | nullاختياري
- variablesobjectاختياري
- started_atstring | nullاختياري
- completed_atstring | nullاختياري
- updated_atstring | nullاختياري
has_morebooleanمطلوب
next_cursorstring | nullمطلوب

الأخطاء المحتملة4

403test_mode_unsupportedغير متاح في وضع الاختبار
422parameter_invalidحقل غير صالح
404resource_missingغير موجود
429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/flows/flow_18/runs \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

صفحة من التشغيلات.

{
  "object": "list",
  "data": [
    {
      "id": "run_9021",
      "object": "flow_run",
      "flow_id": "string",
      "customer": {
        "contact_id": "string",
        "address": "string"
      },
      "channel": "string",
      "state": "active",
      "current_step": "string",
      "reference": "string",
      "variables": {},
      "started_at": "2026-10-01T09:30:00Z",
      "completed_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}

تشغيل تدفق لعميل

posthttps://api.saei.automize.sa/v1/flows/{id}/runs

الصلاحية: flows:trigger
لمفاتيح التشغيل فقط
يقبل Idempotency-Key

يشغّل التدفق لعميل واحد الآن تمامًا كما يفعل مشغّل "API / ويب هوك": الخطوات والرسائل والانتظار والتحويل نفسها. تصبح variables متغيرات التشغيل الأولى (يقرؤها التدفق كـ {{name}})، إلى جانب ما يعرفه عن جهة الاتصال. يُؤخذ العميل من to فقط: المفاتيح contact_id وcontact_phone وphone وphone_number وcustomer وكل مفتاح يبدأ بـ _ محجوزة وتُرفض. وreference معرّفك الخاص، يُعاد في التشغيل وفي كل أحداث flow.run.*.

يجب أن يكون التدفق منشورًا ومشغّله "API / ويب هوك" (startable_via_api: true). تتبع أول رسالة فيه قواعد واتساب: خارج نافذة الـ24 ساعة يعني ذلك قالبًا معتمدًا.

معاملات المسار

idstringمطلوب
معرّف العنصر.

الترويسات

Idempotency-Keystringاختياري
أي نص فريد (يُفضّل UUID). إعادة الطلب بنفس المفتاح ونفس الجسم تُرجع الاستجابة الأولى بدل التنفيذ مرتين. يُحفظ لمدة 24 ساعة.

جسم الطلب

tostringمطلوب
هاتف العميل بأي صيغة.
variablesobjectاختياري
referencestringاختياري

حقول الاستجابة201· التشغيل وقد بدأ بالفعل.

idstringمطلوب
object"flow_run"مطلوب
flow_idstringمطلوب
customerobjectاختياري
الحقول الفرعية (2)
- contact_idstring | nullاختياري
- addressstring | nullاختياري
channelstringاختياري
statestringمطلوب
waiting_input ينتظر رد العميل، وpaused ينتظر خطوة تأخير، وhanded_off حُوّل إلى فريقك، وexpired توقف عن الانتظار.
إحدى القيمactivewaiting_inputpausedhanded_offcompletedexpired
current_stepstring | nullاختياري
referencestring | nullاختياري
variablesobjectاختياري
started_atstring | nullاختياري
completed_atstring | nullاختياري
updated_atstring | nullاختياري

الأخطاء المحتملة6

403test_mode_unsupportedغير متاح في وضع الاختبار
422parameter_missingحقل مفقود
422parameter_invalidحقل غير صالح
404resource_missingغير موجود
422flow_not_triggerableلا يمكن تشغيل التدفق
429rate_limitedطلبات كثيرة

جرّبها

curl -X POST https://api.saei.automize.sa/v1/flows/flow_18/runs \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+966501234567",
  "variables": {
    "order_id": "10482",
    "delivery_date": "الخميس"
  },
  "reference": "order-10482"
}'

الاستجابة

التشغيل وقد بدأ بالفعل.

{
  "id": "run_9021",
  "object": "flow_run",
  "flow_id": "flow_18",
  "customer": {
    "contact_id": "ct_1052",
    "address": "+966501234567"
  },
  "channel": "whatsapp",
  "state": "waiting_input",
  "current_step": "node_ask_rating",
  "reference": "order-10482",
  "variables": {
    "order_id": "10482",
    "delivery_date": "الخميس",
    "first_name": "سارة",
    "reference": "order-10482"
  },
  "started_at": "2026-10-01T10:00:00Z",
  "completed_at": null,
  "updated_at": "2026-10-01T10:00:01Z"
}

اجعل التدفق قابلًا للتشغيل#

شغّل تدفقًا لعميل#

تابع التشغيل#

نماذج واتساب (WhatsApp Flows)#

نقاط الواجهة

عرض ردود نماذج واتساب#

معاملات الاستعلام

جلب تشغيل تدفق#

معاملات المسار

عرض التدفقات#

معاملات الاستعلام

جلب تدفق#

معاملات المسار

عرض تشغيلات تدفق#

معاملات المسار

معاملات الاستعلام

تشغيل تدفق لعميل#

معاملات المسار

الترويسات

جسم الطلب

عرض ردود نماذج واتساب

جلب تشغيل تدفق

عرض التدفقات

جلب تدفق

عرض تشغيلات تدفق

تشغيل تدفق لعميل