Огляд Automations API

Beta. Automations API перебуває в бета-версії, і ми активно збираємо відгуки. Ендпоінти, payload’и та ліміти можуть змінюватися в міру ітерацій. Будь ласка, надсилайте відгуки та звіти про помилки в підтримку, щоб ми могли пріоритизувати правильні покращення.

Ендпоінти Automations дозволяють визначати правила, які автоматично реагують на вхідну engagement-активність в Instagram і на DM, надіслані сторінкам Facebook. Кожна автоматизація поєднує один або кілька тригерів (подія, що спрацьовує) з однією чи кількома діями (що відбувається при спрацюванні). Одне правило може прослуховувати кілька тригерів і виконувати кілька дій — викликати webhook у ваш аналітичний конвеєр І надсилати DM з тієї самої взаємодії. Двигун реагує лише на engagement-активність, яку користувач спрямовує до вас (коментар, відповідь на історію, DM або реакція) — він ніколи не надсилає DM за підпискою, перших DM незнайомцям чи масової вихідної розсилки — і успадковує обмеження швидкості Ayrshare на акаунт, дедуплікацію на отримувача та ідемпотентне приймання webhook’ів.

sent означає, що Meta прийняла повідомлення, а не те, що отримувач його отримав. В Instagram доставка зрештою визначається параметром Message requests отримувача: якщо він не дозволяє запити повідомлень від усіх, Meta повертає успішну відповідь і тихо відкидає повідомлення, і це невидимо на кожному рівні API. Навіть доставлений DM, спричинений коментарем, надходить як запит повідомлення, який отримувач має прийняти (якщо між двома акаунтами вже не існує розмови). Див. Automation DM Sent but Not Delivered для повного пояснення.

Як це працює

Створіть автоматизацію

POST /automations з бажаними тригерами й діями. Автоматизація активується миттєво.

Кінцевий користувач взаємодіє

Хтось коментує ваш допис, відповідає на вашу історію, надсилає DM або реагує на DM. Meta доставляє webhook в Ayrshare.

Ayrshare зіставляє та диспетчеризує

До взаємодії застосовується jitter 20–60 секунд, щоб залишатися в межах антиспам-евристик Instagram. Після цього двигун знаходить кожне правило, що відповідає події, перевіряє дедуплікацію на дію та ваш добовий ліміт DM і виконує кожну дію.

Перегляньте, що спрацювало

GET /automations/:id/activity повертає журнал аудиту — кожну спробу диспетчеризації, результати кожної дії та будь-які помилки.

Тригери

До однієї автоматизації можна приєднати до 50 тригерів. Кожен тригер є discriminated union по полю type; поля, специфічні для типу, розташовані на тому ж рівні. У стовпці Платформи вказано, де доступний кожен тригер; що потрібно для Facebook, див. у розділі Сторінки Facebook.

Тип	Спрацьовує, коли	Платформи	Конфігурація
`comment_keyword`	Коментар, що збігається з ключовим словом, з’являється під дописом або reel	`instagram`	`postId` (обов’язково — ID допису або `"all"`); `keywords` (обов’язково, ≥1 запис)
`story_reply`	Користувач відповідає на історію через DM	`instagram`	`storyId` (необов’язково — ID історії або `"all"`)
`dm_reaction`	Користувач реагує на один з ваших DM емодзі	`instagram`, `facebook`	`emoji` (необов’язково — пропустіть, щоб спрацьовувало на будь-який емодзі)
`dm_keyword`	Користувач надсилає DM, текст якого відповідає ключовому слову	`instagram`, `facebook`	`keywords` (обов’язково, ≥1 запис)

Зіставлення ключових слів — регістронезалежне та по цілому слову. Подія задовольняє тригер із фільтром ключових слів, якщо містить будь-яке з налаштованих ключових слів.

Постійно чинні правила з `"all"`

Установіть postId (або storyId) у дослівний рядок "all" у нижньому регістрі, щоб правило спрацьовувало на кожен допис, reel чи історію підключеного акаунта, а не на один конкретний елемент контенту. Саме це потрібно для правила, яке має продовжувати працювати в міру публікації нового контенту, без API-виклику на кожен допис:

{
  "type": "comment_keyword",
  "postId": "all",
  "keywords": ["LINK", "INFO"]
}

