Piattaforma Instagram

Pubblicazione di contenuti

Puoi utilizzare l'API Instagram Graph per pubblicare immagini, video o reel singoli (ovvero post con contenuto multimediale singolo) oppure post contenenti più immagini e video (post carosello) sugli account Instagram per professionisti.

A partire dal 1° luglio 2023, tutti i video del feed singoli pubblicati tramite l'API Content Publishing di Instagram saranno condivisi come reel.

Requisiti

Token d'accesso

Tutte le richieste devono includere il token d'accesso dell'utente dell'utente dell'app.

Autorizzazioni

La pubblicazione si basa su una combinazione delle seguenti autorizzazioni. La combinazione esatta dipende dagli endpoint utilizzati dall'app. Consulta i riferimenti dei nostri endpoint per conoscere le autorizzazioni necessarie per ogni endpoint.

Se la tua app sarà utilizzata da utenti che non hanno un ruolo al suo interno o in un Business Manager che ha reclamato l'app, devi richiedere l'approvazione per ogni autorizzazione tramite l'analisi dell'app prima che gli utenti senza un ruolo possano concedere le autorizzazioni all'app.

Server pubblico

Nei tentativi di pubblicazione, usiamo con il contenuto multimediale la funzione cURL, quindi al momento del tentativo il contenuto deve essere su un server pubblicamente accessibile.

Autorizzazione alla pubblicazione sulle Pagine

Non è possibile pubblicare su account Instagram per professionisti collegati a una Pagina che richiede l'autorizzazione alla pubblicazione sulle Pagine (PPA) fino al completamento della procedura PPA.

È possibile che un utente dell'app sia in grado di eseguire attività su una Pagina che inizialmente non richiede PPA, ma che la richiede in un secondo momento. In questo scenario, l'utente dell'app non potrebbe pubblicare contenuti sul proprio account Instagram per professionisti fino al completamento della procedura PPA. Poiché non esiste un modo per sapere se la Pagina di un utente dell'app richiede la PPA, ti consigliamo di richiedere agli utenti di completare preventivamente questa procedura.

Limitazioni

  • Il formato JPEG è l'unico formato di immagine supportato. I formati JPEG estesi come MPO e JPS non sono supportati.
  • I tag di shopping non sono supportati.
  • I tag di contenuti brandizzati non sono supportati.
  • I filtri non sono supportati.
  • La pubblicazione su Instagram TV non è supportata.

Per ulteriori limitazioni, consulta il riferimento di ogni endpoint.

Rate limiting

Gli account Instagram hanno un limite di pubblicazione di 50 post tramite API in un periodo di 24 ore. I caroselli vengono considerati come un singolo post. Questo limite viene applicato sull'endpoint POST /{ig-user-id}/media_publish quando si tenta di pubblicare un contenitore multimediale. Ti consigliamo di configurare l'app in modo che applichi il rate limiting di pubblicazione, soprattutto se consente agli utenti di programmare la pubblicazione futura dei post.

Per controllare l'utilizzo del rate limiting corrente di un account Instagram per professionisti, interroga l'endpoint GET /{ig-user-id}/content_publishing_limit.

Endpoint

L'API si compone degli endpoint seguenti. Consulta ciascun documento di riferimento dell'endpoint per le istruzioni sull'utilizzo.

Post con contenuto multimediale singolo

La procedura di pubblicazione di immagini, video, storie o reel singoli si compone di due passaggi:

  1. Usa l'endpoint POST /{ig-user-id}/media per creare un contenitore da un'immagine o un video ospitati sul tuo server pubblico.
  2. Usa l'endpoint POST /{ig-user-id}/media_publish per pubblicare il contenitore.

Passaggio 1 di 2: creazione del contenitore

Ipotizziamo che tu abbia un'immagine all'indirizzo...

https://www.example.com/images/bronz-fonz.jpg

... che desideri pubblicare con l'hashtag "#BronzFonz" come didascalia. Invia una richiesta all'endpoint POST /{ig-user-id}/media:

Esempio di richiesta

POST https://graph.facebook.com/v19.0/17841400008460056/media
  ?image_url=https://www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

Viene restituito un ID contenitore per l'immagine.

Esempio di risposta

{
  "id": "17889455560051444"  // IG Container ID
}

Passaggio 2 di 2: pubblicazione del contenitore

Usa l'endpoint POST /{ig-user-id}/media_publish per pubblicare l'ID contenitore restituito nel corso del passaggio precedente.

Esempio di richiesta

POST https://graph.facebook.com/v19.0/17841400008460056/media_publish ?creation_id=17889455560051444

Esempio di risposta

{
  "id": "17920238422030506" // IG Media ID
}

Post carosello

Puoi pubblicare fino a 10 immagini, video o un mix di immagini e video in un unico post (un post carosello). La procedura di pubblicazione di caroselli si compone di tre passaggi:

  1. Usa l'endpoint POST /{ig-user-id}/media per creare singoli contenitori di elementi per ogni immagine o video che saranno inclusi nel carosello.
  2. Usa nuovamente l'endpoint POST /{ig-user-id}/media per creare un singolo contenitore carosello per gli elementi.
  3. Usa l'endpoint POST /{ig-user-id}/media_publish per pubblicare il contenitore carosello.

