# التدفقات

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

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

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

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

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

[`POST /flows/{id}/runs`](/docs/reference/flows#startFlowRun):

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

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

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

## تابع التشغيل {#runs}

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

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

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

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

نماذج واتساب هي استمارات تُفتح داخل المحادثة: حجز أو تسجيل أو استبيان. يصلك كل إرسال كحدث [`flow.response`](/docs/events#flow-response) يحمل إجابات العميل `answers`، ويعرضها [`GET /flow_responses`](/docs/reference/flows#listFlowResponses) حسب النموذج (`whatsapp_flow_id`) أو التاريخ.

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

```
GET https://api.saei.automize.sa/v1/flow_responses
```

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

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

### المعاملات

- `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100.
- `cursor` (query): قيمة `next_cursor` من الصفحة السابقة.
- `whatsapp_flow_id` (query): الردود على هذا النموذج فقط (معرّف النموذج لدى Meta).
- `since` (query): 

### الاستجابة 200

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

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

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

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`parameter_invalid`, `test_mode_unsupported`, `rate_limited`

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

```
GET https://api.saei.automize.sa/v1/flow_runs/{id}
```

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

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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

التشغيل.

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

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

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`resource_missing`, `test_mode_unsupported`, `rate_limited`

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

```
GET https://api.saei.automize.sa/v1/flows
```

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

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

### المعاملات

- `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100.
- `cursor` (query): قيمة `next_cursor` من الصفحة السابقة.
- `status` (query): 
- `startable_via_api` (query): `true` لعرض التدفقات التي يمكن تشغيلها عبر الواجهة فقط.

### الاستجابة 200

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

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

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

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`parameter_invalid`, `rate_limited`

## جلب تدفق

```
GET https://api.saei.automize.sa/v1/flows/{id}
```



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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

التدفق.

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

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

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`resource_missing`, `rate_limited`

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

```
GET https://api.saei.automize.sa/v1/flows/{id}/runs
```



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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.
- `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100.
- `cursor` (query): قيمة `next_cursor` من الصفحة السابقة.
- `state` (query): 
- `to` (query): تشغيلات هذا العميل فقط (الهاتف بأي صيغة).

### الاستجابة 200

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

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

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

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`resource_missing`, `parameter_invalid`, `test_mode_unsupported`, `rate_limited`

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

```
POST https://api.saei.automize.sa/v1/flows/{id}/runs
```

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

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


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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.
- `Idempotency-Key` (header): أي نص فريد (يُفضّل UUID). إعادة الطلب بنفس المفتاح ونفس الجسم تُرجع الاستجابة الأولى بدل التنفيذ مرتين. يُحفظ لمدة 24 ساعة.

### الطلب

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

### الاستجابة 201

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

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

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

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`parameter_missing`, `parameter_invalid`, `resource_missing`, `flow_not_triggerable`, `test_mode_unsupported`, `rate_limited`