Огляд Post API

Кінцева точка post дозволяє публікувати дописи в соціальних мережах: Bluesky, Facebook, Google Business Profile, Instagram, LinkedIn, Pinterest, Reddit, Snapchat, Telegram, TikTok, X/Twitter та YouTube. Існує багато параметрів для налаштування Вашого допису, наприклад планування дописів, додавання автохештегів, автоматичне планування публікацій тощо. Часто це використовується агенціями, коли кілька зацікавлених сторін мають затвердити допис перед його публікацією. Почніть публікувати дописи за допомогою кінцевої точки POST /post.

Робочий процес затвердження

Якщо Ваш робочий процес публікації вимагає затвердження перед надсиланням допису, встановіть поле requiresApproval у true. Це еквівалентно призупиненню допису, поки параметр approved не буде встановлено у true.

Приклад робочого процесу затвердження

Допис матиме статус “awaiting approval”, поки параметр approved не буде встановлено у true через кінцеву точку PATCH /post.

Публікація з параметрами

Опублікуйте свій допис за допомогою кінцевої точки /post з полем requiresApproval як true. Ви також можете включити стандартні параметри, наприклад scheduleDate.

Статус awaiting approval

Допис буде у статусі “awaiting approval” і буде утриманий до надання затвердження.

Затвердження допису

Оновіть допис за допомогою операції PATCH /post, встановивши поле approved у true. Допис тепер буде надіслано в запланований час.

Використання нотаток

Опціонально: Встановіть notes для допису для довідки, наприклад, хто повинен затвердити допис.

Publish the Post with Approval

{
  "requiresApproval": true,
  "notes": "need approval by John Smith" // опціонально
}

Якщо scheduleDate включено і дата в минулому, допис буде опубліковано негайно після затвердження.

Відео робочого процесу затвердження

Перегляньте відео нижче для прикладу робочого процесу затвердження.

Автохештеги

Додайте найрелевантніші хештеги до Вашого допису. autoHashtag — це об’єкт або Boolean — див. нижче — з такими параметрами:

max: (опціонально) Ціле число хештегів для додавання, діапазон 1-10. За замовчуванням 2.
position: (опціонально) Рядок “auto” або “end”. Auto додає хештеги в дописі або в кінець. “end” додає хештеги лише в кінець.

Потрібен платний план.

{
  "hashtags": {
    "max": 3, // опціонально: діапазон цілого числа 1-10
    "position": "auto" // опціонально: Рядок "auto" або "end"
  }
}

Якщо Ви не хочете надсилати жодного з наведених вище параметрів, передайте булеве значення true замість об’єкта.

{
  "autoHashtag": true
}

Автоповтор

Автоматично повторно публікує Ваш контент кілька разів через регулярні проміжки, створюючи вічнозелений контент, який залишається свіжим і видимим для Вашої аудиторії. Потрібен платний план. Параметри:

repeat: (обов’язково) Кількість разів для повторної публікації контенту. Має бути від 1 до 10.
days: (обов’язково) Кількість днів між кожним повторенням. Має бути принаймні 2 дні.
startDate: (опціонально) Коли розпочати графік повтору, у форматі ISO-8601 UTC. Якщо не вказано, перший допис буде опубліковано негайно. Ви повинні використовувати параметр startDate замість верхньорівневого параметра scheduleDate.

Auto Repost

{
  "repeat": 2, // мін 2, макс 10
  "days": 5, // мін 2
  "startDate": "2021-07-08T12:30:00Z"
}

Відповідь включатиме всі майбутні заплановані повтори та autoRepostId для кожного повтору.

Auto Repost Response

{
  "status": "scheduled",
  "scheduleDate": "2025-06-13T12:30:00.000Z",
  "id": "eIT96IYEodNuzU4oMmwG",
  "refId": "9abf1426d6ce9122ef11c72bd",
  "autoRepostId": "F5wdoaOAAGtDQVciExSxL",
  "post": "The most important things are the hardest to say - Stephen King"
}

