# واجهة برمجة تطبيقات الأتمتة (Automations API)

الأتمتة هي سير عمل يتكون من خطوات: مشغل واحد أو أكثر لبدئها، ثم إجراءات، وشروط، وتأخيرات، وخطوات ذكاء اصطناعي، وبقية العناصر المتصلة في رسم بياني. إنها نفس الأتمتة التي تراها وتعدلها في صفحة [الأتمتة](../automations/automations.md). يغطي هذا الدليل كيفية قراءتها وبنائها عبر واجهة برمجة التطبيقات.

- **عنوان URL الأساسي**: `https://api.dmchamp.com/v1`
- **المصادقة**: مفتاح API الخاص بك (راجع [المصادقة](authentication.md))
- **الحقول والهيئات**: كل معلمة وحقل استجابة موجود في [مرجع API](reference.md#tag/automations)
- **الأخطاء**: راجع [الأخطاء والترقيم](errors-and-pagination.md) و[الأخطاء](#errors) أدناه

> **الوكالات:** تقبل كل نقطة نهاية في هذه الصفحة `sub_account_id` كمعامل استعلام، بحيث يمكنك قراءة وبناء أتمتة العميل باستخدام مفتاح الوكالة الخاص بك. أي `sub_account_id` ليس أحد حسابات عملائك سيعيد `404`. انظر [واجهة برمجة التطبيقات للوكالات](../agency/api-for-agencies.md).

---

## كيف يعمل: المسودة أولاً

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

1. **اقرأ الكتالوج.** يسرد `GET /automations/steps` كل مشغل وإجراء ونوع خطوة يمكنك استخدامه، بالإضافة إلى قواعد كتابة الرسم البياني (`graph_rules`).
2. **أنشئ مسودة.** يخزن `POST /automations` الأتمتة وهي **متوقفة**. لا شيء يعمل بعد.
3. **تحقق منها.** اقرأها مرة أخرى، وافتحها في أداة البناء (تمنحك الاستجابة `open_path` الخاص بها)، وتأكد من أن الشخص الذي يملك الحساب قد رأى ما تفعله ولمن.
4. **شغّلها.** `POST /automations/{automationId}/enable` هو استدعاء خاص به. هذه هي الخطوة التي تجعل الأشياء الحقيقية تحدث: إرسال الرسائل، تغيير السجلات، وتوفير الأدوات لوكيل الذكاء الاصطناعي.

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

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

### الوصول

- يحتاج الحساب إلى ميزة الأتمتة. بدونها، سيعيد كل استدعاء في هذه الصفحة `403`.
- يتبع وصول عضو الفريق منطقة **الأتمتة** الخاصة به في [إدارة الفريق](../settings/team-management.md): القراءة (القائمة، الحصول على، الخطوات، التشغيلات، المجلدات) تتطلب **عرض**، وكل ما يغير شيئاً يتطلب **تعديل**.
- في حساب العميل الذي تستثني خطته إنشاء وتعديل الأتمتة، ستعيد استدعاءات الكتابة `403`، تماماً كما تفعل أداة البناء في التطبيق.

---

## نقاط النهاية

| المهمة | الطريقة + المسار | المستكشف |
|---|---|---|
| سرد الأتمتة | `GET /automations` | [فتح في مرجع API](reference.md#tag/automations/GET/automations) |
| الحصول على أتمتة مع الرسم البياني الخاص بها | `GET /automations/{automationId}` | [فتح في مرجع API](reference.md#tag/automations/GET/automations/{automationId}) |
| قراءة كتالوج الخطوات | `GET /automations/steps` | [فتح في مرجع API](reference.md#tag/automations/GET/automations/steps) |
| إنشاء أتمتة (مسودة) | `POST /automations` | [فتح في مرجع API](reference.md#tag/automations/POST/automations) |
| تحديث أتمتة | `PUT /automations/{automationId}` | [فتح في مرجع API](reference.md#tag/automations/PUT/automations/{automationId}) |
| تشغيلها | `POST /automations/{automationId}/enable` | [فتح في مرجع API](reference.md#tag/automations/POST/automations/{automationId}/enable) |
| إيقافها | `POST /automations/{automationId}/disable` | [فتح في مرجع API](reference.md#tag/automations/POST/automations/{automationId}/disable) |
| قراءة سجل التشغيل | `GET /automations/{automationId}/runs` | [فتح في مرجع API](reference.md#tag/automations/GET/automations/{automationId}/runs) |
| سرد المجلدات | `GET /automations/folders` | [فتح في مرجع API](reference.md#tag/automations/GET/automations/folders) |
| إنشاء مجلد | `POST /automations/folders` | [فتح في مرجع API](reference.md#tag/automations/POST/automations/folders) |
| إعادة تسمية مجلد | `PUT /automations/folders/{folderId}` | [فتح في مرجع API](reference.md#tag/automations/PUT/automations/folders/{folderId}) |
| حذف مجلد | `DELETE /automations/folders/{folderId}` | [فتح في مرجع API](reference.md#tag/automations/DELETE/automations/folders/{folderId}) |
| نقل أتمتة إلى مجلد | `PUT /automations/{automationId}/folder` | [فتح في مرجع API](reference.md#tag/automations/PUT/automations/{automationId}/folder) |

---

## قراءة الأتمتة

تُرجع `GET /automations` ملخصات (بدون خطوات)، مع عرض الأحدث تغييرًا أولاً؛ تسرد `folder_id=none` تلك الموجودة خارج أي مجلد. تضيف `GET /automations/{automationId}` الـ `graph` الكامل: كل خطوة (`nodes[]`) مع `kind`، و`label`، و`alias`، و`action`، و`params`، و`config` الخاص بها، والاتصالات (`edges[]`) مع `from`، و`to`، وبعد شرط أو ما شابه، `branch`.

```bash
curl "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f?apiKey=YOUR_API_KEY"
```

**من الجيد معرفة ذلك**

- **`alias` هي الطريقة التي تقرأ بها الخطوات اللاحقة مخرجات خطوة ما**، كـ `${nodes.<alias>.<field>}`. الخطوة التي لا تحتوي على مخرجات يُشار إليها بمعرفها (id).
- يتم الاحتفاظ بـ `params` للقراء القدامى؛ تحمل `config` نفس القيم وأكثر (قواعد الشرط، ومطالبة خطوة الذكاء الاصطناعي، ومدة التأخير، واسم الإجراء ومعلماته).
- **الأسرار مخفية.** القيم التي تبدو كبيانات اعتماد (أسرار خطاف الويب، والرموز المميزة، ومفاتيح API، وكلمات المرور، وقيم الرأس) تعود كـ `"[redacted]"`. أرسل `"[redacted]"` مرة أخرى دون تغيير وسيتم الاحتفاظ بالقيمة المخزنة.
- **النصوص الطويلة يتم اختصارها.** يتم قطع النص الواحد الذي يزيد طوله عن 4000 حرف تقريبًا وينتهي بعلامة حذف. إذا أعدت إرسال تلك الخطوة، ضع نصها الكامل أولاً.
- إذا تعذر الوصول إلى خدمة الأتمتة، ستحصل على `503`، وليس قائمة فارغة. القائمة الفارغة تعني دائمًا عدم وجود أتمتة.

### كتالوج الخطوات

تُرجع `GET /automations/steps` كل ما يمكن بناء أتمتة منه: الـ 8 `node_kinds`، وكل مشغل مع إعداداته `fields` و`output_keys`، و`actions` المضمنة مع معاملاتها، و`api_actions` (عمليات واجهة برمجة التطبيقات هذه التي يمكن لخطوة الإجراء استدعاؤها)، وقواعد `graph_rules`، و`counts`. هذا ما **يقدمه** المنشئ، وليس ما بناه الحساب: تحقق من ذلك قبل أن تستنتج أن مشغلًا أو إجراءً ما غير موجود.

- بدون `q`، تعود مئات إجراءات API كتسميات مجمعة حسب المنطقة في `api_actions_by_tag` وتكون القائمة المسطحة فارغة.
- مع `q` (كلمة غير حساسة لحالة الأحرف)، تكون `api_actions` هي القائمة المسطحة للمطابقات، بحد أقصى 60 (تخبرك `api_actions_truncated` متى). يتم البحث أيضًا في إجراءات تطبيقات الطرف الثالث المتصلة وتعود في `app_actions`: ابحث باسم التطبيق، على سبيل المثال `q=hubspot`. يوضح كل منها ما إذا كان الحساب يمتلك ذلك التطبيق `connected`، وتسرد `connected_apps` التطبيقات المتصلة. تكون `app_actions_unavailable` هي `true` عندما يتعذر البحث في إجراءات التطبيق هذه المرة؛ تظل القوائم الأخرى كاملة.

---

## الإنشاء والتحرير

### إنشاء مسودة

```bash
curl -X POST "https://api.dmchamp.com/v1/automations?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Price question auto-reply",
    "description": "Replies with the price list when someone asks about prices.",
    "graph": {
      "nodes": [
        { "id": "trigger_1", "type": "trigger", "label": "Incoming message",
          "data": { "trigger": { "kind": "incoming_message", "message_filter_contains": "price" } } },
        { "id": "send_prices", "type": "action", "label": "Send message",
          "data": { "action": { "provider": "native", "slug": "SEND_MESSAGE",
            "params": { "contact_id": "${trigger.contact.id}", "body": "Hi ${trigger.contact.first_name}, here is our price list: https://example.com/prices" } } } }
      ],
      "edges": [{ "source": "trigger_1", "target": "send_prices" }]
    }
  }'
```

```json
{ "success": true, "automation": { "id": "8d2c7f1e-…", "enabled": false, "…": "…" }, "draft": true, "open_path": "/automations/8d2c7f1e-…", "warnings": [] }
```

تعتبر `draft: true` و`enabled: false` طبيعية، وليست فشلًا: الأتمتة الجديدة تكون دائمًا مسودة حتى تقوم بتمكينها. تسرد `warnings` ما لم يتمكن المنشئ من إنهائه، كتسميات قصيرة (على سبيل المثال `agent_function:not_linked`).

**كتابة الرسم البياني.** `graph_rules` من الكتالوج هي القواعد الكاملة. باختصار:

- كل عقدة لها `id` (فريد في الرسم البياني)، و`type` (واحد من 8 [أنواع خطوات](#step-kinds))، و`label` اختياري، وإعداداتها في `data` تحت مفتاح مسمى باسم نوعها (`data.trigger`، `data.action`، `data.condition`، `data.delay`، `data.ai`، `data.loop`، `data.transform`، `data.respond`).
- تحتاج الأتمتة إلى مشغل واحد على الأقل. تسمح القواعد الحية بما يصل إلى 10، وتبدأ الأتمتة عند إطلاق أي منها.
- يجب أن تكون كل خطوة أخرى قابلة للوصول من مشغل، ولا يجوز لأي اتصال أن يؤدي إلى خطوة سابقة.
- الحواف الخارجة من شرط تحمل `sourceHandle` `true` أو `false`؛ حلقة `body` أو `done`؛ تأخير انتظار الرد `replied` أو `timed_out`. الحواف الأخرى لا تحمل شيئًا.
- تأتي أسماء الإجراءات ومعلماتها من الكتالوج. **لا تخمن المعرف أبدًا** (وكيل، علامة، قائمة، مرحلة): ابحث عنه باستخدام API أولاً، أو اترك الحقل كـ `""` ليختار الشخص في المنشئ.
- المواضع اختيارية؛ الخطوات التي لا تحتوي على موضع يتم ترتيبها تلقائيًا.
- تُكتب القيم من الخطوات السابقة كـ `${trigger.<field>}` و`${nodes.<step>.<field>}`. راجع [استخدام ما أعادته خطوة سابقة](../automations/automations.md#using-what-an-earlier-step-returned) و[التعبيرات](../automations/automations.md#expressions).
- يتم قبول الرسم البياني بطريقتين للكتابة: طريقة المنشئ الخاصة (أعلاه) والطريقة التي تجيب بها القراءة (`kind`، `config`، `from`، `to`، `branch`). لذا يمكنك قراءة أتمتة، وتغيير خطوة، وإرسالها مرة أخرى.
- **لا يُنصح بتكرار الإنشاء بشكل أعمى.** إذا انتهت مهلة الطلب، اسرد الأتمتة الخاصة بك قبل إرساله مرة أخرى، وإلا فقد ينتهي بك الأمر بمسودتين.

### تحديث

`PUT /automations/{automationId}` تغير `name`، و/أو `description` و/أو `graph` (واحدة على الأقل، أو `400`). يستبدل `graph` الرسم البياني **بالكامل**، لذا اعمل دائمًا بناءً على ما هو مخزن: اقرأه، وقم بتغيير ما تحتاجه، ثم أرسل الرسم البياني بالكامل مرة أخرى.

```bash
curl -X PUT "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Price question auto-reply (EN)" }'
```

- **احتفظ بكل `alias` للخطوة تمامًا كما حصلت عليه.** إذا قمت بتغييره أو حذفه، فسيظهر كل مرجع لتلك الخطوة فارغًا. راجع [تسمية خطواتك](../automations/automations.md#naming-your-steps).
- **اترك قيم `"[redacted]"` كما هي**، و**استعد النصوص المختصرة** (النص الذي ينتهي بنقاط حذف تم اقتطاعه في القراءة).
- لا يتم تغيير حالة تشغيل الأتمتة هنا أبدًا. إذا كانت قيد التشغيل، فسيصبح تعديلك مباشرًا بمجرد حفظه. أثناء تشغيلها، يتم رفض أي تغيير قد يجعلها تحفز نفسها: قم بإيقاف تشغيلها أولاً.

### التمكين والتعطيل

`POST /automations/{automationId}/enable` تقوم بتشغيل الأتمتة، بحيث تعمل بناءً على محفزها من الآن فصاعدًا. لا تستدعِ هذا الأمر إلا بعد أن يرى الشخص مالك الحساب ما تفعله الأتمتة ولمن، وبعد موافقته. يرفض المنشئ تشغيل رسم بياني لا يمكنه العمل (لا يوجد محفز، أو حلقة، أو خطوة تحفز نفسها) مع `400` يوضح السبب.

```bash
curl -X POST "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/enable?apiKey=YOUR_API_KEY"
```

`POST /automations/{automationId}/disable` تقوم بإيقافها مؤقتًا: تكتمل عمليات التشغيل الجارية بالفعل، ولا تبدأ أي عمليات تشغيل جديدة. التعطيل مسموح به دائمًا. لا يتطلب أي من الاستدعاءين نصًا أساسيًا (body).

---

## سجل التشغيل

`GET /automations/{automationId}/runs` تعيد عمليات التشغيل لأتمتة واحدة، الأحدث أولاً (`limit` من 1 إلى 50، الافتراضي 10): متى بدأت وانتهت كل منها، وما الذي أطلقها، وما إذا كانت ناجحة، والخطأ عند فشلها. قراءة الأتمتة تخبرك بما **ستفعله**؛ وسجل التشغيل يخبرك بما **فعلته**، وهي الطريقة الوحيدة للتمييز بين أتمتة لم تعمل أبدًا وأخرى تعمل وتفشل في كل مرة.

```bash
curl "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/runs?apiKey=YOUR_API_KEY&limit=20"
```

- `mode` هي `live` للتشغيل الحقيقي، أو `safe` لـ **تشغيل آمن** من المحرر. لا يرسل التشغيل الآمن أي شيء، لذا فهو ليس دليلاً على أن الأتمتة تعمل في الاستخدام الحقيقي.
- قائمة `runs` فارغة هي إجابة، وليست فجوة. تحمل الاستجابة حينها `note`: إما أن المحفز لم يعمل أبدًا، أو أن الأتمتة معطلة.

---

## المجلدات

تعمل المجلدات فقط على تجميع الأتمتة في القائمة. وهي لا تغير أبداً ما تفعله الأتمتة أو ما إذا كانت قيد التشغيل. راجع [تنظيم الأتمتة في مجلدات](../automations/automations.md#organizing-automations-in-folders).

```bash
curl -X PUT "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/folder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folder_id": "f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708" }'
```

- سرد المجلدات يعيد أيضًا `unfiled_count`، وعدد الأتمتات الموجودة خارج أي مجلد.
- اسم المجلد مطلوب، بحد أقصى 100 حرف، ويجب أن يكون فريدًا في الحساب (`409`، `code: "folder_name_taken"`). يمكنك أيضًا تصنيف أتمتة عن طريق تمرير `folder_id` عند إنشائها.
- إعادة التسمية تترك الأتمتات في أماكنها.
- **حذف مجلد يحذف المجلد فقط.** تنتقل أتمتاته لتصبح بلا مجلد وتستمر في العمل تمامًا كما كانت من قبل؛ توضح الاستجابة عدد الأتمتات التي تم نقلها (`moved_to_no_folder`).
- عند النقل، `folder_id` مطلوب؛ أرسل `null` لإخراج الأتمتة من مجلدها.

---

## الكتالوج

### أنواع الخطوات

| النوع | ماذا يفعل |
|---|---|
| `trigger` | يبدأ الأتمتة عند حدوث شيء ما. |
| `action` | ينفذ خطوة واحدة: إجراء مدمج، أو إجراء API، أو إجراء تطبيق متصل، أو طلب HTTP، أو بريد إلكتروني. |
| `condition` | يقسم التدفق بناءً على قاعدة، إلى فرع `true` وفرع `false`. |
| `transform` | يشغل جزءاً قصيراً من الكود لإعادة تشكيل البيانات بين الخطوات. |
| `ai` | يسأل الذكاء الاصطناعي باستخدام مطالبة تكتبها أنت. يمكنه إرجاع نص، أو حقول منفصلة، أو اختيار أحد الفروع المتعددة. |
| `delay` | ينتظر لفترة زمنية محددة، أو ينتظر رد جهة الاتصال (مع مهلة زمنية). |
| `loop` | يكرر الخطوات الموجودة بداخله لكل عنصر في قائمة. |
| `respond` | يُرجع استجابة لطلب webhook أو استدعاء دالة وكيل الذكاء الاصطناعي الذي بدأ التشغيل. |

### المشغلات

هذه هي المشغلات الأربعون التي يسردها الكتالوج اليوم، مجمعة كما يصنفها المنشئ. يحتوي عمود **الإعدادات** على مفاتيح إعدادات المشغل الخاصة (`fields`)، والتي تضيق نطاق وقت تفعيله. يأخذ كل مشغل أيضاً `respect_quiet_hours` و `run_hours` و `reentry` و `stop_on_response`؛ راجع [إعدادات الأتمتة](../automations/automations.md#automation-settings).

**المراسلة**

| المشغل (`kind`) | يتم تفعيله عند | الإعدادات |
|---|---|---|
| رسالة واردة (`incoming_message`) | ترسل جهة اتصال رسالة على أي قناة. | `campaign` (يقتصر على وكيل ذكاء اصطناعي واحد)، `channel`، `message_filter_contains` (كلمة مفتاحية)، `message_filter_regex` (نمط) |
| مكالمة فائتة (`missed_call`) | يتصل شخص ما بأحد أرقام WhatsApp Web الخاصة بك أو رقم SMS الخاص بك ولا يرد أحد. | `to_number` |
| تم تسليم الرسالة (`message_delivered`) | يتم تأكيد تسليم رسالة أرسلتها بواسطة القناة. | `channel`، `agent` |
| فشل تسليم الرسالة (`message_failed`) | تعذر تسليم رسالة أرسلتها، مع ذكر الخطأ. | `channel`، `agent` |
| تم إرسال الرسالة (`message_sent`) | أي رسالة تغادر حسابك: رسالة الذكاء الاصطناعي، أو رسالتك، أو بث، أو متابعة. قم بتصفيتها، وإلا فسيتم تشغيلها على جميع الرسائل. | `channel`، `sent_by` |
| تم إرسال متابعة (`follow_up_sent`) | يتم إرسال متابعة تلقائية. | لا يوجد |
| تم تخطي المتابعة (`follow_up_skipped`) | تم حجب المتابعة لأن شرط إرسالها فشل. | لا يوجد |
| انتهت المتابعات (`follow_up_exhausted`) | حصلت جهة الاتصال على آخر متابعة في التسلسل ولم يعد هناك أي شيء في قائمة الانتظار. | لا يوجد |
| إغلاق المحادثة (`conversation_closed`) | يتم إغلاق المحادثة، مع توضيح كيفية انتهائها وملخص لها. | `channel`، `agent` |
| انتهى البث (`broadcast_completed`) | انتهى البث من الإرسال، مع توضيح عدد الرسائل التي تم إرسالها وعدد التي فشلت. | لا يوجد |
| تم فرز رد العميل المحتمل (`outreach_reply_labelled`) | يتم فرز رد عميل محتمل عبر البريد الإلكتروني البارد، على سبيل المثال كـ "مهتم". | `label` |
| تم استلام تعليق Skool (`skool_comment_received`) | يعلق عضو أسفل منشور Skool تراقبه إحدى قواعد التعليقات الخاصة بك. | لا يوجد |

**جهات الاتصال**

| المشغل (`kind`) | يتم تفعيله عند | الإعدادات |
|---|---|---|
| جهة اتصال جديدة (`contact_created`) | يصل إليك شخص جديد لأول مرة على أي قناة، وكذلك بالنسبة للاستيراد، وAPI، وجهات الاتصال التي تنشئها يدوياً. | لا يوجد |
| تم تحديث جهة الاتصال (`contact_updated`) | يتغير حقل جهة الاتصال. | `field` |
| جهات الاتصال التي تضيفها هنا (`contact_added`) | فقط لجهات الاتصال التي تضعها في هذه الأتمتة بنفسك من صفحة جهات الاتصال. تشغيل واحد لكل جهة اتصال. | لا يوجد |
| تم تطبيق وسم (`tag_applied`) | تتم إضافة وسم إلى جهة اتصال، بواسطة وكيل الذكاء الاصطناعي الخاص بك، أو شخص، أو أتمتة، أو استيراد. | `tag_name`، `channel`، `applied_by` |
| تمت إزالة وسم (`tag_removed`) | تتم إزالة وسم من جهة اتصال. | `tag_name`، `channel` |
| انضم عضو Skool (`skool_member_joined`) | ينضم شخص ما إلى مجتمع Skool الذي تمتلكه أو تديره، مع ملفه الشخصي وإجاباته ودرجة ملاءمته. | `group_id`، `create_contact` |
| تأهل عضو Skool (`skool_member_qualified`) | إجابات عضو Skool الجديد تسجل درجة تساوي أو تتجاوز الحد الأدنى الخاص بك. | `min_score` |

**الصفقات**

| المشغل (`kind`) | يتم تفعيله عند | الإعدادات |
|---|---|---|
| تم إنشاء صفقة (`deal_created`) | تتم إضافة صفقة جديدة إلى إحدى خطوط أنابيب المبيعات الخاصة بك. | `pipeline_id`، `stage_id` |
| تغيرت مرحلة الصفقة (`deal_stage_changed`) | تنتقل صفقة إلى مرحلة مختلفة، مع تسمية المرحلة التي غادرتها والمرحلة التي دخلتها. | `pipeline_id`، `to_stage_id`، `from_stage_id` |
| تم تحديث صفقة (`deal_updated`) | يتغير حقل الصفقة. | `field` |

**المواعيد**

| المشغل (`kind`) | يتم تفعيله عند | الإعدادات |
|---|---|---|
| تم حجز موعد (`appointment_booked`) | يتم حجز موعد جديد. | لا يوجد |
| تم إلغاء موعد (`appointment_cancelled`) | يتم إلغاء موعد محجوز. | لا يوجد |
| تم إعادة جدولة موعد (`appointment_rescheduled`) | ينتقل موعد محجوز إلى وقت آخر، مع ذكر الوقت القديم بجانب الوقت الجديد. | `event_id` |
| قبل الموعد (`appointment_upcoming`) | وقت محدد قبل كل موعد مؤكد، للتذكيرات. ما يصل إلى خمسة تذكيرات لكل أتمتة. | `offsets_minutes` |

**المهام**

| المشغل (`kind`) | يتم تفعيله عند | الإعدادات |
|---|---|---|
| تم إنشاء مهمة (`task_created`) | يتم إنشاء مهمة. | `task_type` |
| تم إكمال مهمة (`task_completed`) | يتم نقل مهمة إلى مرحلة الإكمال. | لا يوجد |

**الحساب**

| المشغل (`kind`) | يتم تفعيله عند | الإعدادات |
|---|---|---|
| رصيد منخفض (`low_credit_balance`) | ينخفض رصيد الائتمان الخاص بك عن حد التنبيه الخاص بك. | لا يوجد |
| تم توصيل القناة (`channel_connected`) | تنتهي إحدى قنواتك من الاتصال. | `channel` |
| تم فصل القناة (`channel_disconnected`) | تنقطع إحدى قنواتك: تسجيل خروج، أو إلغاء ربط، أو انقطاع. رقم WhatsApp Web الذي يعيد الاتصال بنفسه لا يُحتسب إلا إذا ظل معطلاً بعد 30 دقيقة. | `channel` |

**الوكالة**

| المشغل (`kind`) | يتم تفعيله عند | الإعدادات |
|---|---|---|
| تم إنشاء حساب فرعي (`sub_account_created`) | يتم إنشاء حساب عميل جديد، من لوحة التحكم الخاصة بك، أو API، أو صفحة التسجيل الخاصة بك. | لا يوجد |
| نشاط الحساب الفرعي (`sub_account_event`) | يحدث شيء ما في أحد حسابات عملائك: انخفاض الرصيد، أو اتصال قناة، أو تغيير في الخطة. | `event`، `threshold` |

**عام والتطبيقات**

| المشغل (`kind`) | يتم تفعيله عند | الإعدادات |
|---|---|---|
| حسب الجدول الزمني (`schedule`) | وفق جدول زمني (cron). | `cron`, `timezone` |
| خطاف الويب (Webhook) (`webhook`) | يقوم نظام خارجي باستدعاء عنوان خطاف الويب الخاص بالأتمتة. | `webhook_secret` |
| وظيفة وكيل الذكاء الاصطناعي (`agent_function`) | يقوم وكيل الذكاء الاصطناعي الخاص بك باستدعاء هذه الأتمتة كوظيفة أثناء المحادثة. | `function_name`, `function_description`, `parameters`, `agent_ids`, `campaign_ids` |
| عنصر تغذية جديد (`rss`) | ظهور عنصر جديد في تغذية RSS أو Atom. | `feed_url` |
| استلام بريد إلكتروني (`email_received`) | وصول بريد إلكتروني إلى صندوق الوارد المتصل الخاص بك. | `from_contains`, `subject_contains` |
| حدث التطبيق (`app_event`) | حدوث شيء ما في تطبيق متصل: تغيير مرحلة صفقة، استلام دفعة، إرسال نموذج. | `toolkit`, `trigger_slug`, `connected_account_id`, `config` |
| التشغيل اليدوي (`manual`) | فقط عند بدء تشغيله يدوياً. | لا يوجد |

يمكن للأتمتة أن تحتوي على مشغل واحد كحد أقصى من كل نوع من أنواع `webhook`، `app_event`، `agent_function`، `rss`، `schedule`، `email_received`، `appointment_upcoming` و `contact_added`. لا يمكن إقران مشغل يتم تفعيله عند إنشاء سجل مع الإجراء الذي ينشئ نفس السجل، لأن الأتمتة ستقوم بتفعيل نفسها.

لمعرفة ما يقدمه كل مشغل للخطوات اللاحقة (`output_keys`) والقائمة الكاملة للإجراءات مع معاملاتها، اقرأ `GET /automations/steps`. يشرح [دليل الأتمتة](../automations/automations.md#triggers) كل مشغل بمصطلحات أداة الإنشاء.

---

## الأخطاء

كل خطأ له الشكل المعتاد `{ "success": false, "error_code": <status>, "error": "..." }`. يضيف الرسم البياني المرفوض `code` و`errors`: تسرد `errors` كل مشكلة، مع جملة واحدة قابلة للإصلاح لكل منها، و`error` هي المشكلة الأولى. أصلح ما هو مدرج بالضبط وأرسل الرسم البياني بالكامل مرة أخرى. `code` هي واحدة من `invalid_graph`، أو `automation_graph_has_a_cycle`، أو `self_triggering_automation`، أو `no_trigger`، أو رمز آخر من المنشئ.

| الحالة | متى |
|---|---|
| `400` | تم رفض الرسم البياني، أو فقدان حقل مطلوب (`name` أو `graph` عند الإنشاء، أو `folder_id` عند النقل)، أو أن التحديث لم يرسل أي شيء للتغيير، أو أن المعرف غير صالح، أو أن اسم المجلد مفقود أو فارغ أو طويل جدًا (`code: "invalid_name"`). |
| `403` | الحساب لا يحتوي على أتمتات؛ أو أن خطة حساب العميل لا تتضمن إنشاء وتعديل الأتمتات (كتابة فقط)؛ أو أن صلاحية وصول عضو الفريق إلى **الأتمتات** منخفضة جدًا. |
| `404` | لا توجد أتمتة بهذا المعرف في هذا الحساب، أو لا يوجد مجلد بهذا المعرف (`code: "folder_not_found"`)، أو أن `sub_account_id` ليس أحد حسابات عملائك. |
| `409` | يوجد مجلد بهذا الاسم بالفعل (`code: "folder_name_taken"`). |
| `413` | الأتمتة أكبر من 1 ميجابايت التي يقبلها المنشئ. انقل الكود أو البيانات الكبيرة خارج خطواتها. |
| `422` | رفض المنشئ الطلب لسبب آخر. تحقق من الرسم البياني مقابل `GET /automations/steps`؛ إرسال نفس الطلب مرة أخرى لن يساعد. |
| `503` | تعذر الوصول إلى خدمة الأتمتة. حاول مرة أخرى بعد لحظات. بالنسبة للإنشاء، اسرد أتمتاتك أولاً حتى لا تنشئ مسودة ثانية. |

::: master-only
## استخدام نقاط النهاية هذه عبر MCP

كل نقطة نهاية في هذه الصفحة هي أيضاً أداة لمساعد الذكاء الاصطناعي الذي [تتصل به عبر MCP](../integrations/connect-ai-clients.md)، مع نفس القواعد: الأتمتة الجديدة تكون مسودة حتى يتم تمكينها، وأي تعديل على أتمتة قيد التشغيل يصبح مباشراً.

| الأداة | نقطة النهاية |
|---|---|
| `list_automations` | `GET /automations` |
| `get_automation` | `GET /automations/{automationId}` |
| `list_automation_steps` | `GET /automations/steps` |
| `create_automation` | `POST /automations` |
| `update_automation` | `PUT /automations/{automationId}` |
| `enable_automation` | `POST /automations/{automationId}/enable` |
| `disable_automation` | `POST /automations/{automationId}/disable` |
| `list_automation_runs` | `GET /automations/{automationId}/runs` |
| `list_automation_folders` | `GET /automations/folders` |
| `create_automation_folder` | `POST /automations/folders` |
| `rename_automation_folder` | `PUT /automations/folders/{folderId}` |
| `delete_automation_folder` | `DELETE /automations/folders/{folderId}` |
| `move_automation_to_folder` | `PUT /automations/{automationId}/folder` |
:::

---

## الخطوات التالية

- [الأتمتة](../automations/automations.md): كيف تعمل المشغلات، والخطوات، والمتغيرات، وسجل التشغيل في أداة الإنشاء.
- [API للوكالات](../agency/api-for-agencies.md): بناء أتمتة على حساب عميل باستخدام `sub_account_id`.
- [مرجع API](reference.md): مستكشف نقاط النهاية التفاعلي الكامل.