Ai fini del rate limiting dell'account, i post carosello vengono conteggiati come un singolo post.

Limitazioni

  • I caroselli non possono essere messi in evidenza.
  • I caroselli sono limitati a 10 immagini, video o un mix di immagini e video.
  • Le immagini carosello sono tutte ritagliate in base alla prima immagine del carosello, con proporzioni predefinite 1:1.

Passaggio 1 di 3: creazione del contenitore di elementi

Usa l'endpoint POST /{ig-user-id}/media per la creazione di un contenitore di elementi per un'immagine o un video che saranno inclusi in un carosello. I caroselli possono avere in totale un massimo di 10 immagini, video o un mix di immagini e video.

POST /{ig-user-id}/media

Parametri

I parametri seguenti sono obbligatori. Consulta il riferimento per l'endpoint POST /{ig-user-id}/media per ulteriori parametri supportati.

  • is_carousel_item: impostato su true. Indica che l'immagine o il video sarà visibile in un carosello.
  • image_url (solo immagini): il percorso all'immagine. Useremo la funzione cURL con l'immagine utilizzando l'URL passato, quindi l'immagine deve trovarsi su un server pubblico.
  • media_type (solo video): impostato su VIDEO. Indica che il contenuto multimediale è un video.
  • video_url (solo video): percorso al video. Useremo la funzione cURL con il video utilizzando l'URL passato, quindi il video deve trovarsi su un server pubblico.

Se l'operazione va a buon fine, l'API restituirà un ID contenitore elementi che può essere utilizzato durante la creazione del contenitore carosello.

Ripeti questa procedura per ogni immagine o video da includere nel carosello.

Esempio di richiesta

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=EAAOc..."

Esempio di risposta

{
  "id": "17899506308402767"
}

Passaggio 2 di 3: creazione del contenitore carosello

Usa l'endpoint POST /{ig-user-id}/media per creare un contenitore carosello.

POST /{ig-user-id}/media

Parametri

I parametri seguenti sono obbligatori. Consulta il riferimento per l'endpoint POST /{ig-user-id}/media per ulteriori parametri supportati.

  • media_type: impostato su CAROUSEL. Indica che il contenitore è per un carosello.
  • children: un array di 10 ID contenitore massimo di ogni immagine e video che deve essere visibile nel carosello pubblicato. I caroselli possono avere in totale un massimo di 10 immagini, video o un mix di immagini e video.

Esempio di richiesta

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media?caption=Fruit%20candies&media_type=CAROUSEL&children=17899506308402767%2C18193870522147812%2C17853844403701904&access_token=EAAOc..."

Esempio di risposta

{
  "id": "18000748627392977"
}

Passaggio 3 di 3: pubblicazione del contenitore carosello

Usa l'endpoint POST /{ig-user-id}/media_publish per pubblicare un contenitore carosello (un post carosello). Gli account hanno un limite di pubblicazione di 50 post in un periodo di 24 ore. La pubblicazione di un carosello viene conteggiata come un singolo post.

POST /{ig-user-id}/media_publish

Parametri

I parametri seguenti sono obbligatori.

  • creation_id: l'ID del contenitore carosello.

Se l'operazione va a buon fine, l'API restituirà un ID contenuto multimediale di IG dell'album carosello.

Esempio di richiesta

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media_publish?creation_id=18000748627392977&access_token=EAAOc..."

Esempio di risposta

{
  "id": "90010778390276"
}

Post con reel

I reel sono brevi video idonei a essere mostrati nella tab Reels dell'app Instagram se soddisfano determinate specifiche e vengono selezionati dal nostro algoritmo. Per pubblicare un reel, segui la procedura per la pubblicazione di un post con contenuto multimediale singolo e includi il parametro media_type=REELS insieme al percorso al video usando il parametro video_url.

I reel non sono un nuovo tipo di contenuto multimediale, anche se imposti media_type=REELS quando pubblichi un reel. Se pubblichi un reel e poi ne richiedi il campo media_type, il valore restituito sarà VIDEO. Per determinare se un video pubblicato è stato approvato come reel, richiedine il campo media_product_type.

Puoi utilizzare l'esempio di codice su GitHub (insta_reels_publishing_api_sample) per scoprire come pubblicare reel su Instagram.

Per renderlo più comodo per gli sviluppatori, Meta ha pubblicato il set completo di chiamate API Graph per Instagram Reels nella piattaforma dell'API Postman. Per maggiori informazioni, consulta Raccolte Postman per Facebook Reels e Instagram Reels.

Per maggiori informazioni sui reel, consulta la documentazione sui reel per gli sviluppatori.

Post delle storie

Solo gli account business possono pubblicare storie con l'API Content Publishing al momento.

