> ## 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.

# Instagram API

> Опції публікації через Instagram API

<Info>
  Якщо у вас виникли проблеми з підключенням Instagram, див. [посібник з
  усунення несправностей](/help-center/technical-support/facebook_or_instagram_linking_issues).
</Info>

<Info>
  Якщо ваш медіафайл розміщено на сервері або CDN, який ви контролюєте, переконайтеся, що crawler Meta для публікацій
  може його отримати. Див. [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked),
  якщо ви бачите код помилки Ayrshare 440 ("social network could not download media from this URL") або код помилки 138 з "Restricted by robots.txt" у деталях.
</Info>

<div class="video-container">
  <iframe width="380" height="200" src="https://www.youtube.com/embed/3F7mbVN0qrw" title="Posting to Instagram API" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />
</div>

Instagram API має такі вимоги та обмеження.

<ul class="custom-bullets">
  <li>
    Обліковий запис Business або Creator Instagram, підключений до Facebook Page — [див.
    тут](/dashboard/connect-social-accounts/instagram).
  </li>

  <li>За 24-годинний період дозволено лише 50 дописів у Instagram. Див. нижче про `usedQuota`</li>

  <li>
    Текст `post` може містити до *5 хештегів* (наприклад, #wildtimes) та *3 згадування користувачів*
    (наприклад, @natgeo).
  </li>

  <li>Згадані @ користувачі Instagram отримають сповіщення.</li>
  <li>Максимум 2 200 символів у дописі.</li>

  <li>
    Мультизображення/відео-дописи підтримуються та надсилаються як carousel. Ви можете надіслати до 10 відео та
    зображень.
  </li>

  <li>
    Instagram не підтримує видалення через API. Видалення потрібно виконувати вручну через застосунок Instagram.
  </li>

  <li>
    Якщо ваше Reels відео не закінчується відомим розширенням відео, як-от mp4, використовуйте параметр `isVideo`.
    Див. [/post endpoint](/apis/post/post) для деталей.
  </li>

  <li>
    Instagram також підтримує надсилання медіа без тексту допису. Якщо ви не хочете включати текст допису,
    надішліть порожній рядок `post: ""`.
  </li>

  <li>Див. [Instagram Media Guidelines](/media-guidelines/instagram) та [Instagram Authorization](/dashboard/connect-social-accounts/instagram) для отримання додаткової інформації.</li>
</ul>

## Публікація у Instagram

JSON для базового допису із зображенням та хештегами у Instagram:

```json Instagram Post theme={"system"}
{
  "post": "The best IG ever #best #awesome https://www.instagram.com",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["instagram"]
}
```

Хештеги у дописах Instagram клікабельні, а посилання — ні.

<Note>
  Співвідношення сторін зображень і відео та тривалість відео дуже важливі для успішної публікації у Instagram. Якщо вони не відповідають вимогам, допис буде відхилено.

  [Див. розділ Instagram у Image and Video Guidelines](/media-guidelines/instagram).
</Note>

## Обліковий запис Instagram Business або Creator

Ваш обліковий запис Instagram має бути Business або Creator Account і підключеним до Facebook Page. Налаштування безкоштовне й просте.

Див. детальні інструкції тут:

<Card title="Instagram Linking" icon="link" href="/dashboard/connect-social-accounts/instagram" horizontal />

## Carousel з зображень та відео

Ви можете опублікувати в Instagram кілька зображень або відео Reels як carousel; загалом до 10 зображень або відео можна використати в одному carousel.
Просто додайте додаткові зображення чи відео у масив `mediaUrls`, і carousel буде створено автоматично.

```json Instagram Carousel Post theme={"system"}
{
  // Max 10 images or videos
  "mediaUrls": ["https://url.com/image.jpg", "https://url.com/video.mp4"]
}
```

<Note>
  URL-адреси відео повинні закінчуватися відомим розширенням, як-от `mp4`. Параметр `isVideo` не підтримується
  для carousel Instagram.
</Note>

## Instagram Reels

У Instagram відеодопис називається Reel.
Ви можете опублікувати відео у Instagram Reels API з наведеними нижче опціональними параметрами `instagramOptions`.

```json Instagram Reels Options theme={"system"}
{
  "instagramOptions": {
    "shareReelsFeed": true,
    "audioName": "The Weeknd - Blinding Lights",
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg", // if used, thumbNailOffset will be ignored.
    "thumbNailOffset": 30000
  }
}
```

<ul class="custom-bullets">
  <li>
    Див. [вимоги до відео Reels API](/media-guidelines/instagram#reels), щоб дізнатися деталі
    щодо вимог до відео.
  </li>

  <li>
    `shareReelsFeed`: Boolean, встановлений у `true`, щоб вказати, що Reel *може* з'являтися і в
    **Feed**, і у вкладці **Reels**, або `false`, щоб вказати, що Reel *може* з'являтися лише
    у вкладці **Reels**. Це значення є підказкою для Instagram, де ви хочете, щоб Reel з'явився, але жодне зі
    значень не визначає, чи Reel *насправді* з'явиться у вкладці **Reels** або **Feed**, оскільки
    Reel може не відповідати вимогам чи не бути обраним алгоритмом Instagram.
  </li>

  <li>
    `audioName`: Рядок-назва аудіо музики вашого медіа Reels. Перейменувати можна лише один раз, або
    під час створення Reel, або після — зі сторінки аудіо. Наприклад, `"The Weeknd - Blinding
            Lights"`.
  </li>

  <li>
    `thumbNail`: URL-адреса зображення обкладинки Reel (мініатюри). Див. [деталі про
    thumbNail](/apis/post/social-networks/instagram#reels-thumbnails).
  </li>

  <li>
    `thumbNailOffset`: Цілочисельне зміщення в мілісекундах кадру мініатюри. Див.
    [деталі про thumbNailOffset.](/apis/post/social-networks/instagram#reels-thumbnails)
  </li>
</ul>

Див. [вимоги до відео Reels API](/media-guidelines/instagram#reels) або [приклад використання Instagram Reels API](https://www.ayrshare.com/blog/instagram-reels-api-how-to-post-videos-to-reels-using-a-social-media-api/).

Ви також можете встановити [URL обкладинки Reels](/apis/post/social-networks/instagram#reels-thumbnails) та [теги локації та користувачів](/apis/post/social-networks/instagram#user-tags-and-locations).

## Trial Reels

Trial reel — це Reel, який публікується лише не-підписникам, коли його вперше опубліковано, що дозволяє вам протестувати, як Reel працює зі свіжою аудиторією, перш ніж він потрапить до ваших наявних підписників. Встановіть `trialParams.graduationStrategy` в `instagramOptions`, щоб опублікувати Reel як trial.

```json Instagram Trial Reel theme={"system"}
{
  "post": "Testing this with a fresh audience first",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "platforms": ["instagram"],
  "instagramOptions": {
    "trialParams": {
      "graduationStrategy": "MANUAL"
    }
  }
}
```

`graduationStrategy` контролює, як trial reel пізніше "graduates" — тобто стає видимим і для ваших підписників. Він обов'язковий, коли надано `trialParams`, і має бути одним з:

<ul class="custom-bullets">
  <li>
    <code>"MANUAL"</code> — допис залишається trial reel, поки ви вручну не graduate його з
    застосунку Instagram.
  </li>

  <li>
    <code>"SS\_PERFORMANCE"</code> — Meta автоматично graduates Reel на основі ранньої продуктивності
    серед не-підписників.
  </li>
</ul>

<Note>
  Сама graduation (просування опублікованого trial reel до підписників) наразі не надається
  API Meta, і її потрібно виконувати вручну у застосунку Instagram. Ayrshare додасть endpoint graduation,
  щойно Meta його надасть.
</Note>

### Обмеження trial reel

Запит trial reel відхиляється на edge Ayrshare — до будь-якого виклику Meta — коли будь-яка з цих умов не виконана:

<ul class="custom-bullets">
  <li>Рівно одна медіа URL, що закінчується на <code>.mp4</code> або <code>.mov</code> (регістронезалежно). Carousel не підтримуються.</li>
  <li><code>instagramOptions.stories</code> не повинно бути <code>true</code>. Stories не можуть бути trial reels.</li>
  <li><code>graduationStrategy</code> має бути присутнім і бути точно <code>"MANUAL"</code> або <code>"SS\_PERFORMANCE"</code> (регістрозалежно).</li>
</ul>

Невдачі повертають один з трьох кодів помилок Ayrshare — див. [Instagram Trial Reel Errors](/errors/errors-ayrshare#instagram-specific-error-codes) (<code>447</code>, <code>448</code>, <code>449</code>) для повних payloads.

## Instagram Stories

Ви можете опублікувати одне зображення або відео як Instagram Story з наведеними нижче `instagramOptions`. Instagram stories зникають через 24 години.

```json Stories Post theme={"system"}
{
  "post": "The description of the video",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "instagramOptions": {
    "stories": true
  }
}
```

Див. [вимоги Stories API](/media-guidelines/instagram#stories).

<ul class="custom-bullets">
  <li>
    Instagram Stories не підтримують текст допису — будь-який текст, наданий у полі `post`, включно зі
    згадуваннями, буде проігноровано.
  </li>

  <li>Stories зникають через 24 години.</li>

  <li>
    Instagram наразі підтримує публікацію Story лише на Instagram Business Accounts, а не на
    Creator Accounts.
  </li>

  <li>Instagram Stories не підтримують collaborators.</li>
  <li>Публікація стікерів (тобто link, poll, location) не підтримується Instagram.</li>
</ul>

## Мініатюри Reels

Ви можете вибрати кадр Reel як зображення мініатюри або власне зображення обкладинки (мініатюру) з зовнішньої URL-адреси.

```json Instagram Thumbnail theme={"system"}
{
  "instagramOptions": {
    // milliseconds
    "thumbNailOffset": 30000,
    // If both thumbNail and thumbNailOffset includes, thumbNail will be used.
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg"
  }
}
```

Зміщення — це розташування у мілісекундах кадру мініатюри відео Reel. Значення за замовчуванням `0`, це перший кадр Reel.

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

Мініатюра Reel повинна відповідати [вимогам до мініатюр Reels](/media-guidelines/instagram#reels-thumbnails).
Signed URLs з перенаправленнями не гарантовано сумісні з cover URLs.
Ми рекомендуємо не-signed URL або використання [/media endpoint](/apis/media/overview).

## Альтернативний текст

Додайте альтернативний текст Instagram, також відомий як alt-текст, до зображення.
Alt-текст Instagram — це функція доступності, яка використовується для додаткової інформації про користувача та програм зчитування з екрана.

<ul class="custom-bullets">
  <li>Alt-текст підтримує до 1 000 символів на зображення.</li>
  <li>Instagram не підтримує alt-текст для Reels або Stories.</li>
</ul>

Використовуйте `altText` в об'єкті `instagramOptions`.

```json Instagram Alt Text theme={"system"}
{
  "instagramOptions": {
    // Array of Alt Texts
    "altText": ["This is my best pic", "😃 here is the next one"]
  }
}
```

Кожен alt-текст має відповідати зображенню або відео у масиві `mediaUrls`.
Alt-текст буде застосовано до кожного зображення по порядку.

## User Tags та Locations

<Info>
  Користувач Instagram отримає сповіщення, коли ви використаєте його ім'я користувача у дописі. Будьте обережні,
  щоб не спамити користувачів і не публікувати з їхнім ім'ям користувача повторно. Якщо це зробити, Instagram може призупинити або
  деактивувати ваш обліковий запис.
</Info>

Зображення або Reel можна позначити тегами користувачів Instagram, а зображення, відео або Reel можна позначити локацією за допомогою параметра `instagramOptions`.

### Локація

Локація визначається `locationId`, тобто Facebook Page ID або ім'ям Facebook Page. Наприклад, ID сторінки Facebook [Guggenheim Museum](https://www.facebook.com/guggenheimmuseum) — `7640348500` або ім'я сторінки Facebook `"@guggenheimmuseum"`. Сторінки мають бути пов'язані з фізичною локацією.

```json Instagram Location theme={"system"}
// Using the Facebook Page Id - must be associated with a location
{
    "instagramOptions": {
        "locationId": 7640348500 // Guggenheim Museum Page Id
    }
}

// Using the Facebook Page name - must be associated with a location
{
    "instagramOptions": {
        "locationId": "@guggenheimmuseum" // Guggenheim Museum Page name. Must begin with @
    }
}
```

Ви можете знайти `locationId` (Page Id) через [brand endpoint](/apis/brand/overview). Зверніть увагу, що сторінка повинна мати вказану локацію, інакше locationId поверне помилку.

<Note>Не підтримується для зображень або відео у carousel.</Note>

### User Tags

Instagram-теги дозволяють позначати інших користувачів Instagram у вашому дописі.
Користувачі вказуються у `userTags`, що містить масив об'єктів з ім'ям користувача Instagram та координатами x/y (лише зображення). User tags можна додавати для окремих зображень або Reels, але не для звичайних відео, кількох зображень або Stories.

<ul class="custom-bullets">
  <li>Імена користувачів мають бути публічними обліковими записами Instagram. Не включайте @ handle користувача.</li>

  <li>
    Значення `x` і `y` мають бути числами `float`, що беруть початок з верхнього лівого кута зображення, у
    діапазоні `0.0`–`1.0`. Окремі зображення. Не включайте з Reels, інакше виникне помилка.
  </li>
</ul>

```json Instagram User Tags theme={"system"}
{
  "instagramOptions": {
    "userTags": [
      {
        "username": "ayrshare", // Required: Instagram username
        "x": 0.5, // Required for Images, cannot be used with Reels
        "y": 1.0 // Required for Images, cannot be used with Reels
      },
      {
        "username": "johnboy", // Required: Instagram username
        "x": 0.1, // Required for Images, cannot be used with Reels
        "y": 0.9 // Required for Images, cannot be used with Reels
      }
    ]
  }
}
```

## Instagram Mentions

Згадайте інший handle Instagram, додавши @handle у текст допису.

Наприклад, ви можете згадати handle @ayrshare у тексті допису:

```json Instagram Mentions theme={"system"}
{
  "post": "The best social media API @Ayrshare ever!", // empty string is allowed
  "mediaUrls": ["https://images.com/image.jpg"],
  "platforms": ["instagram"]
}
```

<Warning>
  Користувач, згаданий через `@mentioned`, буде сповіщений про згадку. Ознайомтеся з [важливими
  правилами](/testing/post-verification#mentions) щодо згадувань.
</Warning>

## Collaboration

Instagram collaboration дозволяє вам виступати співавтором контенту з іншими обліковими записами Instagram, [позначаючи інших як collaborators](https://www.facebook.com/help/instagram/291200585956732).
Це дозволяє призначати інших користувачів Instagram творцями вашого допису.
Коли їх позначено, ці користувачі отримують запрошення на співпрацю у мобільному застосунку.
Якщо вони погоджуються, допис також з'являється у їхній стрічці та стає видимим для їхніх підписників, розширюючи охоплення та потенціал залученості допису.

### Collaborators

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

Ви можете додавати collaborators до Reel, зображення або carousel.

Позначення приватного collaborator не дозволяється через Instagram API. Хоча
така функція існує у застосунку Instagram, платформи та їхні API
часто не мають [паритету функцій](/help-center/product/are_social_networks_native_apps_and_the_apis_at_parity).

<Warning>Instagram Stories не підтримують collaborators.</Warning>

<Warning>
  <ul class="custom-bullets">
    <li>**Запрошуйте лише тих collaborators, які, як ви очікуєте, `accept` ваше запрошення**.</li>

    <li>
      Якщо [collaborator
      відповідає](/apis/post/social-networks/instagram#get-collaborator-request-status) з
      `declined` запитом на співпрацю, **не запрошуйте його знову**, поки не зв'яжетеся з ним, щоб
      зрозуміти причину відмови.
    </li>

    <li>
      Повторні відмови від того самого або кількох користувачів поставлять ваш обліковий запис Instagram та Ayrshare
      під ризик скасування.
    </li>

    <li>Оригінальний автор може додати або видалити collaborator у будь-який час.</li>
  </ul>
</Warning>

Запрошуйте *до трьох* collaborators за допомогою масиву публічних імен користувачів Instagram.

```json Instagram Collaborators theme={"system"}
{
  "instagramOptions": {
    "collaborators": ["ayrshare", "therock", "taylorswift"] // Up to three
  }
}
```

Ці три collaborators отримають запрошення-повідомлення у мобільному застосунку Instagram і зможуть прийняти або відхилити запрошення, після чого ви зможете [перевірити статус запиту запрошеного користувача](/apis/post/social-networks/instagram#get-collaborator-request-status).
Запрошуйте лише collaborators, які, як ви знаєте, приймуть ваш запит, інакше ваш обліковий запис Instagram може бути негативно уражений.

<Warning>
  Примітка про запрошених collaborators: за кількома винятками, дані про або щодо співавторських медіа
  можуть бути доступні через API лише користувачеві, який опублікував медіа; collaborators не можуть
  отримати доступ до цих даних через API.
</Warning>

### Отримати статус запиту collaborator

Після запрошення Instagram collaborator ви можете перевірити статус запиту за допомогою [Get Collaborator Request Status API](/apis/utils/instagram-get-collaborator).

## Auto Image Resize

<Note>Потрібен Max Pack</Note>

Зображення автоматично змінюються до 1080 x 1080 px для роботи з Instagram за допомогою параметра `autoResize`. Зверніть увагу, що це змінить розмір зображення для всіх включених платформ, тому ми рекомендуємо робити один виклик для Instagram та інший /post-виклик для додаткових платформ.

```json Instagram Auto Image Resize theme={"system"}
{
  "post": "Let it go!",
  "platforms": ["instagram"],
  "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"],
  "instagramOptions": {
    "autoResize": true, // Max Pack
    "locationId": 7640348500,
    "userTags": [
      {
        "username": "ayrshare",
        "x": 0.5,
        "y": 0.5
      },
      {
        "username": "ayrshare",
        "x": 0.3,
        "y": 0.2
      }
    ]
  }
}
```

## Використана квота

Відповідь Instagram включатиме поточний `usedQuota` для кількості дописів Instagram, виконаних за rolling 24-годинний період. Instagram дозволяє лише 50 дописів у Instagram за 24-годинний період.

```json Instagram Used Quota theme={"system"}
{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "17823977408036085",
            "postUrl": "https://www.instagram.com/p/CeBrkQuN1Kv/",
            "usedQuota": 15,
            "platform": "instagram"
        }
    ],
    "id": "l4FaPHSXWJNdmMfm3dIE",
    "refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
    "post": "Luckily for Alice, the little magic bottle had now had its full effect."
}
```

Якщо квоту досягнуто, повернеться повідомлення про помилку.

## Проблеми з контентом

Ayrshare включає вбудований захист медіа, який може виявляти й вирішувати певні проблеми доставки медіа під час публікації. Коли допис успішний, але проблему з контентом було виявлено та вирішено, відповідь включає опціональний об'єкт `contentIssues`. Це дозволяє вам ідентифікувати та проактивно виправляти проблеми з хостингом медіа.

Об'єкт `contentIssues` присутній лише тоді, коли проблему виявлено та вирішено — звичайні успішні дописи його не включають.

| Поле                    | Тип              | Опис                                                                                                                                                                                                                                                                                                                              |
| ----------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `originMediaHostFailed` | boolean          | Соціальна мережа не змогла отримати медіа з наданої URL-адреси. Автоматизований захист медіа Ayrshare вирішив проблему і завершив допис успішно. Розгляньте можливість перегляду конфігурації хостингу медіа — див. [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked) для поширених причин. |
| `details`               | array of strings | Описи кожної виявленої проблеми, придатні для читання людиною.                                                                                                                                                                                                                                                                    |

```json Content Issues Response Example theme={"system"}
{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "usedQuota": 12,
            "platform": "instagram",
            "contentIssues": {
                "originMediaHostFailed": true,
                "details": [
                    "Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."
                ]
            }
        }
    ],
    "id": "abc123",
    "refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
    "post": "Your post text here"
}
```

<Tip>
  Якщо ви бачите `originMediaHostFailed` у своїх відповідях, можливо, існує проблема з хостингом ваших медіа, яка не дозволяє соціальним мережам отримувати доступ до ваших медіа. Див. [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked) для детальних кроків усунення несправностей.
</Tip>

## Деталі помилки

<Info>
  Коли публікація медіа у Instagram завершується помилкою, об'єкт помилки тепер показує основний текст помилки Meta в полі `details`, поруч з Ayrshare `code` та `message`. Це дозволяє вам відрізняти різні першопричини (наприклад, відхилення співвідношення сторін від відмови у завантаженні медіа), не звертаючись до підтримки.
</Info>

```json Instagram Publish Error theme={"system"}
{
    "status": "error",
    "errors": [
        {
            "action": "post",
            "status": "error",
            "platform": "instagram",
            "code": 156,
            "message": "An error occurred while posting to Instagram.",
            "details": "The submitted image was not found. The aspect ratio is not supported. Please see https://developers.facebook.com/docs/instagram-api for more information."
        }
    ]
}
```

`message` — це стабільне зведення Ayrshare, придатне для читання людиною, а `details` віддзеркалює необроблений текст, повернутий Meta для невдалої публікації.

## Додавання розривів рядків або rich text до допису Instagram

Розриви рядків Instagram можна додати до допису спеціальним [символом нового рядка](/apis/post/post#line-breaks).

Rich text, як-от жирний або курсивний текст, можна додати до допису Instagram кількома [html-елементами](/apis/post/overview#rich-text-posts).

## Обмеження символів

Див. [Instagram Character Limits](/help-center/technical-support/character_limits#instagram-character-limits) для отримання додаткової інформації.

## Додаткові endpoints

<Card title="Get Collaborator Request Status" icon="code" href="/apis/utils/instagram-get-collaborator" horizontal />