> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# نظرة عامة على واجهة برمجة تطبيقات الأتمتة

> أتمتة Instagram المُشغَّلة بالتفاعل — إطلاق رسالة خاصة أو Webhook أو بريد إلكتروني عندما يُعلّق مستخدم نهائي أو يردّ على ستوري أو يتفاعل مع رسالة خاصة أو يُرسل رسالة خاصة

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

<PlansAvailable plans={["business", "enterprise"]} maxPackRequired={false} />

<Note>
  **إصدار تجريبي (Beta).** واجهة برمجة تطبيقات الأتمتة قيد الإصدار التجريبي ونحن نجمع الملاحظات بنشاط. قد تتغير نقاط النهاية والحمولات والحدود مع تطويرنا لها. يُرجى إرسال الملاحظات وتقارير الأخطاء إلى الدعم لكي نتمكّن من ترتيب أولويات التحسينات الصحيحة.
</Note>

تُمكّنك نقاط نهاية الأتمتة من تحديد قواعد تتفاعل تلقائيًا مع التفاعل الوارد على Instagram. تجمع كل أتمتة بين **مشغّل** واحد أو أكثر (الحدث الذي يُطلق القاعدة) و**إجراء** واحد أو أكثر (ما يحدث عند إطلاقها). يمكن لقاعدة واحدة أن تستمع لعدة مشغّلات وترسل عدة إجراءات — أطلق Webhook إلى مسار التحليلات لديك وأرسل رسالة خاصة من نفس التفاعل.

يعمل المحرّك بالكامل داخل نطاق سياسة Meta (لا توجد رسائل خاصة تُطلق عبر المتابعة، ولا رسائل أولى للغرباء، ولا إرسال جماعي)، ويرث حدود المعدل لكل حساب في Ayrshare وإزالة التكرار لكل مستلم واستيعاب Webhook الآمن من التكرار.

## كيف يعمل

<Steps>
  <Step title="أنشئ أتمتة">
    `POST /automations` مع المشغّلات والإجراءات التي تريدها. تنشط الأتمتة على الفور.
  </Step>

  <Step title="يتفاعل مستخدم نهائي">
    يُعلّق شخص ما على منشورك أو يردّ على ستوري أو يُرسل رسالة خاصة أو يتفاعل مع رسالة خاصة. ترسل Meta الـ Webhook إلى Ayrshare.
  </Step>

  <Step title="يطابق Ayrshare ويُرسل">
    يبحث المحرّك عن كل قاعدة تُطابق الحدث، ويتحقق من إزالة التكرار لكل إجراء وحدّك اليومي للرسائل الخاصة، ثم يُنفّذ كل إجراء. يُطبَّق تأخير عشوائي من 20 إلى 60 ثانية على إرسال الرسائل الخاصة للبقاء ضمن قواعد Instagram لمكافحة الرسائل غير المرغوبة.
  </Step>

  <Step title="افحص ما تم إطلاقه">
    يُعيد `GET /automations/:id/activity` سجل التدقيق — كل محاولة إرسال ونتائج كل إجراء وأي أخطاء.
  </Step>
</Steps>

## المشغّلات

يمكنك ربط ما يصل إلى **50 مشغّلًا** بأتمتة واحدة. كل مشغّل عبارة عن اتحاد مميّز على الحقل `type`؛ توجد الحقول الخاصة بالنوع على نفس المستوى. جميع المشغّلات مقتصرة على Instagram في الإصدار v1.

| النوع             | يُطلق عندما                                         | التهيئة                                                    |
| ----------------- | --------------------------------------------------- | ---------------------------------------------------------- |
| `comment_keyword` | يصل تعليق يتطابق مع كلمة مفتاحية على منشور محدّد    | `postId` (مطلوب)؛ `keywords` (مطلوب، إدخال واحد على الأقل) |
| `story_reply`     | يردّ مستخدم على ستوري عبر رسالة خاصة                | `storyId` (اختياري)                                        |
| `dm_reaction`     | يتفاعل مستخدم مع إحدى رسائلك الخاصة برمز تعبيري     | `emoji` (اختياري — اتركه فارغًا للإطلاق على أي رمز تعبيري) |
| `dm_keyword`      | يُرسل مستخدم رسالة خاصة يتطابق نصها مع كلمة مفتاحية | `keywords` (مطلوب، إدخال واحد على الأقل)                   |