Le storie sono video e immagini pubblicati come Instagram Stories su Instagram. Per pubblicare una storia, segui la stessa procedura per la pubblicazione di un post con contenuto multimediale singolo e includi il parametro media_type=STORIES insieme al percorso all'immagine/al video usando il parametro image_url o video_url.

Nota: le storie non sono un nuovo tipo di contenuto multimediale, anche se imposti media_type=STORIES quando pubblichi una storia. Se pubblichi una storia e poi ne richiedi il campo media_type, il valore sarà restituito come IMAGE/VIDEO. Per determinare se un'immagine/un video pubblicata/o è stata/o approvata/o come storia, richiedine invece il campo media_product_type.

Tag dei collaboratori

Puoi aggiungere utenti pubblici di Instagram in un'immagine, un carosello e un reel come collaboratori; riceveranno un invito a collaborare per quel particolare contenuto multimediale. Per taggare gli utenti in un'immagine, segui la procedura precedente riportata in Post con contenuto multimediale singolo ma, alla creazione del contenitore del contenuto multimediale, includi il parametro collaborators e un array di stringhe indicante i nomi utente degli utenti Instagram che vuoi invitare come collaboratori sul contenuto multimediale.

Esempio di richiesta

POST graph.facebook.com/17841400008460056/media
?image_url=https://www.example.com/images/bronzed-fonzes.jpg
&caption=#BronzedFonzes!
&collaborators= [‘username1’,’username2’]

Note

  • Il valore collaborators deve essere un array di stringhe.
  • Puoi taggare solo utenti con account Instagram pubblici.
  • Puoi aggiungere un massimo di 3 collaboratori per contenuto multimediale.
  • Non puoi aggiungere collaboratori a un contenuto multimediale di tipo storia.

Tag della posizione

Puoi usare l' API Pages Search : assicurati di includere il campo `location` nella query per cercare le Pagine i cui nomi corrispondono a una stringa di ricerca. Quindi, analizza i risultati per identificare eventuali Pagine create per una posizione fisica. Se includi l'ID di una Pagina quando pubblichi un'immagine o un video, tale contenuto sarà taggato con la posizione associata alla Pagina.

Limitazioni

Per essere idonea a essere taggata, una Pagina deve contenere dati relativi a latitudine e longitudine.

Verifica che la Pagina che desideri utilizzare abbia i dati relativi a latitudine e longitudine nella risposta. Qualsiasi tentativo di creare un contenitore usando una Pagina senza dati sulla posizione non riuscirà, restituendo l'eccezione codificata INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID.

Dopo aver ottenuto l'ID Pagina, assegnalo al parametro location_id quando pubblichi contenitori con contenuto multimediale singolo o carosello.

Tag dei prodotti

Puoi pubblicare sia post con contenuto multimediale singolo sia post carosello taggati con prodotti Shopping su Instagram. Per scoprire come fare, consulta la guida sui Tag dei prodotti.

Tag utente

Puoi taggare utenti Instagram pubblici in un'immagine. Gli utenti taggati riceveranno una notifica.

Per taggare gli utenti in un'immagine, segui la procedura precedente riportata in Post con contenuto multimediale singolo ma, alla creazione del contenitore del contenuto multimediale, includi il parametro user_tags e un array di oggetti indicando gli utenti Instagram nell'immagine e le relative coordinate x/y all'interno dell'immagine.

Esempio di richiesta

POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &user_tags= [ { username:'kevinhart4real', x: 0.5, y: 0.8 }, { username:'therock', x: 0.3, y: 0.2 } ]

Viene restituito un ID contenitore da pubblicare usando l'endpoint per la pubblicazione di contenuti multimediali utente di IG.

Note

  • Il valore user_tags deve essere un array di oggetti in formato JSON.
  • Puoi taggare solo utenti con account Instagram pubblici.
  • L'oggetto deve contenere tutte e tre le proprietà (username, x e y) per ciascun utente.
  • I valori x e y devono essere numeri float che si originano dalla parte in alto a sinistra dell'immagine, con intervallo 0.0-1.0.
  • I tag utente possono essere usati con le immagini nei caroselli.

Risoluzione dei problemi

Se riesci a creare un contenitore per un video, ma l'endpoint POST /{ig-user-id}/media_publish non restituisce l'ID del contenuto multimediale pubblicato, puoi richiedere lo stato di pubblicazione del contenitore interrogando l'endpoint GET /{ig-container-id}?fields=status_code. Questo endpoint restituirà uno dei seguenti risultati:

  • EXPIRED: il contenitore non è stato pubblicato entro 24 ore ed è scaduto.
  • ERROR: il contenitore non è riuscito a completare la procedura di pubblicazione.
  • FINISHED: il contenitore e il relativo oggetto multimediale sono pronti per essere pubblicati.
  • IN_PROGRESS: il contenitore è ancora in fase di pubblicazione.
  • PUBLISHED: l'oggetto multimediale del contenitore è stato pubblicato.

Ti consigliamo di interrogare lo stato di un contenitore una volta al minuto, per non più di 5 minuti.

Errori

Consulta il riferimento Codici di errore.