# API אוטומציות

אוטומציה היא תהליך עבודה המורכב משלבים: טריגר אחד או יותר שמפעילים אותו, ולאחר מכן פעולות, תנאים, השהיות, שלבי בינה מלאכותית ושאר מרכיבים, המחוברים יחד לגרף. זוהי אותה אוטומציה שאתה רואה ועורך בדף [אוטומציות](../automations/automations.md). מדריך זה מכסה קריאה ובנייה שלהן באמצעות ה-API.

- **כתובת בסיס (Base 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`. ראה [API לסוכנויות](../agency/api-for-agencies.md).

---

## איך זה עובד: תחילה טיוטה

ה-API בנוי כך ששום דבר לא יתחיל לפעול בטעות.

1. **קרא את הקטלוג.** `GET /automations/steps` מפרט כל טריגר, פעולה וסוג שלב שניתן להשתמש בהם, בתוספת הדקדוק לכתיבת גרף (`graph_rules`).
2. **צור טיוטה.** `POST /automations` שומר את האוטומציה כשהיא **כבויה**. שום דבר עדיין לא רץ.
3. **בדוק אותה.** קרא אותה בחזרה, פתח אותה בבונה (התגובה נותנת לך את ה-`open_path` שלה), וודא שבעל החשבון ראה מה היא עושה ולמי.
4. **הפעל אותה.** `POST /automations/{automationId}/enable` היא קריאה בפני עצמה. זהו השלב שגורם לדברים אמיתיים לקרות: הודעות נשלחות, רשומות משתנות, כלים ניתנים לסוכן בינה מלאכותית.

עריכה לעולם לא משנה אם אוטומציה מופעלת או כבויה. המשמעות היא גם ששינוי באוטומציה שהיא **מופעלת** נכנס לתוקף מיד, באוטומציה החיה. כדי לשנות אוטומציה רצה בבטחה, השבת אותה, ערוך אותה, בדוק אותה והפעל אותה שוב.

כל גרף שאתה שולח עובר את אותן בדיקות שבונה הקנבס מיישם. גרף שלא ניתן לפתוח או להריץ נדחה עם `400` שמפרט בדיוק מה צריך לתקן.

### גישה

- החשבון זקוק לאוטומציות. ללא זה, כל קריאה בדף זה תחזיר `403`.
- הגישה של חבר צוות עוקבת אחר אזור ה-**אוטומציות** שלו ב-[ניהול צוות](../settings/team-management.md): קריאה (רשימה, קבלת פרטים, שלבים, הרצות, תיקיות) דורשת **צפייה**, וכל מה שמשנה משהו דורש **עריכה**.
- בחשבון לקוח שהתוכנית שלו אינה כוללת יצירה ועריכה של אוטומציות, קריאות הכתיבה יחזירו `403`, בדיוק כפי שהבונה עושה באפליקציה.

---

## נקודות קצה (Endpoints)

| משימה | מתודה + נתיב | סייר |
|---|---|---|
| רשימת אוטומציות | `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` נושא את אותם ערכים ועוד (חוקי תנאי, הנחיית צעד AI, משך השהיה, slug ופרמטרים של פעולה).
- **סודות מוסתרים.** ערכים שנראים כמו אישורים (סודות webhook, אסימונים, מפתחות API, סיסמאות, ערכי כותרות) חוזרים כ-`"[redacted]"`. שלחו את `"[redacted]"` בחזרה ללא שינוי והערך השמור יישמר.
- **טקסטים ארוכים מקוצרים.** טקסט בודד שארוך מ-4,000 תווים בערך נחתך ומסתיים בשלוש נקודות. אם אתם שולחים את הצעד הזה בחזרה, הכניסו תחילה את הטקסט המלא שלו.
- אם לא ניתן להגיע לשירות האוטומציה, תקבלו `503`, לעולם לא רשימה ריקה במקומו. רשימה ריקה תמיד אומרת שאין אוטומציות.

### קטלוג הצעדים

`GET /automations/steps` מחזירה את כל מה שניתן לבנות ממנו אוטומציה: 8 ה-`node_kinds`, כל טריגר עם ההגדרות שלו `fields` ו-`output_keys`, ה-`actions` המובנים עם הפרמטרים שלהם, ה-`api_actions` (פעולות של ה-API הזה שצעד פעולה יכול לקרוא), הדקדוק של `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`. לקשתות אחרות אין כאלו.
- ה-slugs והפרמטרים של הפעולות מגיעים מהקטלוג. **לעולם אל תנחשו id** (סוכן, תגית, רשימה, שלב): חפשו אותו ב-API תחילה, או השאירו את השדה כ-`""` כדי שהמשתמש יבחר בבונה.
- מיקומים הם אופציונליים; צעדים ללא מיקום מסודרים אוטומטית.
- ערכים מצעדים קודמים נכתבים כ-`${trigger.<field>}` ו-`${nodes.<step>.<field>}`. ראו [שימוש במה שצעד קודם החזיר](../automations/automations.md#using-what-an-earlier-step-returned) ו-[ביטויים](../automations/automations.md#expressions).
- הגרף מתקבל בשני איותים: זה של הבונה (למעלה) וזה שקריאה מחזירה (`kind`, `config`, `from`, `to`, `branch`). כך שניתן לקרוא אוטומציה, לשנות צעד ולשלוח אותו בחזרה.
- **יצירה אינה בטוחה לחזרה עיוורת.** אם בקשה פגה (timeout), רשמו את האוטומציות שלכם לפני שתשלחו אותה שוב, אחרת אתם עלולים להישאר עם שתי טיוטות.

### עדכון

`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` מפעיל אוטומציה, כך שהיא תרוץ לפי הטריגר שלה מעתה ואילך. קרא לזה רק לאחר שבעל החשבון ראה מה האוטומציה עושה ולמי, והסכים לכך. ה-builder מסרב להפעיל גרף שהוא לא יכול להריץ (אין טריגר, לולאה, שלב שמפעיל את עצמו) עם `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` עבור **הרצה בטוחה (Safe run)** מהעורך. הרצה בטוחה לא שולחת דבר, לכן היא אינה הוכחה לכך שהאוטומציה עובדת בשימוש אמיתי.
- רשימת `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` | שואל את ה-AI באמצעות הנחיה (prompt) שתכתוב. הוא יכול להחזיר טקסט, שדות נפרדים, או לבחור באחד מכמה ענפים. |
| `delay` | ממתין לזמן מוגדר, או ממתין לתגובת איש הקשר (עם זמן קצוב). |
| `loop` | חוזר על השלבים שבתוכו עבור כל פריט ברשימה. |
| `respond` | מחזיר תגובה לקריאת ה-webhook או לקריאת פונקציית סוכן ה-AI שהפעילה את ההרצה. |

### טריגרים

אלו הם 40 הטריגרים שהקטלוג מציג כיום, מקובצים כפי שהבונה מקבץ אותם. עמודת **הגדרות** מכילה את מפתחות ההגדרות של הטריגר עצמו (`fields`), אשר מצמצמים את מתי הוא מופעל. כל טריגר מקבל גם `respect_quiet_hours`, `run_hours`, `reentry` ו-`stop_on_response`; ראה [הגדרות אוטומציה](../automations/automations.md#automation-settings).

**הודעות**

| טריגר (`kind`) | מופעל כאשר | הגדרות |
|---|---|---|
| הודעה נכנסת (`incoming_message`) | איש קשר שולח הודעה בכל ערוץ. | `campaign` (מגביל לסוכן AI אחד), `channel`, `message_filter_contains` (מילת מפתח), `message_filter_regex` (תבנית) |
| שיחה שלא נענתה (`missed_call`) | מישהו מתקשר לאחד ממספרי ה-WhatsApp Web שלך או למספר ה-SMS שלך ואף אחד לא עונה. | `to_number` |
| הודעה נמסרה (`message_delivered`) | הודעה ששלחת אושרה כנמסרה על ידי הערוץ. | `channel`, `agent` |
| הודעה נכשלה (`message_failed`) | הודעה ששלחת לא הצליחה להימסר, עם השגיאה. | `channel`, `agent` |
| הודעה נשלחה (`message_sent`) | כל הודעה עוזבת את החשבון שלך: של ה-AI, שלך, שידור, או הודעת המשך. סנן אותה, אחרת היא תרוץ על כולן. | `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`) | תגית מתווספת לאיש קשר, על ידי סוכן ה-AI שלך, אדם, אוטומציה או ייבוא. | `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 של האוטומציה. | `webhook_secret` |
| פונקציית סוכן AI (`agent_function`) | סוכן ה-AI שלך קורא לאוטומציה זו כפונקציה במהלך שיחה. | `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`) | רק כאשר היא מופעלת באופן ידני. | none |

