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

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

عنوان URL الأساسي: https://api.dmchamp.com/v1
المصادقة: مفتاح واجهة برمجة التطبيقات الخاص بك (انظر المصادقة)
الأخطاء: انظر الأخطاء والترقيم و الأخطاء أدناه

تُظهر جميع الأمثلة أدناه نموذج الاستعلام ?apiKey= في cURL ورأس X-API-Key في JavaScript و Python. كلاهما يعمل على كل نقطة نهاية.

الوكالات: تقبل كل نقطة نهاية في هذه الصفحة sub_account_id كمعامل استعلام، بحيث يمكنك قراءة وبناء أتمتة العميل باستخدام مفتاح الوكالة الخاص بك. أي sub_account_id ليس أحد حسابات عملائك سيعيد 404. انظر واجهة برمجة التطبيقات للوكالات.

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

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

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

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

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

الوصول

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

كائن الأتمتة

تعيد القائمة ملخصاً لكل أتمتة، بدون خطواتها:

{
  "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f",
  "name": "Price question auto-reply",
  "description": "Replies with the price list when someone asks about prices.",
  "enabled": false,
  "updated_at": "2026-10-27T09:40:00.000Z",
  "trigger_kind": "incoming_message",
  "folder_id": "f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708",
  "folder_name": "Sales"
}

الحقل	المعنى
`id`	معرف الأتمتة.
`name`	ما يسمى به في القائمة.
`description`	جملة إلى ثلاث جمل حول ما تفعله، أو `null`.
`enabled`	ما إذا كانت قيد التشغيل. الأتمتة المعطلة لا تعمل أبداً.
`updated_at`	متى تم تغييرها آخر مرة.
`trigger_kind`	ما الذي يبدأ تشغيلها، على سبيل المثال `incoming_message`، أو `schedule`، أو `webhook`، أو `agent_function`، أو `manual`. `null` عندما لا يحتوي الرسم البياني على مشغل بعد.
`folder_id`، `folder_name`	المجلد الذي تم حفظها فيه، أو `null` إذا لم تكن في مجلد.

تؤدي قراءة أتمتة واحدة إلى إضافة created_at وgraph الخاص بها:

{
  "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f",
  "name": "Price question auto-reply",
  "description": "Replies with the price list when someone asks about prices.",
  "enabled": false,
  "created_at": "2026-10-27T09:12:00.000Z",
  "updated_at": "2026-10-27T09:40:00.000Z",
  "trigger_kind": "incoming_message",
  "folder_id": null,
  "folder_name": null,
  "graph": {
    "nodes": [
      {
        "id": "trigger_1",
        "kind": "trigger",
        "label": "Incoming message",
        "alias": "incoming_message",
        "action": "incoming_message",
        "params": { "message_filter_contains": "price" },
        "config": { "kind": "incoming_message", "message_filter_contains": "price" }
      },
      {
        "id": "send_prices",
        "kind": "action",
        "label": "Send message",
        "alias": "send_message",
        "action": "SEND_MESSAGE",
        "params": { "contact_id": "${trigger.contact.id}", "body": "Hi ${trigger.contact.first_name}, here is our price list: https://example.com/prices" },
        "config": { "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": [{ "from": "trigger_1", "to": "send_prices" }]
  }
}

تحتوي كل خطوة (nodes[]) على:

الحقل	المعنى
`id`	معرف الخطوة، وهو فريد داخل المخطط.
`kind`	نوع الخطوة: `trigger`، `action`، `condition`، `transform`، `ai`، `delay`، `loop` أو `respond`. راجع أنواع الخطوات.
`label`	الاسم المعروض على الخطوة في أداة الإنشاء.
`alias`	الاسم المرجعي للخطوة. تقرأ الخطوات اللاحقة مخرجاتها كـ `${nodes.<alias>.<field>}`. `null` في خطوة لا تملك اسماً (يتم الإشارة إليها حينها بمعرفها).
`action`	ما تفعله الخطوة: الإجراء الذي تقوم بتشغيله، أو نوع المشغل في خطوة المشغل. `null` في الخطوات الأخرى.
`params`	معلمات الإجراء في خطوة الإجراء، أو إعدادات المشغل في خطوة المشغل. `null` في كل نوع آخر. تم الاحتفاظ به للقراء القدامى: `config` يحمل نفس القيم وأكثر.
`config`	إعدادات الخطوة الكاملة كما تخزنها أداة الإنشاء، لكل نوع من الخطوات: قواعد الشرط، ومطالبة خطوة الذكاء الاصطناعي، ومدة التأخير، وslug الإجراء ومعلماته.

يحتوي كل اتصال (edges[]) على from وto (معرفات الخطوات)، وbranch عندما يتبع فرعاً واحداً من الخطوة، على سبيل المثال true أو false بعد شرط.

يتم تغيير شيئين في config عند الخروج:

إخفاء الأسرار. القيم التي تبدو كبيانات اعتماد (أسرار خطاف الويب، الرموز المميزة، مفاتيح API، كلمات المرور، قيم الرأس) تعود كـ "[redacted]". أرسل "[redacted]" مرة أخرى دون تغيير وسيتم الاحتفاظ بالقيمة المخزنة.
تقصير النصوص الطويلة. يتم تقصير النص الواحد الذي يزيد طوله عن 4000 حرف تقريباً وينتهي بعلامة حذف. إذا قمت بإرسال تلك الخطوة مرة أخرى، ضع نصها الكامل فيها أولاً.

سرد الأتمتات

يعيد GET /automations الأتمتات الموجودة في الحساب، مرتبة حسب الأحدث تغييراً أولاً، كملخصات (بدون خطوات).

معلمات الاستعلام (جميعها اختيارية): folder_id (فقط الأتمتات الموجودة في ذلك المجلد، معرف من سرد المجلدات، أو none للأتمتات التي لا تتبع لأي مجلد)، sub_account_id.

cURL

curl "https://api.dmchamp.com/v1/automations?apiKey=YOUR_API_KEY&folder_id=none"

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/automations?folder_id=none", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { automations } = await res.json();

Python

res = requests.get(
    "https://api.dmchamp.com/v1/automations",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"folder_id": "none"},
)
automations = res.json()["automations"]

الاستجابة (200)

{ "success": true, "automations": [{ "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f", "name": "Price question auto-reply", "enabled": false, "...": "..." }] }

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

الحصول على أتمتة

يعيد GET /automations/{automationId} أتمتة واحدة مع مخططها الكامل: نوع كل خطوة، وتسميتها، واسمها المستعار، وإجراءها، ومعلماتها، وإعداداتها، بالإضافة إلى الاتصالات بينها.

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

const res = await fetch("https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { automation } = await res.json();

res = requests.get(
    "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
automation = res.json()["automation"]

الاستجابة (200)

{ "success": true, "automation": { "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f", "name": "Price question auto-reply", "graph": { "nodes": ["..."], "edges": ["..."] } } }

المعرف غير الموجود في هذا الحساب يعيد 404.

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

يعيد GET /automations/steps كل ما يمكن بناء أتمتة منه:

node_kinds: الأنواع الثمانية للخطوات، كل منها يحتوي على تسمية ووصف.
triggers: كل مشغل (trigger) يمكنه بدء التشغيل الآلي، مع حقول الإعدادات الخاصة به (fields) والقيم التي يمررها للخطوات اللاحقة (output_keys).
actions: الإجراءات المضمنة التي يمكن لخطوة الإجراء تشغيلها، كل منها مع key (الاسم المختصر الذي تستخدمه في الرسم البياني) و params الخاص بها، مع تحديد required حيث توجد.
api_actions: عمليات واجهة برمجة التطبيقات (API) هذه التي يمكن لخطوة الإجراء استدعاؤها. بدون q، تعود كملصقات مجمعة حسب المنطقة في api_actions_by_tag، وتكون القائمة المسطحة فارغة، نظرًا لوجود عدة مئات منها.
graph_rules: قواعد كتابة الرسم البياني: البيانات التي يحملها كل نوع من الخطوات، وكل نوع من المشغلات مع مفاتيح الإعدادات الخاصة به، وموفري الإجراءات، وأسماء الفروع، وبنية القالب. اقرأها قبل إنشاء أو تعديل أي منها.
counts: الإجماليات لكل قائمة، أيًا كان ما بحثت عنه.

هذا ما يقدمه المنشئ، وليس ما قام الحساب ببنائه. تحقق من ذلك قبل أن تستنتج أن المشغل أو الإجراء غير موجود.

معلمات الاستعلام (كلها اختيارية): q، كلمة للبحث في كل قائمة (غير حساسة لحالة الأحرف)، و sub_account_id.

مع q:

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

curl "https://api.dmchamp.com/v1/automations/steps?apiKey=YOUR_API_KEY&q=tag"

const res = await fetch("https://api.dmchamp.com/v1/automations/steps?q=tag", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { triggers, actions, graph_rules } = await res.json();

res = requests.get(
    "https://api.dmchamp.com/v1/automations/steps",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"q": "tag"},
)
catalogue = res.json()

الاستجابة (200، مختصرة)

{
  "success": true,
  "q": "tag",
  "node_kinds": [{ "kind": "trigger", "label": "Trigger", "description": "Starts the automation when an event happens." }],
  "triggers": [
    {
      "kind": "tag_applied",
      "label": "Tag applied",
      "group": "Contacts",
      "fields": ["tag_name", "channel", "applied_by"],
      "output_keys": ["contact.id", "contact.first_name", "..."]
    }
  ],
  "actions": [
    {
      "key": "SET_CONTACT_TAG",
      "label": "Set contact tag",
      "group": "Contacts",
      "provider": "native",
      "params": [{ "key": "contact_id", "required": true }, { "key": "tag", "required": true }]
    }
  ],
  "api_actions": ["..."],
  "app_actions": [],
  "graph_rules": "GRAPH: { nodes: [{ id, type, label?, data }], edges: [{ source, target, sourceHandle? }] } ...",
  "counts": { "node_kinds": 8, "triggers": 40, "actions": 44, "api_actions": 454 }
}

قوائم أنواع الخطوات و المشغلات أدناه مأخوذة من نقطة النهاية هذه. نقطة النهاية نفسها هي دائمًا القائمة الحالية.

إنشاء تشغيل آلي

POST /automations ينشئ تشغيلًا آليًا من اسم ورسم بياني. يتم تخزينه مغلقًا، كمسودة.

النص الأساسي

الحقل	مطلوب	المعنى
`name`	نعم	ما يسمى به في القائمة. قصير ومحدد.
`description`	لا	جملة إلى ثلاث جمل حول ما يفعله ومتى يعمل.
`graph`	نعم	`{ nodes, edges }`، انظر أدناه.
`folder_id`	لا	المجلد المراد حفظه فيه، معرف من قائمة المجلدات. إذا تُرك فارغًا أو `null`، فلن يتم وضعه في أي مجلد.

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

كل عقدة لها id (فريد في الرسم البياني، على سبيل المثال trigger_1 أو send_reminder)، و type (واحد من 8 أنواع خطوات)، و label اختياري، وإعداداتها في data، تحت مفتاح مسمى باسم نوعها: data.trigger = { kind, ... }، data.action = { provider, slug, params }، data.condition = { ... }، data.delay = { seconds }، data.ai = { prompt }، data.loop = { over }، data.transform = { language, code }، data.respond = { status, body, content_type }.
يحتاج التشغيل الآلي إلى مشغل واحد على الأقل. تسمح القواعد الحية بما يصل إلى 10، ويبدأ التشغيل الآلي عندما يتم تشغيل أي منها.
يجب أن تكون كل خطوة أخرى قابلة للوصول من مشغل، ولا يجوز أن يؤدي أي اتصال إلى خطوة سابقة.
كل حافة لها source و target. الحواف التي تخرج من شرط تحمل sourceHandle true أو false. الحواف التي تخرج من حلقة تحمل body أو done. الحواف التي تخرج من تأخير “انتظار الرد” تحمل replied أو timed_out. الحواف الأخرى ليس لها sourceHandle؛ تسرد القواعد الباقي.
تأتي أسماء الإجراءات والمعلمات من الكتالوج. لا تخمن أبدًا معرفًا (وكيل، علامة، قائمة، مرحلة): ابحث عنه باستخدام واجهة برمجة التطبيقات أولاً، أو اترك الحقل كـ "" ليختاره الشخص في المنشئ.
المواضع اختيارية. يتم ترتيب الخطوات التي لا تحتوي على موضع تلقائيًا.
يتم كتابة القيم من الخطوات السابقة كـ ${trigger.<field>} و ${nodes.<step>.<field>}. انظر استخدام ما أعادته خطوة سابقة و التعبيرات في دليل التشغيل الآلي.

يتم قبول الرسم البياني بطريقتين للكتابة: طريقة المنشئ الخاصة (عقد بـ type و data، حواف بـ source و target، كما هو موضح أدناه) والطريقة التي يجيب بها الحصول على تشغيل آلي (عقد بـ kind، config، action، params؛ حواف بـ from، to، branch). لذا يمكنك قراءة تشغيل آلي، وتغيير خطوة، وإرساله مرة أخرى.

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" }]
    }
  }'

const res = await fetch("https://api.dmchamp.com/v1/automations", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Price question auto-reply", graph: { nodes, edges } }),
});
const { automation, draft, open_path, warnings } = await res.json();

res = requests.post(
    "https://api.dmchamp.com/v1/automations",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Price question auto-reply", "graph": {"nodes": nodes, "edges": edges}},
)
draft = res.json()

الاستجابة (201)

{
  "success": true,
  "automation": { "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f", "name": "Price question auto-reply", "enabled": false, "graph": { "...": "..." } },
  "draft": true,
  "open_path": "/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f",
  "warnings": []
}

automation هو التشغيل الآلي كما تم تخزينه، بنفس شكل الحصول على تشغيل آلي.
draft هي true أثناء إيقاف تشغيله. يكون التشغيل الآلي الجديد دائمًا مسودة حتى تقوم بـ تمكينه، لذا فإن enabled: false هنا أمر طبيعي، وليس فشلًا.
open_path هو المكان الذي يفتح فيه في منشئ التطبيق.
warnings يسرد الأشياء التي لم يتمكن المنشئ من إنهائها، كملصقات قصيرة (على سبيل المثال agent_function:not_linked). تكون فارغة عندما يكون كل شيء نظيفًا.

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

تحديث أتمتة

PUT /automations/{automationId} يغير الاسم، والوصف، و/أو الرسم البياني. أرسل فقط الحقول التي تريد تغييرها.

الجسم (Body): name، description، graph (جميعها اختيارية، يجب توفير واحد على الأقل).

يقوم graph باستبدال الرسم البياني بالكامل، لذا اعمل دائماً بناءً على ما هو مخزن:

اقرأ الأتمتة باستخدام GET /automations/{automationId}.
قم بتغيير ما تحتاجه في ذلك الرسم البياني.
أرسل الرسم البياني بالكامل مرة أخرى، متضمناً كل خطوة.

عند إرساله مرة أخرى:

احتفظ بـ alias لكل خطوة تماماً كما حصلت عليه. تشير الخطوات اللاحقة إلى الخطوة بواسطة اسم مستعار لها (${nodes.<alias>.<field>}). إذا قمت بتغييره أو حذفه، فسيصبح كل مرجع لتلك الخطوة فارغاً. راجع تسمية خطواتك.
اترك قيم "[redacted]" كما هي. القيمة التي تظهر كـ "[redacted]" تحتفظ بقيمتها المخزنة.
استعد النصوص المختصرة. النص الذي عاد منتهياً بنقاط حذف تم اختصاره أثناء القراءة.

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

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)" }'