Значення має бути точно "all". Варіант на кшталт "ALL" або " all" відхиляється з помилкою валідації, а не зберігається як ID допису, який ніколи не збіжиться. "all" ніколи не поширюється за межі підключеного акаунта — правило одного профілю не може спрацювати на контенті іншого профілю. Ваш добовий ліміт DM і правила надсилання, прив’язані до взаємодії, застосовуються точно так само, як і для правила з одним дописом.

Дедуплікація рахується на автоматизацію та отримувача, а не на допис. У правилі з "all" користувач, який коментує ключове слово під двома різними дописами в межах вікна дедуплікації (типово 7 днів), отримує DM лише один раз; друга активність фіксується як deduplicated. Менше значення dedupWindowMinutes лише скорочує це вікно; воно не робить дедуплікацію окремою для кожного допису. Установлення 0 вимикає дедуплікацію, тож кожен відповідний коментар надсилає DM, включно з повторними коментарями під тим самим дописом.

У тригерах історій пропуск storyId поводиться так само, як "all". Віддавайте перевагу "all" — воно явно висловлює намір, а пропуск буде виведено з ужитку в майбутньому релізі із завчасним анонсом на сторінці Upcoming API Changes.

Сторінки Facebook

Установіть platform у значення facebook, щоб запускати автоматизацію на сторінці Facebook, пов’язаній із профілем. DM надсилаються від сторінки через Messenger.

Тригери: dm_keyword і dm_reaction. Тригери коментарів та історій поки що працюють лише для Instagram, і автоматизацію Facebook, яка використовує один із них, буде відхилено з помилкою валідації.
Messaging: для профілю має бути активовано Messaging для Facebook, так само як для надсилання DM у Facebook через Messages API.
Отримувач: {{recipient_id}} — це Page-scoped ID (PSID) користувача. {{recipient_username}} порожній, оскільки webhook Messenger не містять username.

{
  "platform": "facebook",
  "name": "Price list on request",
  "triggers": [{ "type": "dm_keyword", "keywords": ["price"] }],
  "actions": [{ "type": "send_dm", "message": "Here is our price list: https://example.com/prices" }]
}

Дії

До однієї автоматизації можна приєднати до 50 дій. Вони виконуються послідовно; кожен результат записується у рядок активності.

Тип	Ефект	Конфігурація
`send_dm`	Надсилає DM (в Instagram або через Messenger від вашої сторінки Facebook) користувачеві, який спричинив спрацювання правила, використовуючи шаблонне повідомлення або текст, який ви генеруєте для кожного спрацювання.	`message` (обов’язково, шаблонне); `messageUrl` (необов’язково); `timeoutMs` (необов’язково)
`fire_webhook`	Виконує POST-запит із контекстом автоматизації на webhook-URL рівня акаунта (налаштуйте через `POST /hook/webhook`).	`sendCompletedEvent` (необов’язково, boolean — також надсилає `automation.completed`). Форма payload’у зафіксована; див. нижче
`send_email`	Ставить у чергу лист через поштовий конвеєр платформи.	`to` (обов’язково, email); `subject` (необов’язково, шаблонне); `message` (обов’язково, шаблонне)

Вікно дедуплікації на дію

Кожна дія — незалежно від типу — додатково приймає необов’язкове поле верхнього рівня dedupWindowMinutes, яке перевизначає типове 7-денне вікно дедуплікації на отримувача лише для цієї дії.

Установіть 0, щоб повністю вимкнути дедуплікацію для цієї дії (типово для fire_webhook / send_email, де отримувач очікує кожну подію).
Обмеження — 525600 (один рік).

Action with a 24h dedup override

{
  "type": "send_dm",
  "message": "Thanks {{recipient_username}}!",
  "dedupWindowMinutes": 1440
}

Динамічний вміст повідомлення

Типово send_dm надсилає той самий message кожному, хто спричинив спрацювання правила. Від людини до людини змінюються лише placeholder’и на кшталт {{recipient_username}}. Установіть messageUrl у дії, і тоді DM для кожної людини писатиме ваш власний сервер: щоразу, коли правило збігається, ми запитуємо ваш ендпоінт, що сказати, а потім надсилаємо його відповідь як DM. Приклад. Ваше правило відповідає кожному, хто коментує “LINK” під дописом, а messageUrl вказує на ваш сервер. Коли Ava коментує “LINK please!”:

Ми надсилаємо POST із деталями на ваш messageUrl: хто коментував ("recipientUsername": "ava"), що саме написав і під яким дописом.
Ваш сервер пише відповідь для Ava, наприклад із посиланням для відстеження, створеним саме для неї, і відповідає { "message": "Hi ava, here's your link: https://example.com/r/12345" }.
Ми надсилаємо цей текст Ava як DM — точно так, як ви його написали.

Якщо ваш сервер не відповідає протягом timeoutMs, повертає помилку або повертає щось, чого ми не можемо використати, ми натомість надсилаємо Ava звичайний message дії, тож вона все одно отримає відповідь. Додайте його до дії send_dm так:

send_dm with messageUrl

{
  "type": "send_dm",
  "messageUrl": "https://yourapp.example.com/automations/message",
  "timeoutMs": 3000,
  "message": "Thanks for commenting! Here is the link: https://example.com"
}

messageUrl — це адреса, за якою ми запитуємо текст. message, як і раніше, обов’язковий і слугує запасним варіантом: він ніколи не надсилається на ваш сервер, а ми надсилаємо його як DM щоразу, коли ваш сервер не відповідає вчасно, повертає помилку або повертає щось, чого ми не можемо використати (див. попередження нижче). timeoutMs необов’язковий (типово 3000, максимум 5000). Що ми надсилаємо на ваш ендпоінт. POST з таким JSON-тілом:

Callback request body

{
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "ava",
  "keyword":           "LINK",
  "activityId":        "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:17912345678901234",
  "actionId":          "act_dm_1",
  "eventId":           "comment.received:17912345678901234",
  "commentId":         "17912345678901234",
  "commentText":       "LINK please!",
  "postId":            "17998765432109876",
  "storyId":           null,
  "timestamp":         "2026-05-12T09:14:22.000Z",
  "timeStamp":         1778577262
}

Поле	Значення
`automationId`, `triggerId`, `trigger`, `platform`	Яка автоматизація і який тригер спрацювали, як у payload’і `fire_webhook`
`recipientId`, `recipientUsername`	Людина, якій надсилається DM. `recipientUsername` має значення `null`, коли тригер його не містить (наприклад, `dm_keyword`)
`keyword`	Ключове слово, що збіглося, або `null`
`activityId`	Запис активності для цього спрацювання, щоб ви могли зіставити його з `GET /automations/:id/activity`
`actionId`	Яка дія `send_dm` робить запит; збігається з `actionResults[].actionId`. Дає змогу одному ендпоінту обслуговувати кілька дій `send_dm` в одній автоматизації
`eventId`	Наш ID взаємодії, яка спричинила спрацювання
`commentId`	ID коментаря Instagram для тригерів коментарів; `null` для тригерів DM та історій
`commentText`	Текст, що збігся: коментар, DM або емодзі реакції. `null`, коли його немає (наприклад, `story_reply`)
`postId`, `storyId`	Допис або історія, на яких відбулася взаємодія, або `null`
`timestamp`	Коли ми зробили запит, ISO 8601
`timeStamp`	Той самий момент як Unix-час у секундах. Присутній лише тоді, коли callback підписано, як і в наших webhook’ах

Якщо ви зареєстрували секрет webhook’а, тіло підписується тим самим секретом, що й ваші webhook’и automations, і в той самий спосіб: X-Authorization-Content-SHA256 — це HMAC-SHA256 необробленого тіла, а X-Authorization-Timestamp містить timeStamp тіла. Код перевірки, який ви вже використовуєте для наших webhook’ів, працює без змін. Якщо секрет зареєстровано, але в цей момент ми не можемо його прочитати, ми не надсилаємо callback без підпису; натомість ми надсилаємо ваш шаблон message. Куди він може вказувати. messageUrl має бути публічною HTTPS-адресою. URL, що резолвиться в приватну, loopback, link-local адресу або адресу хмарних метаданих, відхиляється, а переспрямування не виконуються — відповідь 3xx вважається невдачею. В обох випадках натомість надсилається шаблон. Що повертає ваш ендпоінт. Поверніть 200 з JSON-тілом розміром не більше 16 KB, що містить рядок message довжиною від 1 до 1000 символів:

{ "message": "Hi ava — grabbed that link for you: https://example.com/r/12345" }