При створенні автоповтору ID autoRepostId призначається для відстеження цієї серії дописів. Ви можете отримати всі автоповтори для допису за допомогою виклику History з autoRepostId. Якщо Вам потрібно видалити повтор, Ви можете використати виклик DELETE з ID допису.

Важливо: При використанні автоповтору обов’язково дотримуйтесь рекомендацій щодо частоти публікацій кожної соціальної мережі, щоб уникнути обмежень облікового запису.Примітка: Функція autoRepost не може використовуватися разом з scheduleDate. Якщо Ви включите обидва параметри, scheduleDate матиме пріоритет, а autoRepost буде проігноровано. Будь ласка, використовуйте параметр startDate замість цього.

Перший коментар

Автоматично додавайте перший коментар з медіа після публікації допису. Для TikTok коментар відкладається до завершення обробки відео (див. Час обробки першого коментаря). Публікація першого коментаря під власним дописом у соціальній мережі може допомогти запустити взаємодію та задати тон подальшій дискусії.

{
  "firstComment": {
    "comment": "My first comment", // обов'язково
    "mediaUrls": ["https://..."] // Тільки Facebook, LinkedIn та X/Twitter
  }
}

Час обробки першого коментаря

Для більшості соціальних мереж відповідь API затримується, оскільки наша система повинна (1) чекати повної публікації оригінального допису, а потім (2) додати коментар до цього опублікованого допису. Цей послідовний процес додає приблизно 20 секунд затримки. TikTok обробляється по-іншому. TikTok обробляє відео асинхронно, тому id допису — "pending", поки webhook TikTok post.publish.publicly_available не розкриє реальний id відео (див. TikTok Processing). Тому відповідь /post одразу повертає перший коментар TikTok з status: "pending", і коментар публікується автоматично, коли TikTok завершує обробку і спрацьовує webhook tikTokPublished Scheduled Action. TikTok не гарантує час обробки, тому фіксованої затримки немає. Важлива примітка про TikTok: Для правильної роботи перших коментарів у TikTok параметр visibility допису має бути встановлено на public. Непублічне відео ніколи не отримує webhook publicly_available, тому його перший коментар не може бути опубліковано; у цьому випадку Ayrshare повертає помилку коментаря замість того, щоб залишити його pending.

Ідемпотентні дописи

Ідемпотентність — це опціональна функція, яка гарантує, що запит виконується лише один раз, навіть якщо він випадково надсилається кілька разів. При публікації контенту через API Ви можете включити опціональний параметр idempotencyKey у тіло запиту, щоб унікально ідентифікувати операцію. Це дозволяє безпечно повторити запит публікації без ризику створення дублікатів дописів. Щоб використовувати ідемпотентність, додайте параметр idempotencyKey до JSON-тіла POST-запиту /post:

Idempotency Key

{
  "idempotencyKey": "Unique Key"
}

Значення idempotencyKey має бути унікальним рядком для кожного User Profile. Якщо зроблено запит з тим самим idempotencyKey для певного User Profile, незалежно від стану допису (success, error, pending або deleted), буде повернуто помилку, яка вказує, що знайдено дублікат ключа.

API повинен спочатку прийняти та обробити POST-запит, щоб зберегти ключ ідемпотентності та перевірити на наявність дублікатів. Однак, якщо кілька POST-запитів з тим самим idempotencyKey надсилаються одночасно або заплановані на той самий час публікації, API може не виявити дублікати ключів. Це тому, що API обробляє ці одночасні або одночасно заплановані запити паралельно, перш ніж він встигне зареєструвати ключ ідемпотентності з будь-якого одного запиту. У результаті немає гарантії, що дублікати ідемпотентних ключів будуть виявлені в цих сценаріях одночасного подання або виконання запланованих дописів.

Використання ідемпотентності допомагає запобігти випадковому створенню дублікатів дописів при повторних спробах невдалих запитів або обробці проблем з мережею. Однак все ще рекомендується впровадити належну обробку помилок та механізми повторних спроб у Вашому додатку, щоб належним чином обробляти потенційні збої.

Вимоги до зображень і відео