אוטומציה יכולה להכיל לכל היותר טריגר אחד מכל סוג של `webhook`, `app_event`, `agent_function`, `rss`, `schedule`, `email_received`, `appointment_upcoming` ו-`contact_added`. טריגר שמופעל כאשר רשומה נוצרת לא יכול להיות משולב עם הפעולה שיוצרת את אותה רשומה, כיוון שהאוטומציה תפעיל את עצמה.

למידע על מה כל טריגר מעביר לשלבים הבאים (`output_keys`) ועל הרשימה המלאה של פעולות עם הפרמטרים שלהן, קרא את `GET /automations/steps`. [מדריך האוטומציות](../automations/automations.md#triggers) מסביר כל טריגר במילים של ה-builder.

---

## שגיאות

לכל שגיאה יש את המבנה הרגיל `{ "success": false, "error_code": <status>, "error": "..." }`. גרף שנדחה מוסיף `code` ו-`errors`: `errors` מפרט כל בעיה, משפט אחד שניתן לתיקון לכל בעיה, ו-`error` הוא הראשון שבהם. תקן בדיוק את מה שמפורט ושלח את הגרף כולו שוב. `code` הוא אחד מ-`invalid_graph`, `automation_graph_has_a_cycle`, `self_triggering_automation`, `no_trigger`, או קוד אחר מה-builder.

| סטטוס | מתי |
|---|---|
| `400` | הגרף נדחה, שדה חובה חסר (`name` או `graph` ביצירה, `folder_id` בהעברה), עדכון שלא שלח דבר לשינוי, מזהה (id) לא תקין, או שם תיקייה חסר, ריק או ארוך מדי (`code: "invalid_name"`). |
| `403` | לחשבון אין אוטומציות; התוכנית של חשבון לקוח אינה כוללת יצירה ועריכה של אוטומציות (כתיבה בלבד); או שהגישה של חבר הצוות ל-**Automations** נמוכה מדי. |
| `404` | אין אוטומציה עם מזהה כזה בחשבון זה, אין תיקייה עם מזהה כזה (`code: "folder_not_found"`), או ש-`sub_account_id` אינו אחד מחשבונות הלקוח שלך. |
| `409` | תיקייה בשם זה כבר קיימת (`code: "folder_name_taken"`). |
| `413` | האוטומציה גדולה מ-1 MB שה-builder מקבל. העבר קוד או נתונים גדולים מחוץ לשלבים שלה. |
| `422` | ה-builder דחה את הבקשה מסיבה אחרת. בדוק את הגרף מול `GET /automations/steps`; שליחת אותה בקשה שוב לא תעזור. |
| `503` | לא ניתן היה להגיע לשירות האוטומציות. נסה שוב בעוד רגע. עבור יצירה, הצג תחילה את האוטומציות שלך כדי שלא תיצור טיוטה שנייה. |

::: master-only
## שימוש בנקודות קצה אלו דרך MCP

כל נקודת קצה בדף זה היא גם כלי עבור עוזר AI שאתה [מחבר דרך 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): כיצד טריגרים, שלבים, משתנים והיסטוריית הרצות עובדים ב-builder.
- [API לסוכנויות](../agency/api-for-agencies.md): בנה אוטומציות בחשבון לקוח עם `sub_account_id`.
- [תיעוד API](reference.md): סייר נקודות הקצה האינטראקטיבי המלא.