Skip to main content
Операції з оголошеннями приймають рекламну платформу як аргумент, тому та сама операція працює на кожній рекламній платформі, яку підтримує Ayrshare. Наразі це FACEBOOK та INSTAGRAM. Кожна операція викликає відповідний REST-ендпоінт оголошень і повертає його відповідь без змін. Автентифікація та ліміти такі самі, як у REST. Невдалий виклик повертає помилку GraphQL: extensions.status містить статус REST, а extensions.code — код помилки Ayrshare, якщо помилка REST його має. Див. Помилки. Операції з оголошеннями потребують доповнення Ads. Без нього кожен виклик повертає помилку з extensions.status 403 і extensions.code 399.

​
Операції

Кожна операція також приймає необов’язковий profileKey, щоб діяти від імені User Profile (профілю користувача). Усі вони повертають відповідь REST як JSON, тому не приймають вибірки полів.

​
Список рекламних акаунтів

Почніть звідси. Використовуйте значення accountId з відповіді всюди, де операція запитує accountId.

​
Пошук параметрів таргетингу

kind визначає тип пошуку: INTERESTS для таргетингу аудиторії, REGIONS або CITIES для місцеположень. Кожен тип приймає лише власні аргументи. Наприклад, countryCode і regionId працюють лише з CITIES, а INTERESTS потребує search.

​
Список оголошень

Передайте принаймні один із параметрів campaignId, accountId, adId, postId або socialPostId. socialPostId — це власний id публікації в соцмережі, для публікацій, опублікованих не через Ayrshare.

​
Перегляд витрат на оголошення

​
Призупинення або відновлення оголошення

updateAd змінює реальні рекламні витрати. PAUSED зупиняє витрати, ACTIVE відновлює їх, а DELETED або ARCHIVED виводить оголошення з обігу. Той самий статус також встановлюється для набору оголошень і кампанії цього оголошення, тому всі інші оголошення в цьому наборі оголошень або кампанії змінюються разом із ним. Кампанія або набір оголошень, до яких просування було приєднано через attachTo, зберігають власний статус, а оголошення показується лише тоді, коли кампанія та набір оголошень над ним активні.

​
Просування публікації

boostPost витрачає реальні гроші з рекламного акаунта. Він перетворює опубліковану публікацію на оголошення.
  • Передайте postId (id публікації в Ayrshare) або socialPostId (власний id публікації в соцмережі).
  • Отримайте accountId з adAccounts.
  • budget.amount вказується у валюті рекламного акаунта. Не передавайте budget лише тоді, коли attachTo.adSetId додає оголошення до набору оголошень, який ви вже ведете і який зберігає власний бюджет. У такому разі не передавайте й targeting: набір оголошень зберігає власний. Див. Просування в наявну кампанію або набір оголошень.
  • schedule, targeting, callToAction, attachTo і status необов’язкові. Якщо не вказати status і schedule, оголошення буде активним, почне показуватися одразу й не матиме дати завершення, тому воно витрачатиме кошти, доки ви його не призупините. Щоб обмежити його, встановіть status: PAUSED або schedule.end.
  • Налаштування, які має лише одна платформа, розміщуйте в platformOptions з ключем за платформою. На Facebook та Instagram adName і bidAmount там обов’язкові, наприклад platformOptions: { facebook: { adName: "Autumn sale", bidAmount: 2 } }. Без них просування повертає помилку про відсутні поля. З attachTo.adSetId не передавайте bidAmount: набір оголошень зберігає власну ставку.
Деякі аргументи приймають більше ніж одну форму, тому вони використовують тип JSON:
  • accountId приймає рядок або число.
  • Дати в schedule приймають дату або дату й час у форматі ISO 8601, наприклад "2026-10-10T09:00:00Z". Використовуйте цю форму, а не число. schedule.end також приймає 0, що означає відсутність дати завершення.
  • Ключі місцеположень приймають одне значення або список.
  • targeting.interests приймає id у вигляді рядків або чисел.
  • platformOptions приймає об’єкт.
Надсилайте новий idempotencyKey, наприклад UUID, з кожним просуванням. Якщо виклик перевищив час очікування або завершився помилкою, повторіть його з тим самим ключем і тими самими аргументами.
  • Якщо перше просування завершилося, повторний виклик повертає його відповідь, а не створює й оплачує друге оголошення.
  • Якщо перше просування ще виконується, повторний виклик повертає помилку з extensions.status 409. Зачекайте, а потім повторіть виклик із тим самим ключем. Не переходьте на новий ключ.
  • Повторне використання ключа з іншими аргументами також повертає 409.
Щоб зупинити витрати на оголошення, викличте updateAd зі status: PAUSED. boostFacebookPost та instagramBoostPost і далі працюють. Операції для окремих платформ, як-от facebookAdAccounts та instagramAds, і далі працюють без змін.