Публікація зображень і відео має різні вимоги для кожної мережі, але не хвилюйтеся. Наша система перевіряє Ваш допис перед надсиланням, тому Ви отримаєте відповідь про помилку, якщо щось не так. Див. посилання нижче для отримання деталей про рекомендації щодо зображень і відео.

Рекомендації щодо зображень і відео

Дійсний URL

Переконайтеся, що URL Вашого медіа дійсний і безпосередньо надає доступ до медіа. Перший тест — спробуйте URL у браузері. Якщо зображення не завантажиться або не може бути завантажено в браузері, воно, ймовірно, зазнає невдачі. Наприклад, URL DropBox, який відкриває веб-додаток DropBox, не працюватиме.

Якщо у Вас є Google Drive Share URL або Dropbox Share URL, Ви можете просто використовувати URL у параметрі mediaUrls при публікації допису або коментаря. Ayrshare автоматично перетворить share URL на посилання для завантаження.

Ми перевіряємо URL медіа, виконуючи запит HEAD. Будь ласка, переконайтеся, що хостинг-провайдер не блокує запит HEAD, інакше публікація зазнає невдачі з помилкою 403. Наприклад, ось запит HEAD до URL медіа:

Fetch HEAD Request

const run = async () => {
  const url = "https://img.ayrshare.com/012/gb.jpg";
  return await fetch(url, {
    method: "HEAD"
  })
    .then((res) => {
      if (res.ok) {
        return console.log("Success:", res.status, res.statusText);
      } else {
        return console.error("Error:", res.status, res.statusText, res);
      }
    })
    .catch((error) => {
      return console.error("Error Catch:", error);
    });
};

run();

Автоматизований захист медіа

Ayrshare включає вбудований захист медіа, який може виявляти та вирішувати певні проблеми з доставкою медіа під час публікації. Коли публікація вдалася, але виявлено та вирішено проблему з контентом, кожен постраждалий запис у postIds[] включає опціональний об’єкт contentIssues, щоб Ви могли визначити та виправити основну проблему:

{
    "postIds": [
        {
            "status": "success",
            "platform": "instagram",
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "contentIssues": {
                "originMediaHostFailed": true,
                "details": ["Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."]
            }
        }
    ]
}

Якщо Ви бачите originMediaHostFailed у своїх відповідях, перегляньте конфігурацію хостингу медіа. Див. Meta Media Crawler Blocked для типових причин та рішень.

Пробіли та спеціальні символи

Ми рекомендуємо уникати наступного в URL Вашого медіа:

Пробілів в URL.
URL-закодованих пробілів в URL.
Спеціальних символів в URL, навіть якщо вони URL-закодовані, наприклад accent marks é.

Наприклад:

https://img.ayrshare.com/012/test .webp

Цей URL зазнає невдачі через пробіл test .webp. Ми також не рекомендуємо використовувати URL-закодовані пробіли, наприклад %20 в URL — це також може спричинити проблеми з деякими соціальними мережами. І це зображення Unsplash:

https://unsplash.com/photos/a-house-in-the-middle-of-a-field-with-trees-in-the-background-znbmh2-cIj0

Це зображення Unsplash зазнає невдачі, тому що воно не безпосередньо звертається до зображення, а показує веб-додаток.

Санітизація імен файлів та URL

Ви можете санітизувати імена файлів за допомогою регулярного виразу, наприклад /[^a-z0-9\/\.]/gi.

const sanitizeFileName = (url) => url.replace(/[^a-z0-9\/\.]/gi, "_");
sanitizeFileName("tést .webp"); // t_st_.webp

або санітизуйте URL

const sanitizeUrl = (url) => {
  const [protocol, rest] = url.split("://");
  const [domain, ...path] = rest.split("/");
  const sanitizedPath = path.join("/").replace(/[^a-z0-9\/\.]/gi, "_");
  return `${protocol}://${domain}/${sanitizedPath}`;
};

// Output: https://img.ayrshare.com/012/t_st_.webp
sanitizeUrl("https://img.ayrshare.com/012/tést .webp");

Додаткова інформація