// Read, edit, send back the whole graph
const get = await fetch(`https://api.dmchamp.com/v1/automations/${id}`, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const { automation } = await get.json();
const step = automation.graph.nodes.find((n) => n.id === "send_prices");
step.config.params.body = "Hi ${trigger.contact.first_name}, our new price list: https://example.com/prices";
await fetch(`https://api.dmchamp.com/v1/automations/${id}`, {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ graph: automation.graph }),
});

url = f"https://api.dmchamp.com/v1/automations/{automation_id}"
automation = requests.get(url, headers={"X-API-Key": "YOUR_API_KEY"}).json()["automation"]
# ...edit automation["graph"] here, keeping every alias...
requests.put(url, headers={"X-API-Key": "YOUR_API_KEY"}, json={"graph": automation["graph"]})

الاستجابة (200): بنفس شكل الإنشاء (automation، draft، open_path، warnings). إرسال أي من name، أو description، أو graph لا يعيد 400.

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

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

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

لا يتطلب أي من الاستدعاءين جسماً (body).

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

await fetch("https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/disable", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});

requests.post(
    "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/enable",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

الاستجابة (200): الأتمتة كما هي مخزنة الآن، بنفس شكل الإنشاء، مع draft: false بعد التمكين.

سجل التشغيل

GET /automations/{automationId}/runs تُرجع عمليات التشغيل لأتمتة واحدة، مرتبة من الأحدث إلى الأقدم: متى بدأت كل عملية تشغيل وانتهت، وما الذي أدى إلى تشغيلها، وما إذا كانت قد نجحت، والخطأ الذي حدث عند فشلها. قراءة الأتمتة تخبرك بما ستفعله. أما سجل التشغيل فيخبرك بما فعلته بالفعل، وهو الطريقة الوحيدة للتمييز بين أتمتة لم يتم تشغيلها مطلقاً وأتمتة تعمل وتفشل في كل مرة.

معلمات الاستعلام (جميعها اختيارية): limit (من 1 إلى 50، القيمة الافتراضية 10)، sub_account_id.

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

const res = await fetch("https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/runs?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { runs, note } = await res.json();

res = requests.get(
    "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/runs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 20},
)
runs = res.json()["runs"]

الاستجابة (200)

{
  "success": true,
  "automation": { "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f", "name": "Price question auto-reply", "enabled": true, "trigger_kind": "incoming_message" },
  "runs": [
    {
      "id": "run_7f3a",
      "status": "failed",
      "trigger_source": "incoming_message",
      "started_at": "2026-10-27T10:02:11.000Z",
      "finished_at": "2026-10-27T10:02:12.000Z",
      "error": "Contact is on Do Not Disturb list",
      "cancel_reason": null,
      "mode": "live"
    }
  ]
}

mode تكون live لعملية تشغيل حقيقية، أو safe لـ تشغيل آمن (Safe run) من المحرر. لا يرسل التشغيل الآمن أي شيء، لذا فهو ليس دليلاً على أن الأتمتة تعمل في الاستخدام الفعلي.
قائمة runs الفارغة هي إجابة وليست نقصاً. في هذه الحالة، تحمل الاستجابة note: إما أن المشغل لم يعمل مطلقاً، أو أن الأتمتة متوقفة، وبالتالي لم يتم تشغيل أي شيء.

المجلدات

تعمل المجلدات فقط على تجميع الأتمتة في القائمة. وهي لا تغير أبداً ما تفعله الأتمتة أو ما إذا كانت قيد التشغيل. راجع تنظيم الأتمتة في مجلدات.

سرد المجلدات

GET /automations/folders تُرجع المجلدات، مع توضيح عدد الأتمتة التي يحتويها كل مجلد، بالإضافة إلى unfiled_count: عدد الأتمتة التي لا توجد في أي مجلد.

curl "https://api.dmchamp.com/v1/automations/folders?apiKey=YOUR_API_KEY"

{
  "success": true,
  "folders": [{ "id": "f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708", "name": "Sales", "automation_count": 3 }],
  "unfiled_count": 5
}

إنشاء مجلد

POST /automations/folders مع { "name": "Appointment reminders" }. الاسم مطلوب، بحد أقصى 100 حرف، ويجب أن يكون فريداً في الحساب. يمكنك وضع الأتمتة داخل المجلد باستخدام نقل أتمتة، أو تمرير folder_id عند إنشاء واحدة.

curl -X POST "https://api.dmchamp.com/v1/automations/folders?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Appointment reminders" }'

الاستجابة (201): { "success": true, "folder": { "id": "...", "name": "Appointment reminders", "automation_count": 0 } }. الاسم الذي يستخدمه مجلد آخر بالفعل يُرجع 409 مع code: "folder_name_taken".

إعادة تسمية مجلد

PUT /automations/folders/{folderId} مع { "name": "..." }. تظل الأتمتة الموجودة بداخله في مكانها.

الاستجابة (200): { "success": true, "folder": { ... } }.

حذف مجلد

DELETE /automations/folders/{folderId} تحذف المجلد فقط. الأتمتة الموجودة بداخله لا تُحذف: بل تنتقل إلى خارج أي مجلد وتستمر في العمل تماماً كما كانت من قبل.

curl -X DELETE "https://api.dmchamp.com/v1/automations/folders/f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708?apiKey=YOUR_API_KEY"

{ "success": true, "deleted": true, "moved_to_no_folder": 3, "message": "Folder deleted. 3 automations were moved to No folder; no automation was deleted." }

نقل أتمتة إلى مجلد

PUT /automations/{automationId}/folder باستخدام { "folder_id": "<folder id>" }، أو { "folder_id": null } لإخراجها من مجلدها. folder_id مطلوبة. يتغير فقط المكان الذي تُدرج فيه الأتمتة.

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" }'

الاستجابة (200): { "success": true, "automation_id": "...", "folder_id": "..." }.

الكتالوج

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

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

المشغلات

هذه هي المشغلات الأربعون التي يسردها الكتالوج اليوم، مجمعة كما يصنفها المنشئ. يحتوي عمود الإعدادات على مفاتيح إعدادات المشغل الخاصة (fields)، والتي تضيق نطاق وقت تفعيله. يأخذ كل مشغل أيضاً respect_quiet_hours و run_hours و reentry و stop_on_response؛ راجع إعدادات الأتمتة.

المراسلة

المشغل (`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. يشرح دليل الأتمتة كل مشغل بمصطلحات أداة الإنشاء.

الأخطاء

كل خطأ له الشكل المعتاد { "success": false, "error_code": <status>, "error": "..." }. الرسم البياني المرفوض يضيف code و errors:

{
  "success": false,
  "error_code": 400,
  "code": "invalid_graph",
  "error": "<the first problem, as one sentence>",
  "errors": ["<the first problem, as one sentence>", "<the next problem>"]
}

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`	تعذر الوصول إلى خدمة الأتمتة. حاول مرة أخرى بعد لحظات. بالنسبة للإنشاء، قم بإدراج الأتمتة الخاصة بك أولاً حتى لا تقوم بإنشاء مسودة ثانية.

استخدام نقاط النهاية هذه عبر MCP

كل نقطة نهاية في هذه الصفحة هي أيضاً أداة لمساعد الذكاء الاصطناعي الذي تتصل به عبر MCP، مع نفس القواعد: الأتمتة الجديدة تكون مسودة حتى يتم تمكينها، وأي تعديل على أتمتة قيد التشغيل يصبح مباشراً.

الأداة	نقطة النهاية
`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`

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

الأتمتة: كيف تعمل المشغلات، والخطوات، والمتغيرات، وسجل التشغيل في أداة الإنشاء.
API للوكالات: بناء أتمتة على حساب عميل باستخدام sub_account_id.
مرجع API: مستكشف نقاط النهاية التفاعلي الكامل.

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

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

الوصول #

كائن الأتمتة #

سرد الأتمتات #

الحصول على أتمتة #

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

إنشاء تشغيل آلي #

تحديث أتمتة #

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

سجل التشغيل #

المجلدات #

سرد المجلدات #

إنشاء مجلد #

إعادة تسمية مجلد #

حذف مجلد #

نقل أتمتة إلى مجلد #

الكتالوج #

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

المشغلات #

الأخطاء #

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

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

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

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

الوصول

كائن الأتمتة

سرد الأتمتات

الحصول على أتمتة

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

إنشاء تشغيل آلي

تحديث أتمتة

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

سجل التشغيل

المجلدات

سرد المجلدات

إنشاء مجلد

إعادة تسمية مجلد

حذف مجلد

نقل أتمتة إلى مجلد

الكتالوج

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

المشغلات

الأخطاء

استخدام نقاط النهاية هذه عبر MCP

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