Ваш текст надсилається дослівно. Підстановка {{placeholder}} до нього не застосовується, тож дослівний {{ у згенерованому вами тексті дійде до отримувача саме так, як написано.

message залишається обов’язковим, і це не прикраса. Якщо ваш ендпоінт перевищує час очікування, повертає не-2xx, повертає тіло, яке ми не можемо використати, або його тимчасово вимкнув circuit breaker після повторних невдач, ми натомість надсилаємо відрендерений шаблон message. Це надсилання все одно може завершитися невдачею, наприклад якщо шаблон рендериться порожнім (див. нижче) або Instagram його відхиляє. Ми ніколи не повторюємо callback — повтор загрожує тим, що отримувач отримає два повідомлення.

timeoutMs типово дорівнює 3000. Максимум — 5000: більше значення відхиляється з помилкою валідації під час створення або оновлення автоматизації. Він охоплює весь обмін, включно з читанням тіла вашої відповіді. Врахуйте це: DM надсилається після того, як ваш ендпоінт відповість, тож повільний ендпоінт затримує повідомлення. Перевірте, яким шляхом пішло спрацювання, у GET /automations/:id/activity. Запис send_dm в actionResults[] містить messageSource, щойно текст DM визначено, зокрема й тоді, коли надсилання потім завершилося невдачею. Він відсутній, коли дія зупинилася раніше, наприклад DM на ваш власний акаунт зі статусом skipped або дія зі статусом deduplicated:

`messageSource`	Значення
`template`	`messageUrl` не налаштовано; використано статичний `message`
`callback`	Ваш ендпоінт відповів, і використано його текст
`fallback`	`messageUrl` було встановлено, але його не вдалося використати; натомість використано `message`

messageSource вказує, з якого тексту було сформовано DM, а не чи його доставлено. Для цього дивіться status запису. Сам по собі запасний варіант не робить дію невдалою: коли DM із шаблоном доставлено, запис має статус sent, а причина, з якої callback не було використано, міститься в errorDetails. Якщо DM із шаблоном потім теж не вдається надіслати, запис має статус failed, а errorDetails містить помилку надсилання, за якою йде причина щодо callback. Стежте за цим: інакше callback, який не спрацьовує при кожному спрацюванні правила, виглядає точнісінько як той, що працює. Подбайте, щоб ваш message можна було надіслати й окремо. Якщо для отримувача він рендериться порожнім, наприклад лише {{recipient_username}} у тригері DM, який не містить username, а текст вашого callback не використано, DM не надсилається, і дія має статус failed із причиною в errorDetails.

Webhook-події

На webhook-дію automations, яку ви реєструєте через POST /hook/webhook, доставляються дві події. Обидві несуть поле type — розгалужуйтеся за ним, перш ніж читати будь-що інше.

`type`	Надсилається, коли
`automation.triggered`	Виконується дія `fire_webhook` правила
`automation.completed`	Диспетчеризація завершилася, з її результатом

automation.completed типово вимкнено. Увімкніть його для автоматизації, встановивши "sendCompletedEvent": true у її дії fire_webhook. Інакше воно залишається вимкненим, тож отримувач, розрахований на один payload на спрацювання, і далі отримує рівно один. automation.triggered не є записом кожного збігу: воно надсилається лише тоді, коли виконується сам fire_webhook, тож збіг, що завершився як rate_limited або deduplicated, породжує лише automation.completed. Жодна з подій не надсилається для автоматизації, яку було деактивовано або видалено до виконання диспетчеризації.

`automation.triggered`

{
  "type":              "automation.triggered",
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "jane_doe",
  "keyword":           "LINK",
  "activityId":        "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:17912345678901234",
  "actionId":          "act_wh_1",
  "eventId":           "comment.received:17912345678901234",
  "commentId":         "17912345678901234",
  "commentText":       "LINK please",
  "postId":            "17895695668004550",
  "storyId":           null,
  "timestamp":         "2026-05-12T09:14:22.000Z"
}

activityId — це рядок, який повертає GET /automations/:id/activity, тож ви можете точно поєднати їх, замість зіставлення за recipientId + triggerId + keyword — що неоднозначно, коли кілька людей одночасно коментують те саме ключове слово. actionId — це дія fire_webhook, яка надіслала подію, і збігається з actionResults[].actionId; вона розрізняє дві дії fire_webhook в одному правилі. Поля, які тригер не заповнює, мають значення null, а не пропускаються, тож форма стабільна. recipientUsername має значення null для dm_keyword, dm_reaction та story_reply, оскільки payload Meta не містить username. commentId встановлюється лише для comment_keyword і story_comment, postId — лише для comment_keyword, а storyId — лише для тригерів історій. story_reply не має keyword. Для dm_keyword commentText — це текст DM; для dm_reaction і commentText, і keyword є емодзі реакції.

`automation.completed`

Надсилається лише тоді, коли автоматизація вмикає це у своїй дії fire_webhook:

fire_webhook action with the outcome event on

{
  "type": "fire_webhook",
  "sendCompletedEvent": true
}

{
  "type":         "automation.completed",
  "automationId": "auto_9xKp2Lm4nQ",
  "triggerId":    "trg_a1b2c3",
  "trigger":      "comment_keyword",
  "platform":     "instagram",
  "recipientId":  "17841401234567890",
  "activityId":   "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:17912345678901234",
  "eventId":      "comment.received:17912345678901234",
  "status":       "sent",
  "actionResults": [
    { "actionId": "act_dm_1", "type": "send_dm",      "status": "sent", "errorDetails": null, "messageSource": "callback" },
    { "actionId": "act_wh_1", "type": "fire_webhook", "status": "sent", "errorDetails": null }
  ],
  "errorDetails": null,
  "timestamp":    "2026-05-12T09:14:58.000Z"
}

status і кожен actionResults[].status використовують ті самі значення, що й журнал активності — sent, failed, rate_limited, deduplicated, skipped, auth_error — тож у звичайному випадку ви дізнаєтеся, як завершилася диспетчеризація, без опитування. Втім, доставка цієї події виконується за принципом best-effort: якщо процес зупиниться між записом результату та постановкою події в чергу, її не буде надіслано. Журнал активності є джерелом істини, тож якщо вам потрібен кожен результат, звіряйтеся з GET /automations/:id/activity для будь-якого activityId, який не повідомив результату. Результат send_dm також містить messageSource, як і в журналі активності: template, callback або fallback, тож ви можете помітити messageUrl, який постійно переходить на запасний варіант, без опитування. Зіставляйте результати з вашими налаштованими діями за actionId, а не за позицією — дві дії одного типу можна розрізнити лише так. actionResults порожній у трьох випадках, у кожному з причиною у верхньорівневому errorDetails, коли вона є: rate_limited (досягнуто ваш добовий ліміт), deduplicated (кожна дія була в межах свого вікна дедуплікації) та failed після того, як диспетчеризацію було повторено максимальну кількість разів без завершення. В останньому випадку деякі дії могли вже виконатися, тож DM міг бути надісланий, а automation.triggered могло вже бути надіслано. Доставка webhook’ів виконується за принципом at-least-once, тож та сама подія іноді може надійти двічі, а диспетчеризація, яку повторюють, може надіслати automation.triggered знову з новим hookId. Ніколи не дедуплікуйте за hookId. Ключуйте кожен тип події окремо, щоб обробка однієї ніколи не придушувала іншу: automation.completed — за activityId (кожна активність має один результат), а automation.triggered — за activityId плюс actionId (одна на кожну дію fire_webhook). Дві події доставляються незалежно, тож automation.completed іноді може надійти раніше за automation.triggered.

Якщо webhook не зареєстровано

fire_webhook надсилає POST на дію automations, зареєстровану в профілі, з відкатом на ваш Primary Profile. Відкату на іншу дію, як-от messages, немає. Якщо не існує жодної з цих реєстрацій, automation.triggered не відкидається мовчки: дія фіксується в рядку активності як failed, з причиною в actionResults[].errorDetails. (automation.completed теж нікуди надіслати, і воно не фіксується.) Загальний статус диспетчеризації далі дотримується звичайного пріоритету: auth_error, якщо будь-яка дія спричинила auth-помилку, інакше sent, якщо будь-яку дію було прийнято, інакше failed. Тож відсутній webhook враховується у статистиці невдач автоматизації лише тоді, коли ніщо інше в правилі не надіслалося; коли інша дія таки надіслалася (і жодна не спричинила auth-помилку), диспетчеризація завершується як sent, а невдалий webhook видно лише в actionResults[]. Результат fire_webhook зі значенням sent означає, що подію було поставлено в чергу для доставки на ваш URL, а не те, що ваш ендпоінт її прийняв. Далі доставка повторюється за власним розкладом.

Змінні шаблону

send_dm.message, send_email.subject і send_email.message підтримують підстановку {{placeholder}}. Невідомі placeholder’и відхиляються під час створення/оновлення (як помилка валідації 473), тож помилка друку ніколи мовчки не пропустить дослівний {{foo}} у повідомлення, яке бачить клієнт.

Placeholder	Розгортається у
`{{recipient_username}}`	Instagram-нік користувача, що взаємодіє, у тригерах коментарів. Порожній у тригерах DM і відповідей на історії та завжди у Facebook
`{{recipient_id}}`	ID користувача, що взаємодіє: Instagram-scoped ID (IGSID) в Instagram, Page-scoped ID (PSID) у Facebook
`{{recipient_name}}`	Зарезервовано; поки що розгортається в порожній рядок до появи майбутнього джерела збагачення
`{{sender_username}}`	Зарезервовано; наразі на всіх платформах розгортається в порожній рядок
`{{sender_name}}`	Зарезервовано; наразі на всіх платформах розгортається в порожній рядок
`{{comment_text}}`	Текст коментаря / DM / відповіді на історію, що спричинив тригер
`{{comment_id}}`	Platform-id коментаря / повідомлення, що спрацював
`{{comment_sent_at}}`	ISO 8601 timestamp події (коли доступно)
`{{matched_keyword}}`	Ключове слово, що збіглося (або рядок емодзі для `dm_reaction`)
`{{platform}}`	Ідентифікатор платформи: `instagram` або `facebook`
`{{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 (на акаунт)
Launch & Business	10	1 000
Enterprise	50	5 000

Ліміт активних автоматизацій рахується на User Profile, а не на батьківський акаунт. Кожен профіль вашого акаунта отримує свої Launch/Business 10 або Enterprise 50, тож акаунт із багатьма профілями може запускати відповідну кількість автоматизацій у кожному з них. Він рахує активні автоматизації та застосовується як при POST (створення), так і при повторній активації через PUT (active: false → true), у кожному випадку повертаючи код помилки 470. Потрібен вищий ліміт на профіль? Зв’яжіться з підтримкою, щоб його підвищили для вашого акаунта. Добовий ліміт DM застосовується на батьківський акаунт Ayrshare, спільно для всіх ваших профілів, з підлімітом на профіль, щоб один активний профіль не вичерпав квоту всього акаунта. Коли досягнуто ліміт DM, рядок активності отримує статус rate_limited і DM не надсилається. Ліміт розмов Messaging також застосовується. Для send_dm потрібне доповнення Messaging у профілі, і кожен надісланий ним DM враховується в місячному ліміті розмов цього профілю так само, як DM, який ви надсилаєте самі. Коли ліміт досягнуто, send_dm новому отримувачу не надсилається, а рядок активності отримує статус failed із повідомленням про ліміт в actionResults[].errorDetails. Виняток становлять DM, спричинені коментарем (comment_keyword і story_comment): вони надсилаються навіть після досягнення ліміту й усе одно враховуються. Структурні ліміти на одну автоматизацію: 1–50 тригерів, 1–50 дій. Сам Instagram обмежує DM приблизно 200/годину на акаунт. Двигун виконує диспетчеризацію з jitter 20–60 секунд, щоб залишатися в безпечних межах.

Статуси активності

Рядок у GET /automations/:id/activity має статус верхнього рівня status плюс статус кожної дії всередині actionResults[]:

Статус	Значення
`pending`	Щойно записано; воркер ще не забрав завдання
`in_flight`	Воркер зараз виконує диспетчеризацію
`sent`	Принаймні одну дію було прийнято платформою, і жодна не спричинила auth-помилку. Для `send_dm` це означає, що Meta прийняла повідомлення — не те, що отримувач його отримав (див. примітку нижче)
`failed`	Жодну дію не було прийнято, і принаймні одну було відхилено платформою або її не вдалося виконати (і жодна не спричинила auth-помилку). Причина знаходиться в `actionResults[].errorDetails`
`auth_error`	Облікові дані Instagram чи сторінки Facebook або дозволи на обмін повідомленнями для цього акаунта не вдалося використати — наприклад, прострочений або відкликаний access-токен, невибрана Facebook Page або неактивований Messaging для профілю. DM не було повторено. Помилки доставки для окремих отримувачів фіксуються як `failed`, а не тут
`rate_limited`	Досягнуто добовий ліміт DM (плановий або на профіль); DM не надіслано
`deduplicated`	Ця дія вже спрацьовувала для цього отримувача в межах вікна дедуплікації
`skipped`	Автоматизацію було придушено до диспетчеризації — її було деактивовано або видалено між fan-out і диспетчеризацією, у неї не налаштовано жодних дій, або взаємодія, що її спричинила, надійшла від власного акаунта автоматизації — найчастіше це коментар до вашого власного допису. В останньому випадку жодна дія не виконується: ані DM (акаунт не може надіслати повідомлення сам собі), ані `fire_webhook` чи `send_email`. Автоматизація, яка ввімкнула `automation.completed`, усе одно отримує цю подію з цим статусом

pending і in_flight — перехідні; усі інші — термінальні. Коли автоматизація має більше однієї дії, верхньорівневий status виводиться з результатів окремих дій у такому порядку: auth_error, якщо будь-яка дія спричинила auth-помилку, далі sent, якщо будь-яку дію було прийнято, далі deduplicated, якщо кожну дію було дедупліковано, далі skipped, якщо кожну дію було свідомо придушено (skipped або deduplicated), інакше — failed. Читайте actionResults[] для деталей по кожній дії.

sent — це квитанція про прийняття платформою, а не квитанція про доставку. Дію send_dm позначено як sent у той момент, коли Meta прийме повідомлення, — незалежно від того, чи воно надсилається з вашого акаунта Instagram, чи через Messenger від вашої сторінки Facebook. Автоматизація фіксує лише це прийняття й не відстежує доставку. Instagram не надає доставку повідомлень жодному API, і чи справді його отримає отримувач, залежить від параметра Message requests в Instagram, який Ayrshare не може ані прочитати, ані змінити. Див. Automation DM Sent but Not Delivered.

Коди помилок

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`

Плани Launch також включені. Business Launch відповідає рівню Business, тому автоматизації доступні на планах Launch, Business та Enterprise. 468 повертається лише для планів, які не включають автоматизації.

Що Meta НЕ дозволяє

Кілька часто запитуваних можливостей не підтримуються, оскільки Meta не дозволяє їх у публічному Instagram API:

Автоматичне DM новим підписникам. Instagram не публікує webhook на підписку.
Перше DM-повідомлення незнайомцям. Meta вимагає, щоб отримувач попередньо взаємодіяв (коментар, відповідь, DM, реакція), перш ніж бізнес-акаунт зможе надіслати йому повідомлення. Кожен підтримуваний тригер прив’язаний саме до такої взаємодії — але зверніть увагу, що дозвіл надіслати не є тим самим, що й доставка повідомлення: параметр Message requests в Instagram отримувача все одно може змусити Meta прийняти та потім тихо відкинути повідомлення (див. Automation DM Sent but Not Delivered).
Масові вихідні кампанії. Погодинні ліміти DM та антифрод-евристики застосовуються на рівні платформи.

Використання з кількома профілями

Ендпоінти враховують заголовок profileKey. Передайте ключ дочірнього профілю — і автоматизація буде створена/керована в межах цього профілю. Обмеження швидкості поділяються між профілями через підліміт на профіль, щоб один активний профіль не вичерпав квоту батьківського акаунта.

FAQ

Чи можу я налаштувати тригер на нового підписника?

Ні. Instagram не публікує webhook на підписку, і Meta не дозволяє стороннім застосункам надсилати DM користувачеві, який попередньо не взаємодіяв. Кожен підтримуваний тригер (comment_keyword, story_reply, dm_reaction, dm_keyword) прив’язаний саме до такої взаємодії, що й робить надсилання допустимим.

Чому в активності зазначено sent, але отримувач так і не отримав DM?

sent означає, що Meta прийняла повідомлення, а не те, що воно було доставлене. Це стосується і Instagram, і Facebook (Messenger від вашої сторінки): автоматизація фіксує лише прийняття й не відстежує доставку. В Instagram доставка залежить від параметра Message requests отримувача в Instagram — якщо він не дозволяє запити повідомлень від усіх, Meta повертає успішну відповідь і тихо відкидає повідомлення, без помилки, webhook чи іншого сигналу на жодному рівні API. Успішний DM, спричинений коментарем, також надходить як запит повідомлення, який отримувач має прийняти (якщо розмова вже не існує). Це постійне обмеження платформи Instagram. Див. Automation DM Sent but Not Delivered.

Що станеться, якщо мій access-токен буде недійсним, коли автоматизація спрацює?

Якщо облікові дані Instagram чи сторінки Facebook або дозволи на обмін повідомленнями для акаунта дійсно не працюють — наприклад, прострочений або відкликаний access-токен, невибрана Facebook Page або неактивований Messaging для профілю — рядок активності отримує статус auth_error, і DM не повторюється. Виправлення стану акаунта (перепідключення, вибір Page або активація Messaging) дозволить наступній відповідній взаємодії спрацювати нормально. Це стосується лише справжніх проблем з обліковими даними та дозволами: якщо конкретний DM не вдалося доставити з іншої причини — наприклад, не вдалося знайти отримувача або взаємодія, що спричинила спрацювання, надійшла від акаунта, який мав би надіслати DM, — рядок фіксується як failed або skipped із причиною в actionResults[].errorDetails, і перепідключення не змінить результату.

Чому є затримка перед надсиланням DM?

Кожне диспетчерування планується на 20–60 секунд після взаємодії, щоб надсилання DM виглядало органічно для антиспам-систем Instagram. Затримка застосовується до взаємодії до зіставлення будь-якого правила, тому вона стосується кожної дії правила, включно з fire_webhook і send_email, — ваш webhook надійде через 20–60 секунд після коментаря, а не одразу. Timestamp created у рядку активності — це коли тригер збігся; completedAt — коли диспетчеризація завершилася.

Чи зберігаються рядки активності назавжди?

Рядки активності зберігаються безстроково для трасування та аналітики. Ендпоінт GET /automations/:id/activity повертає рядки за останні 30 днів для продуктивності. (Захист від дедуплікації використовує власне вікно на дію — типово 7 днів — яке не пов’язане з періодом перегляду активності.)

Чи видалення автоматизації прибирає її історію активності?

Ні. Видалення є soft-delete: основний рядок позначається як deleted, нові диспетчеризації не виконуються, але історичні рядки активності залишаються доступними для читання через ендпоінт активності.

Ендпоінти

POST /automations — створити нову автоматизацію
GET /automations — переглянути список ваших автоматизацій
GET /automations/:id — отримати одну автоматизацію з її тригерами та діями
PUT /automations/:id — часткове оновлення; призупиніть за допомогою active: false
DELETE /automations/:id — soft-delete
GET /automations/:id/activity — журнал аудиту диспетчеризацій із пагінацією через курсор

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Огляд Automations API

Як це працює

Тригери

Постійно чинні правила з `"all"`

Сторінки Facebook

Дії

Вікно дедуплікації на дію

Динамічний вміст повідомлення

Webhook-події

`automation.triggered`

`automation.completed`

Якщо webhook не зареєстровано

Змінні шаблону

Обмеження швидкості та ліміти

Статуси активності

Коди помилок

Що Meta НЕ дозволяє

Використання з кількома профілями

FAQ

Ендпоінти

​Як це працює

​Тригери

​Постійно чинні правила з "all"

​Сторінки Facebook

​Дії

​Вікно дедуплікації на дію

​Динамічний вміст повідомлення

​Webhook-події

​automation.triggered

​automation.completed

​Якщо webhook не зареєстровано

​Змінні шаблону

​Обмеження швидкості та ліміти

​Статуси активності

​Коди помилок

​Що Meta НЕ дозволяє

​Використання з кількома профілями

​FAQ

​Ендпоінти

Як це працює

Тригери

Постійно чинні правила з `"all"`

Сторінки Facebook

Дії

Вікно дедуплікації на дію

Динамічний вміст повідомлення

Webhook-події

`automation.triggered`

`automation.completed`

Якщо webhook не зареєстровано

Змінні шаблону

Обмеження швидкості та ліміти

Статуси активності

Коди помилок

Що Meta НЕ дозволяє

Використання з кількома профілями

FAQ

Ендпоінти