Якщо Ви розміщуєте самостійно, переконайтеся, що URL можна отримати ззовні і не вимагає спеціальних дозволів.
Див. нижче, як обробляти відео з невідомими розширеннями, часто signed URLs, як AWS S3.
Якщо Ви використовуєте signed URL, наприклад S3, ми рекомендуємо встановити термін дії URL принаймні 7 днів. Це дозволяє нашій команді допомогти з будь-якими Вашими питаннями щодо публікації допису.
Перевірте, чи існує URL медіа за допомогою наших інструментів перевірки медіа.

Швидкість завантаження

Переконайтеся, що Ваш хостинг медіа має швидке з’єднання, особливо швидкість завантаження. Ви можете протестувати продуктивність хостингу медіа на pingdom. Ми рекомендуємо принаймні рейтинг B.

Розширення відео

Якщо Ваш URL не закінчується відомим розширенням відео, наприклад mp4, Ви можете використати поле isVideo: true у дописі, щоб вказати, що mediaUrl — це відео. Ayrshare спробує визначити тип файлу, наприклад MOV. Однак ми рекомендуємо явно закінчувати Ваш відеофайл відомим розширенням, наприклад mp4, оскільки це має вищий рівень успіху в соціальних мережах.

Тільки зображення або відео

Кілька соціальних мереж підтримують надсилання медіа без тексту допису. Якщо Ви не хочете, щоб текст допису був включений, надішліть порожній рядок: post: "" Наступні соціальні мережі підтримують дописи без тексту/порожній текст: Facebook, Instagram, LinkedIn, Threads, TikTok та X/Twitter.

Тестування зображень і відео

Розгляньте можливість використання генерації випадкового тексту та випадкового зображення чи відео, щоб пришвидшити Ваше тестування. Припиніть намагатися придумати щось інше для кожного зі своїх тестових дописів!

Розриви рядків

Якщо Ви хочете розриви рядків (нові рядки) у дописі, використовуйте невидимий розрив рядка \u2063\n. Наприклад, This is a new\u2063\nline.Ми також рекомендуємо спробувати в Postman, щоб побачити, як новий розрив рядка перекладається на Ваш обраний мову. Наприклад, PHP часто використовує лише \nДеякі соціальні мережі поки не підтримують розриви рядків у тексті допису.

Мультиплатформенні дописи та медіа

Ця функція дозволяє налаштовувати вміст допису та медіа для різних соціальних мереж в одному виклику API. Ви можете вказати унікальний текст та/або зображення для кожної платформи, використовуючи об’єкти для полів post та mediaUrls.

Використовуйте структуру об’єкта для полів post та/або mediaUrls.
Вкажіть контент, специфічний для платформи, використовуючи назви платформ як ключі.
Включіть ключ default для контенту, який буде використовуватись на платформах, які явно не вказано.

{
  "post": {
    "instagram": "Great IG pic!",
    "facebook": "Great FB pic!",
    "default": "Great default pic!"
  },
  "platforms": ["instagram", "facebook", "linkedin"],
  "mediaUrls": {
    "instagram": "https://img.ayrshare.com/012/gb.jpg",
    "linkedin": "https://img.ayrshare.com/012/gb.jpg",
    "default": "https://img.ayrshare.com/012/gb.jpg"
  }
}

У наведеному вище прикладі:

Instagram використовуватиме свій специфічний текст та URL зображення.
Facebook використовуватиме свій специфічний текст та URL зображення за замовчуванням.
LinkedIn використовуватиме текст за замовчуванням та свій специфічний URL зображення.

Якщо Вам потрібно опублікувати кілька зображень на різних платформах, створіть окремі дописи для кожної платформи замість використання цієї мультиплатформенної структури.

Profile Keys

Публікуйте від імені користувача, надаючи Profile Keys користувачів як параметр тіла і додаткові дані у відповіді. Потрібен план Business або Enterprise.

Profiles

Дописи Rich Text