يكون تطابق الكلمات المفتاحية **غير حساس لحالة الأحرف** ومطابقة كلمة كاملة. يستوفي الحدث مشغّلًا مُصفّى بالكلمات المفتاحية إذا كان يحتوي على أي كلمة من الكلمات المُهيَّأة. اترك `storyId` فارغًا في مشغّل الستوري للإطلاق على كل ستوري للحساب المتصل.

## الإجراءات

يمكنك ربط ما يصل إلى **50 إجراءً** بأتمتة واحدة. تُنفَّذ بالتتابع؛ ويُسجَّل كل نتيجة في صف النشاط.

| النوع          | التأثير                                                                                                                                 | التهيئة                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `send_dm`      | يُرسل رسالة خاصة على Instagram إلى المستخدم الذي أطلق القاعدة، باستخدام [رسالة قالبية](#template-variables).                            | `message` (مطلوب، قالبي)                                                          |
| `fire_webhook` | يُرسل POST مع سياق الأتمتة إلى عنوان URL الخاص بـ Webhook على مستوى حسابك (يُهيّأ عبر [`POST /hook/webhook`](/apis/webhooks/register)). | *(لا شيء — شكل الحمولة ثابت؛ راجع [أدناه](#fire_webhook-payload))*                |
| `send_email`   | يضع بريدًا إلكترونيًا في قائمة الانتظار عبر خط أنابيب بريد المنصة.                                                                      | `to` (مطلوب، بريد إلكتروني)؛ `subject` (اختياري، قالبي)؛ `message` (مطلوب، قالبي) |

### نافذة إزالة التكرار لكل إجراء

يقبل كل إجراء — بغض النظر عن نوعه — حقلًا اختياريًا إضافيًا على المستوى الأعلى باسم `dedupWindowMinutes` يتجاوز نافذة **7 أيام الافتراضية** لإزالة التكرار لكل مستلم لذلك الإجراء فقط.

* عيّنه إلى `0` **لتعطيل** إزالة التكرار كليًا لذلك الإجراء (نموذجي لـ `fire_webhook` / `send_email` حيث يتوقّع المستقبِل كل حدث).
* محدود بحد أقصى `525600` (سنة واحدة).

```json إجراء مع تجاوز إزالة تكرار لمدة 24 ساعة theme={"system"}
{
  "type": "send_dm",
  "message": "Thanks {{recipient_username}}!",
  "dedupWindowMinutes": 1440
}
```

### حمولة `fire_webhook`

عندما يُنفَّذ `fire_webhook` فإنه يُرسل POST بجسم JSON إلى عنوان Webhook على مستوى حسابك:

```json theme={"system"}
{
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "jane_doe",
  "keyword":           "LINK",
  "timestamp":         "2026-05-12T09:14:22.000Z"
}
```

يكون `recipientUsername` و`keyword` بقيمة `null` عندما لا يُوفّرها المشغّل (على سبيل المثال، `dm_keyword` لا يحمل اسم مستخدم في حمولة Meta؛ ولا يوجد كلمة مفتاحية لـ `story_reply`).

## متغيرات القالب

تدعم `send_dm.message` و`send_email.subject` و`send_email.message` استبدال `{{placeholder}}`. **تُرفض العلامات النائبة غير المعروفة عند الإنشاء/التحديث** (كخطأ تحقّق `473`) بحيث لا يُسرّب خطأ إملائي سلسلة `{{foo}}` الحرفية إلى رسالة موجّهة للعميل.

| العلامة النائبة          | تُحلّ إلى                                                         |
| ------------------------ | ----------------------------------------------------------------- |
| `{{recipient_username}}` | اسم مستخدم Instagram للمستخدم المتفاعل (عندما يحمله Webhook)      |
| `{{recipient_id}}`       | معرّف المشارك على Instagram (IGSID) للمستخدم المتفاعل             |
| `{{recipient_name}}`     | محجوز؛ يُحلّ إلى قيمة فارغة حتى يُوفّره مصدر إثراء مستقبلي        |
| `{{sender_username}}`    | اسم مستخدم Instagram المرتبط                                      |
| `{{sender_name}}`        | اسم العرض على Instagram المرتبط                                   |
| `{{comment_text}}`       | نص التعليق / الرسالة الخاصة / ردّ الستوري الذي أطلق المشغّل       |
| `{{comment_id}}`         | معرّف المنصة للتعليق / الرسالة التي أطلقت المشغّل                 |
| `{{comment_sent_at}}`    | ختم زمني بتنسيق ISO 8601 للحدث (عند توفره)                        |
| `{{matched_keyword}}`    | الكلمة المفتاحية المطابقة (أو نص الرمز التعبيري لـ `dm_reaction`) |
| `{{platform}}`           | معرّف المنصة (مثل `instagram`)                                    |
| `{{trigger_type}}`       | نوع المشغّل (مثل `comment_keyword`)                               |

<Note>
  **لا يوجد `sender_email` / `recipient_email`.** لم يتم كشفهما عمدًا — بريدك الإلكتروني للفوترة لا مكان مشروع له في رسالة خاصة إلى غريب، ولا توفّر Meta بريد المستلم الإلكتروني في أي Webhook خاص بـ IG. تجنُّب العلامات النائبة يمنع الكشف العرضي.
</Note>

قالب مثال:

```
Hey {{recipient_username}}, thanks for the comment "{{comment_text}}" — here is the link you wanted: https://example.com
```

## حدود المعدل والقيود

| الخطة      | الأتمتة النشطة (لكل ملف شخصي) | الحد اليومي للرسائل الخاصة (لكل حساب) |
| ---------- | ----------------------------- | ------------------------------------- |
| Business   | 10                            | 1,000                                 |
| Enterprise | 50                            | 5,000                                 |

يُحتسب الحد الأقصى للأتمتة النشطة **لكل [ملف تعريف مستخدم](/apis/profiles/overview)**، وليس لكل حساب أصلي. يحصل كل ملف شخصي ضمن حسابك على 10 لـ Business / 50 لـ Enterprise الخاصة به، لذا يمكن لحساب به عدة ملفات شخصية تشغيل هذا العدد من الأتمتة على كل منها. يُحصي الأتمتة النشطة ويُطبَّق على كل من `POST` (إنشاء) و`PUT` لإعادة التنشيط (`active: false → true`)، ويعرض كل منهما رمز الخطأ `470`. تحتاج إلى حد أعلى لكل ملف شخصي؟ [اتصل بالدعم](mailto:support@ayrshare.com) لرفعه لحسابك.

يُطبَّق **الحد اليومي للرسائل الخاصة** لكل حساب Ayrshare أصلي، ويُتشارك عبر جميع ملفاتك الشخصية، مع حد فرعي لكل ملف شخصي بحيث لا يستنزف ملف شخصي واحد مشغول حصة الحساب بأكمله. عند بلوغ حد الرسائل الخاصة، يُسجل صف النشاط الحالة `rate_limited` ولا تُرسَل الرسالة الخاصة.

القيود الهيكلية على أتمتة واحدة: **من 1 إلى 50 مشغّلًا**، **من 1 إلى 50 إجراءً**.

يُحدد Instagram نفسه الرسائل الخاصة بنحو 200/ساعة لكل حساب. يُوزّع المحرك الإرسال بتأخير عشوائي من 20 إلى 60 ثانية للبقاء بأمان تحت هذا الحد.

## حالات النشاط

يحمل صف في `GET /automations/:id/activity` حالة `status` على المستوى الأعلى بالإضافة إلى `status` لكل إجراء داخل `actionResults[]`:

| الحالة         | المعنى                                                                                 |
| -------------- | -------------------------------------------------------------------------------------- |
| `pending`      | مكتوب للتو؛ لم يلتقطه العامل بعد                                                       |
| `in_flight`    | العامل يُرسل حاليًا                                                                    |
| `sent`         | نجح كل إجراء                                                                           |
| `failed`       | فشل إجراء واحد على الأقل (ولم يواجه أي منهم خطأ مصادقة)                                |
| `auth_error`   | كان رمز الوصول إلى Instagram غير صالح؛ لم يُعَد المحاولة بإرسال الرسالة الخاصة         |
| `rate_limited` | تم بلوغ الحد اليومي للرسائل الخاصة (المستوى أو لكل ملف شخصي)؛ لم تُرسَل الرسالة الخاصة |
| `deduplicated` | أُطلق هذا الإجراء بالفعل لهذا المستلم داخل نافذة إزالة التكرار الخاصة به               |
| `skipped`      | أصبحت الأتمتة غير نشطة أو تم حذفها بين التوزيع والإرسال                                |

`pending` و`in_flight` مؤقتتان؛ وكل الحالات الأخرى نهائية.

## رموز الخطأ

تُعيد واجهة برمجة التطبيقات شكلين من الأخطاء:

* **أخطاء قواعد العمل** تحمل رمز `code` مرقّم للأتمتة (مثل `{ "action": "automation", "code": 469, ... }`).
* **أخطاء التحقق** — أي جسم طلب مشوّه (حقول مفقودة أو غير صالحة، متغيرات قوالب غير معروفة، مفاتيح غير مُعتمدة) — تُعاد كاستجابة واحدة **`473`** مع كائن `details` يُدرج الحقول المخالفة. `details` هي مخرجات المُحقِّق (`formErrors` بالإضافة إلى `fieldErrors`). فرِّق بناءً على `details`، وليس على رمز لكل حالة. في `fieldErrors`، تكون المفاتيح هي حقول الطلب على المستوى الأعلى (`triggers`، `actions`): يُبلَّغ عن مشكلة داخل إدخال محدد، مثل مشغّل يفتقر إلى `keywords`، تحت ذلك الحقل (مثل `triggers`)، بينما يحمل `formErrors` المشكلات على مستوى الكائن مثل المفاتيح غير المُعتمدة.

| الرمز | HTTP | المعنى                                                           |
| ----- | ---- | ---------------------------------------------------------------- |
| 468   | 403  | مطلوب خطة Business أو Enterprise                                 |
| 469   | 404  | لم يُعثر على الأتمتة (يُعاد أيضًا عندما لا يملكها المتصل)        |
| 470   | 429  | تم بلوغ الحد الأقصى للأتمتة النشطة لمستوى خطتك                   |
| 471   | 400  | لا يوجد حساب اجتماعي مرتبط على المنصة المطلوبة لهذا الملف الشخصي |
| 472   | 403  | الميزة غير متاحة بعد على حسابك — اتصل بنا للوصول المبكر          |
| 473   | 400  | فشل التحقق (جسم طلب مشوّه) — افحص `details`                      |

## ما لا تسمح به Meta

بعض القدرات المطلوبة عادةً غير مدعومة لأن Meta لا تسمح بها في واجهة Instagram العامة:

* **رسالة خاصة تلقائية للمتابعين الجدد.** لا يُصدر Instagram Webhook للمتابعة.
* **الرسائل الخاصة الأولى للغرباء.** تشترط Meta أن يبدأ المستلم الاتصال (تعليق، رد، رسالة خاصة، تفاعل) قبل أن يتمكّن حساب أعمال من مراسلته — وهو بالضبط ما يمثّله كل مشغّل مدعوم هنا.
* **الحملات الصادرة الجماعية.** تُطبَّق الحدود بالساعة للرسائل الخاصة وقواعد مكافحة الإساءة على مستوى المنصة.

## الاستخدام متعدد الملفات الشخصية

تحترم نقاط النهاية ترويسة `profileKey`. مرّر مفتاح ملف فرعي وستُنشأ/تُدار الأتمتة تحت ذلك الملف. تنقسم حدود المعدل بين الملفات الشخصية عبر حد فرعي لكل ملف شخصي بحيث لا يستنزف ملف شخصي كثير الحديث حصة الحساب الأصلي.

## الأسئلة الشائعة

<AccordionGroup>
  <Accordion title="هل يمكنني الإطلاق عند وجود متابع جديد؟">
    لا. لا يُصدر Instagram Webhook للمتابعة، ولا تسمح Meta لتطبيقات الأطراف الثالثة بإرسال رسالة خاصة إلى مستخدم لم يبدأ محادثة. كل مشغّل مدعوم (`comment_keyword`، `story_reply`، `dm_reaction`، `dm_keyword`) يستوفي شرط "المستخدم اتصل بك أولًا".
  </Accordion>

  <Accordion title="ماذا يحدث إذا كان رمز وصولي غير صالح عند إطلاق أتمتة؟">
    يُسجل صف النشاط الحالة `auth_error` ولا يُعاد محاولة إرسال الرسالة الخاصة. أعِد ربط الحساب، ثم سيُطلق التفاعل المطابق التالي بشكل طبيعي.
  </Accordion>

  <Accordion title="لماذا يوجد تأخير قبل إرسال الرسالة الخاصة؟">
    يُجدوَل كل إرسال `send_dm` بعد 20 إلى 60 ثانية من التفاعل ليبدو طبيعيًا لأنظمة Instagram لمكافحة الرسائل غير المرغوبة. لا يوجد تأخير عشوائي لإجراءات `fire_webhook` و`send_email`. الختم الزمني `created` في صف النشاط هو وقت تطابق المشغّل؛ و`completedAt` هو وقت انتهاء الإرسال.
  </Accordion>

  <Accordion title="هل تُحفظ صفوف النشاط إلى الأبد؟">
    تُحفظ صفوف النشاط إلى أجل غير مسمى للتتبع والتحليلات. تُعيد نقطة نهاية `GET /automations/:id/activity` صفوف آخر 30 يومًا لأغراض الأداء. (يستخدم حارس إزالة التكرار نافذته الخاصة لكل إجراء — بشكل افتراضي 7 أيام — وهي غير مرتبطة بفترة استرجاع النشاط.)
  </Accordion>

  <Accordion title="هل يؤدي حذف أتمتة إلى إزالة سجل نشاطها؟">
    لا. الحذف هو حذف ناعم: يُوسَم السجل الرئيسي بـ `deleted`، ولا تحدث عمليات إرسال جديدة، لكن تبقى صفوف النشاط التاريخية قابلة للقراءة عبر نقطة نهاية النشاط.
  </Accordion>
</AccordionGroup>

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

* [`POST /automations`](/apis/automations/create-automation) — إنشاء أتمتة جديدة
* [`GET /automations`](/apis/automations/list-automations) — سرد الأتمتة الخاصة بك
* [`GET /automations/:id`](/apis/automations/get-automation) — جلب أتمتة واحدة مع مشغّلاتها وإجراءاتها
* [`PUT /automations/:id`](/apis/automations/update-automation) — تحديث جزئي؛ إيقاف مؤقت عبر `active: false`
* [`DELETE /automations/:id`](/apis/automations/delete-automation) — حذف ناعم
* [`GET /automations/:id/activity`](/apis/automations/get-activity) — سجل تدقيق الإرسال مع ترقيم صفحات بالمؤشر