> ## 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.
# Огляд Automations API
> Автоматизації Instagram на основі engagement-тригерів — надсилайте DM, викликайте webhook або надсилайте email, коли кінцевий користувач залишає коментар, відповідає на історію, реагує на DM або надсилає DM
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
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.
{maxPackRequired && window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
Max Pack required
}
;
};
**Beta.** Automations API перебуває в бета-версії, і ми активно збираємо відгуки. Ендпоінти, payload'и та ліміти можуть змінюватися в міру ітерацій. Будь ласка, надсилайте відгуки та звіти про помилки в підтримку, щоб ми могли пріоритизувати правильні покращення.
Ендпоінти Automations дозволяють визначати правила, які автоматично реагують на вхідну engagement-активність Instagram. Кожна автоматизація поєднує один або кілька **тригерів** (подія, що спрацьовує) з однією чи кількома **діями** (що відбувається при спрацюванні). Одне правило може прослуховувати кілька тригерів і виконувати кілька дій — викликати webhook у ваш аналітичний конвеєр І надсилати DM з тієї самої взаємодії.
Двигун повністю працює всередині політики Meta (без DM за підписку, без першого повідомлення незнайомцям, без масової вихідної розсилки) і успадковує обмеження швидкості Ayrshare на акаунт, дедуплікацію на отримувача та ідемпотентне приймання webhook'ів.
## Як це працює
`POST /automations` з бажаними тригерами й діями. Автоматизація активується миттєво.
Хтось коментує ваш допис, відповідає на вашу історію, надсилає DM або реагує на DM. Meta доставляє webhook в Ayrshare.
Двигун знаходить кожне правило, що відповідає події, перевіряє дедуплікацію на дію та ваш добовий ліміт DM, а потім виконує кожну дію. До надсилання DM застосовується jitter 20–60 секунд, щоб залишатися в межах антиспам-евристик Instagram.
`GET /automations/:id/activity` повертає журнал аудиту — кожну спробу диспетчеризації, результати кожної дії та будь-які помилки.
## Тригери
До однієї автоматизації можна приєднати до **50 тригерів**. Кожен тригер є discriminated union по полю `type`; поля, специфічні для типу, розташовані на тому ж рівні. У v1 усі тригери працюють лише для Instagram.
| Тип | Спрацьовує, коли | Конфігурація |
| ----------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `comment_keyword` | Коментар, що збігається з ключовим словом, з'являється під певним дописом | `postId` (обов'язково); `keywords` (обов'язково, ≥1 запис) |
| `story_reply` | Користувач відповідає на історію через DM | `storyId` (необов'язково) |
| `dm_reaction` | Користувач реагує на один з ваших DM емодзі | `emoji` (необов'язково — пропустіть, щоб спрацьовувало на будь-який емодзі) |
| `dm_keyword` | Користувач надсилає DM, текст якого відповідає ключовому слову | `keywords` (обов'язково, ≥1 запис) |
Зіставлення ключових слів — **регістронезалежне** та по цілому слову. Подія задовольняє тригер із фільтром ключових слів, якщо містить будь-яке з налаштованих ключових слів. Пропустіть `storyId` у тригері історії, щоб він спрацьовував на кожну історію підключеного акаунта.
## Дії
До однієї автоматизації можна приєднати до **50 дій**. Вони виконуються послідовно; кожен результат записується у рядок активності.
| Тип | Ефект | Конфігурація |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `send_dm` | Надсилає Instagram DM користувачеві, який спричинив спрацювання правила, використовуючи [шаблонне повідомлення](#template-variables). | `message` (обов'язково, шаблонне) |
| `fire_webhook` | Виконує POST-запит із контекстом автоматизації на webhook-URL рівня акаунта (налаштуйте через [`POST /hook/webhook`](/apis/webhooks/register)). | *(немає — форма payload'у зафіксована; див. [нижче](#fire_webhook-payload))* |
| `send_email` | Ставить у чергу лист через поштовий конвеєр платформи. | `to` (обов'язково, email); `subject` (необов'язково, шаблонне); `message` (обов'язково, шаблонне) |
### Вікно дедуплікації на дію
Кожна дія — незалежно від типу — додатково приймає необов'язкове поле верхнього рівня `dedupWindowMinutes`, яке перевизначає **типове 7-денне** вікно дедуплікації на отримувача лише для цієї дії.
* Установіть `0`, щоб **повністю вимкнути** дедуплікацію для цієї дії (типово для `fire_webhook` / `send_email`, де отримувач очікує кожну подію).
* Обмеження — `525600` (один рік).
```json Action with a 24h dedup override theme={"system"}
{
"type": "send_dm",
"message": "Thanks {{recipient_username}}!",
"dedupWindowMinutes": 1440
}
```
### Payload `fire_webhook`
Коли виконується `fire_webhook`, він надсилає POST з JSON-тілом на webhook-URL рівня акаунта:
```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` не несе username у payload'і Meta; `story_reply` не має ключового слова).
## Змінні шаблону
`send_dm.message`, `send_email.subject` і `send_email.message` підтримують підстановку `{{placeholder}}`. **Невідомі placeholder'и відхиляються під час створення/оновлення** (як помилка валідації `473`), тож помилка друку ніколи мовчки не пропустить дослівний `{{foo}}` у повідомлення, яке бачить клієнт.
| Placeholder | Розгортається у |
| ------------------------ | --------------------------------------------------------------------------------------------- |
| `{{recipient_username}}` | Instagram-нік користувача, що взаємодіє (коли webhook його несе) |
| `{{recipient_id}}` | Instagram participant ID (IGSID) користувача, що взаємодіє |
| `{{recipient_name}}` | Зарезервовано; поки що розгортається в порожній рядок до появи майбутнього джерела збагачення |
| `{{sender_username}}` | Ваш підключений Instagram username |
| `{{sender_name}}` | Ваше підключене Instagram-ім'я для відображення |
| `{{comment_text}}` | Текст коментаря / DM / відповіді на історію, що спричинив тригер |
| `{{comment_id}}` | Platform-id коментаря / повідомлення, що спрацював |
| `{{comment_sent_at}}` | ISO 8601 timestamp події (коли доступно) |
| `{{matched_keyword}}` | Ключове слово, що збіглося (або рядок емодзі для `dm_reaction`) |
| `{{platform}}` | Ідентифікатор платформи (наприклад, `instagram`) |
| `{{trigger_type}}` | Тип тригера (наприклад, `comment_keyword`) |
**Немає `sender_email` / `recipient_email`.** Вони навмисно не надаються — вашому email для білінгу немає легітимного місця в DM незнайомій людині, і Meta не надає email отримувача в жодному IG-webhook. Відсутність placeholder'ів запобігає випадковому розкриттю.
Приклад шаблону:
```
Hey {{recipient_username}}, thanks for the comment "{{comment_text}}" — here is the link you wanted: https://example.com
```
## Обмеження швидкості та ліміти
| План | Активні автоматизації (на профіль) | Добовий ліміт DM (на акаунт) |
| ---------- | ---------------------------------- | ---------------------------- |
| Business | 10 | 1 000 |
| Enterprise | 50 | 5 000 |
Ліміт активних автоматизацій рахується **на [User Profile](/apis/profiles/overview)**, а не на батьківський акаунт. Кожен профіль вашого акаунта отримує свої Business 10 / Enterprise 50, тож акаунт із багатьма профілями може запускати відповідну кількість автоматизацій у кожному з них. Він рахує активні автоматизації та застосовується як при `POST` (створення), так і при повторній активації через `PUT` (`active: false → true`), у кожному випадку повертаючи код помилки `470`. Потрібен вищий ліміт на профіль? [Зв'яжіться з підтримкою](mailto:support@ayrshare.com), щоб його підвищили для вашого акаунта.
**Добовий ліміт DM** застосовується на батьківський акаунт Ayrshare, спільно для всіх ваших профілів, з підлімітом на профіль, щоб один активний профіль не вичерпав квоту всього акаунта. Коли досягнуто ліміт DM, рядок активності отримує статус `rate_limited` і DM не надсилається.
Структурні ліміти на одну автоматизацію: **1–50 тригерів**, **1–50 дій**.
Сам Instagram обмежує DM приблизно 200/годину на акаунт. Двигун виконує диспетчеризацію з jitter 20–60 секунд, щоб залишатися в безпечних межах.
## Статуси активності
Рядок у `GET /automations/:id/activity` має статус верхнього рівня `status` плюс статус кожної дії всередині `actionResults[]`:
| Статус | Значення |
| -------------- | --------------------------------------------------------------------------- |
| `pending` | Щойно записано; воркер ще не забрав завдання |
| `in_flight` | Воркер зараз виконує диспетчеризацію |
| `sent` | Усі дії успішні |
| `failed` | Принаймні одна дія не вдалася (і жодна не спричинила auth-помилку) |
| `auth_error` | Access-токен Instagram недійсний; DM не було повторено |
| `rate_limited` | Досягнуто добовий ліміт DM (плановий або на профіль); DM не надіслано |
| `deduplicated` | Ця дія вже спрацьовувала для цього отримувача в межах вікна дедуплікації |
| `skipped` | Автоматизацію було деактивовано або видалено між fan-out і диспетчеризацією |
`pending` і `in_flight` — перехідні; усі інші — термінальні.
## Коди помилок
API повертає два види помилок:
* **Бізнес-правила** несуть номерний `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 API:
* **Автоматичне DM новим підписникам.** Instagram не публікує webhook на підписку.
* **Перше DM-повідомлення незнайомцям.** Meta вимагає, щоб отримувач ініціював контакт (коментар, відповідь, DM, реакція), перш ніж бізнес-акаунт зможе надіслати йому повідомлення — саме це й представляє кожен підтримуваний тут тригер.
* **Масові вихідні кампанії.** Погодинні ліміти DM та антифрод-евристики застосовуються на рівні платформи.
## Використання з кількома профілями
Ендпоінти враховують заголовок `profileKey`. Передайте ключ дочірнього профілю — і автоматизація буде створена/керована в межах цього профілю. Обмеження швидкості поділяються між профілями через підліміт на профіль, щоб один активний профіль не вичерпав квоту батьківського акаунта.
## FAQ
Ні. Instagram не публікує webhook на підписку, і Meta не дозволяє стороннім застосункам надсилати DM користувачеві, який не ініціював розмову. Кожен підтримуваний тригер (`comment_keyword`, `story_reply`, `dm_reaction`, `dm_keyword`) задовольняє вимогу «користувач звернувся до вас першим».
Рядок активності отримує статус `auth_error`, і DM не повторюється. Перепідключіть акаунт — і наступна відповідна взаємодія спрацює нормально.
Кожне диспетчерування `send_dm` планується на 20–60 секунд після взаємодії, щоб виглядати органічно для антиспам-систем Instagram. Дії `fire_webhook` і `send_email` НЕ мають jitter. Timestamp `created` у рядку активності — це коли тригер збігся; `completedAt` — коли диспетчеризація завершилася.
Рядки активності зберігаються безстроково для трасування та аналітики. Ендпоінт `GET /automations/:id/activity` повертає рядки за останні 30 днів для продуктивності. (Захист від дедуплікації використовує власне вікно на дію — типово 7 днів — яке не пов'язане з періодом перегляду активності.)
Ні. Видалення є soft-delete: основний рядок позначається як `deleted`, нові диспетчеризації не виконуються, але історичні рядки активності залишаються доступними для читання через ендпоінт активності.
## Ендпоінти
* [`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) — soft-delete
* [`GET /automations/:id/activity`](/apis/automations/get-activity) — журнал аудиту диспетчеризацій із пагінацією через курсор