Ви можете додавати rich text, наприклад ”𝓗𝓮𝓵𝓵𝓸, how about a little 𝗯𝗼𝗹𝗱 𝘁𝗲𝘅𝘁 and 𝘪𝘵𝘢𝘭𝘪𝘤𝘴 𝘵𝘦𝘹𝘵 and an x₂?”. Ви можете використовувати rich text у мережах, таких як Twitter, Facebook, LinkedIn, Telegram та Instagram. Якщо публікуєте в Reddit, використовуйте форматування Reddit-flavored Markdown. HTML-елементи використовуються, щоб вказати тип rich text, який перекладається в unicode. Наприклад:

{
    "post": "<var>Hello</var>, how about a little <b>bold text</b> and <i>italics text</i> and an x<sub>2</sub>?"
    "platforms": ["twitter"]
}

HTML-елементи

HTML	Приклад
<b>Nice One!</b>	Nice One!
<strong>Hello, world!</strong>	Hello, world!
<em>World</em>	World
normal <i>italics <b>bold italics</b></i>	normal italics bold italics
`<b>Hello</b>, world!`	`Hello, world!`
`<b>Hello</b>, world!`	`Hello``, world!`
<samp>123</samp>	𝟷𝟸𝟹
<var>Hello</var>	𝓗𝓮𝓵𝓵𝓸
x<sub>2</sub>	x₂
x<sup>2</sup>	x²

CSS-коди

Код	Приклад	Результат
\u00B0	It’s 25\u00B0C today!	It’s 25°C today!
\u2063\n	This is a new\u2063\nline.	This is a new line.

Планування дописів

Створення запланованих дописів

Ви можете планувати майбутні дописи, вказавши параметр scheduleDate з datetime у Zulu/UTC. Zulu Time, також відомий як Coordinated Universal Time (UTC), — це світовий стандарт часу. Наприклад, використовуйте формат YYYY-MM-DDThh:mm:ssZ і надсилайте як 2026-07-08T12:30:00Z. Для більше прикладів див. utctime.

{
  "post": "Hello, world!",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["facebook", "instagram"],
  "scheduleDate": "2023-07-08T12:30:00Z"
}

Див. https://www.utctime.net/, щоб дізнатися, як перетворити Ваш місцевий час у Zulu/UTC. Якщо запланована дата в минулому, допис буде негайно надіслано.

Якщо mediaUrl включено із запланованим дописом, медіа має бути доступне в запланований час публікації. Наприклад, якщо допис заплановано опублікувати 5 березня 2026 року, медіа має бути доступне 5 березня 2026 року.

Обробка помилок для запланованих vs негайних дописівІснує важлива різниця в тому, як обробляються помилки валідації між негайними та запланованими дописами:

Негайні дописи
- При негайній публікації (без scheduleDate), якщо одна платформа не проходить перевірку валідації, інші платформи продовжуватимуть оброблятися. Наприклад, якщо допис перевищує обмеження символів Twitter, але дійсний для Facebook та Instagram, допис зазнає невдачі в Twitter, але все ще буде опубліковано у Facebook та Instagram.
Заплановані дописи
- При плануванні дописів для майбутньої публікації (зі scheduleDate) всі платформи повинні пройти початкові перевірки валідації перед плануванням допису. Якщо будь-яка платформа не проходить ці попередні перевірки валідації, вся операція планування буде відхилена і буде негайно повернуто помилку.
- Однак деякі помилки, специфічні для платформи, можуть бути не виявлені до фактичного часу публікації. У цих випадках запланований допис намагатиметься опублікуватися на всіх платформах, а індивідуальні збої платформ будуть повідомлені в кінцевих результатах без впливу на інші платформи.

Перевірка статусу запланованого допису

Ви можете перевірити статус запланованого допису кількома способами:

Налаштуйте Webhook Scheduled Action, щоб автоматично отримувати статус запланованого допису. Це доступно для плану Business і є рекомендованим методом.
Отримайте статус запланованого допису за допомогою виклику GET з ID допису.
Перевірте статус у Панелі керування Ayrshare. Спочатку перемкніться на User Profile, під яким опубліковано допис, потім перейдіть на сторінку “Posts” і шукайте за Ayrshare Post ID.

Призупинення запланованих дописів

