Огляд Automations API

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

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

Як це працює

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

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

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

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

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 користувачеві, який спричинив спрацювання правила, використовуючи шаблонне повідомлення.	`message` (обов’язково, шаблонне)
`fire_webhook`	Виконує POST-запит із контекстом автоматизації на webhook-URL рівня акаунта (налаштуйте через `POST /hook/webhook`).	(немає — форма 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
}

Payload `fire_webhook`

Коли виконується fire_webhook, він надсилає POST з JSON-тілом на webhook-URL рівня акаунта:

{
  "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, а не на батьківський акаунт. Кожен профіль вашого акаунта отримує свої Business 10 / Enterprise 50, тож акаунт із багатьма профілями може запускати відповідну кількість автоматизацій у кожному з них. Він рахує активні автоматизації та застосовується як при POST (створення), так і при повторній активації через PUT (active: false → true), у кожному випадку повертаючи код помилки 470. Потрібен вищий ліміт на профіль? Зв’яжіться з підтримкою, щоб його підвищили для вашого акаунта. Добовий ліміт 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) задовольняє вимогу «користувач звернувся до вас першим».

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

Рядок активності отримує статус auth_error, і DM не повторюється. Перепідключіть акаунт — і наступна відповідна взаємодія спрацює нормально.

Чому є затримка перед надсиланням 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 — створити нову автоматизацію
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

Як це працює

Тригери

Дії

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

Payload `fire_webhook`

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

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

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

Коди помилок

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

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

FAQ

Ендпоінти

​Як це працює

​Тригери

​Дії

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

​Payload fire_webhook

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

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

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

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

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

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

​FAQ

​Ендпоінти

Як це працює

Тригери

Дії

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

Payload `fire_webhook`

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

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

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

Коди помилок

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

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

FAQ

Ендпоінти