Ви можете призупинити заплановані дописи, які ще не опубліковано. Призупинення запланованого допису запобігатиме його публікації, поки допис не буде відновлено. Використовуйте виклик PATCH, щоб призупинити або відновити запланований допис. Зверніть увагу: якщо допис відновлено, а scheduleDate у минулому, допис буде негайно опубліковано. Розгляньте оновлення scheduleDate перед відновленням.

Скорочення посилань

Посилання в дописі можна скоротити за допомогою link shortner Ayrshare. Ви можете увімкнути автоматичне скорочення посилань за допомогою параметра shortenLinks при надсиланні допису. Потрібен Max Pack.

{
  "post": "Hello, world with a link https://www.ayrshare.com",
  "platforms": ["linkedin"],
  "shortenLinks": true
}

Зображення Unsplash

Наступні поля доступні для параметра тіла unsplash:

Випадкове зображення: random повертає випадкове зображення Unsplash.
Зображення на основі пошуку: значення рядка пошукового терміна; наприклад, money вибере випадкове зображення на основі money.
Image IDs: значення масиву Ids; наприклад, [“HubtZZb2fCM”] зображення https://unsplash.com/photos/HubtZZb2fCM

{
  "post": "Hello, world!",
  "platforms": ["instagram"],
  "unsplash": "random",
  "unsplash": "search term", // unsplash: "money"
  "unsplash": ["unsplash image ID"] // unsplash: ["HubtZZb2fCM"]
}

Якщо копіюєте URL Unsplash для публікації в mediaUrls, обов’язково скопіюйте адресу зображення, а не просто URL. Для отримання додаткової інформації див. цей приклад.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Робочий процес затвердження

Приклад робочого процесу затвердження

Відео робочого процесу затвердження

Автохештеги

Автоповтор

Перший коментар

Час обробки першого коментаря

Ідемпотентні дописи

Вимоги до зображень і відео

Рекомендації щодо зображень і відео

Дійсний URL

Автоматизований захист медіа

Пробіли та спеціальні символи

Санітизація імен файлів та URL

Додаткова інформація

Швидкість завантаження

Розширення відео

Тільки зображення або відео

Тестування зображень і відео

Розриви рядків

Мультиплатформенні дописи та медіа

Profile Keys

Profiles

Дописи Rich Text

HTML-елементи

CSS-коди

Планування дописів

Створення запланованих дописів

Перевірка статусу запланованого допису

Призупинення запланованих дописів

Скорочення посилань

Зображення Unsplash

​Робочий процес затвердження

​Приклад робочого процесу затвердження

​Відео робочого процесу затвердження

​Автохештеги

​Автоповтор

​Перший коментар

​Час обробки першого коментаря

​Ідемпотентні дописи

​Вимоги до зображень і відео

Рекомендації щодо зображень і відео

​Дійсний URL

​Автоматизований захист медіа

​Пробіли та спеціальні символи

​Санітизація імен файлів та URL

​Додаткова інформація

​Швидкість завантаження

​Розширення відео

​Тільки зображення або відео

​Тестування зображень і відео

​Розриви рядків

​Мультиплатформенні дописи та медіа

​Profile Keys

Profiles

​Дописи Rich Text

​HTML-елементи

​CSS-коди

​Планування дописів

​Створення запланованих дописів

​Перевірка статусу запланованого допису

​Призупинення запланованих дописів

​Скорочення посилань

​Зображення Unsplash

Робочий процес затвердження

Приклад робочого процесу затвердження

Відео робочого процесу затвердження

Автохештеги

Автоповтор

Перший коментар

Час обробки першого коментаря

Ідемпотентні дописи

Вимоги до зображень і відео

Дійсний URL

Автоматизований захист медіа

Пробіли та спеціальні символи

Санітизація імен файлів та URL

Додаткова інформація

Швидкість завантаження

Розширення відео

Тільки зображення або відео

Тестування зображень і відео

Розриви рядків

Мультиплатформенні дописи та медіа

Profile Keys

Дописи Rich Text

HTML-елементи

CSS-коди

Планування дописів

Створення запланованих дописів

Перевірка статусу запланованого допису

Призупинення запланованих дописів

Скорочення посилань

Зображення Unsplash