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 /{ig-user-id}/media: carica contenuti multimediali e crea contenitori di oggetti multimediali.
POST /{ig-user-id}/media_publish: pubblica contenuti multimediali caricati utilizzando i relativi contenitori.
GET /{ig-container-id}?fields=status_code: verifica l'idoneità alla pubblicazione e lo stato dei contenitori di contenuti multimediali.
GET /{ig-user-id}/content_publishing_limit: verifica l'utilizzo del rate limiting di pubblicazione corrente dell'utente dell'app.

Post con contenuto multimediale singolo

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

Usa l'endpoint POST /{ig-user-id}/media per creare un contenitore da un'immagine o un video ospitati sul tuo server pubblico.
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/v20.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/v20.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:

Usa l'endpoint POST /{ig-user-id}/media per creare singoli contenitori di elementi per ogni immagine o video che saranno inclusi nel carosello.
Usa nuovamente l'endpoint POST /{ig-user-id}/media per creare un singolo contenitore carosello per gli elementi.
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/v20.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/v20.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/v20.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 o un video pubblicati sono stati approvati come storia, richiedine invece il campo media_product_type.

Protocollo di caricamento ripristinabile

Il Protocollo di caricamento ripristinabile è un nuovo flusso per la pubblicazione di contenuti multimediali di Instagram che supporta i caricamenti video per i media_types reel, storie con video e caroselli con video.

Questo nuovo protocollo supporta la creazione di contenuti multimediali di Instagram sia dai video locali che dai video URL ospitati pubblici. Il protocollo ti permette di riprendere un'operazione di caricamento di file in locale dopo un'interruzione di rete o un altro errore di trasmissione, risparmiando tempo e larghezza di banda in caso di errori di rete. Mantiene le stesse specifiche dei contenuti multimediali.

Endpoint

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media: inizializza contenitori di creazioni video impostando upload_type=resumable.
POST https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}: carica video da un file video in locale o un URL ospitato in modo più sicuro utilizzando il protocollo di caricamento ripristinabile.
POST https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish: pubblica contenuti multimediali caricati utilizzando i relativi contenitori.
GET /{ig-container-id}?fields=status_code: verifica l'idoneità alla pubblicazione e lo stato dei contenitori di contenuti multimediali.

Suggerimenti per la codifica degli URL HTML

Alcuni dei parametri sono supportati in formato list/dict.
Alcuni caratteri devono essere codificati in un formato che può essere trasmesso via Internet. Ad esempio: user_tags=[{username:’ig_user_name’}] è codificato in user_tags=%5B%7Busername:ig_user_name%7D%5D dove [ è codificato in %5B e { è codificato in %7B. Per altre conversioni, consulta lo standard di codifica URL HTML.

Passaggio 1: inizializzare una sessione di caricamento per reel, storie con video o elementi carosello

Esempio di richiesta di reel

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=REELS" \
    -d "upload_type=resumable" \
    -d "caption={caption}"\
    -d "collaborators={collaborators-username}"
    -d "cover_url={cover-url}" \
    -d "audio_name={audio-name}" \
    -d "user_tags={user-tags}" \
    -d "location_id={location-id}" \
    -d "thumb_offset={thumb-offset}" \
    -H "Authorization: OAuth {access-token}"

Esempio di richiesta di video con storie

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=STORIES" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

Esempio di richiesta di elementi video carosello

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=VIDEO" \
    -d "is_carousel_item=true" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

Esempio di risposta

{
   "id": "{ig-container-id}",
   "uri": "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}"
}

Passaggio 2: caricare il video usando il Protocollo di caricamento ripristinabile

La maggior parte delle chiamate API Graph usa l'host graph.facebook.com, tuttavia, le chiamate per il caricamento di video per reel usano rupload.facebook.com.

Sono supportate le seguenti sorgenti di file per i file video caricati:

un file sul computer
un file ospitato su un server aperto al pubblico, come un CDN

Esempio di richiesta di caricamento di un file video in locale

Con l'ig-container-id restituito da una chiamata di sessione di caricamento ripristinabile, carica il video.

Assicurati che l'host sia rupload.facebook.com.
Tutti i media_type condividono lo stesso flusso per il caricamento di video.
ig-container-id è l'ID restituito dalle chiamate di sessione di caricamento ripristinabili.
access-token è lo stesso token usato nei passaggi precedenti.
offset è impostato sul primo byte caricato, generalmente 0.
file_size è impostato sulla dimensione del file in byte.
Your_file_local_path è impostato sul percorso del file in locale, ad esempio, se carichi un file dalla cartella dei Download su un macOS, il percorso è @Downloads/example.mov.

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

Esempio di richiesta di caricamento di un video ospitato pubblico

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "file_url: https://example_hosted_video.com"

Esempio di risposta

// Success Response Message
{
  "success":true,
  "message":"Upload successful."
}

// Failure Response Message
{
  "debug_info":{
    "retriable":false,
    "type":"ProcessingFailedError",
    "message":"{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}"
  }
}

Passaggio 3: (solo carosello) creare contenitori carosello

Puoi ripetere i passaggi 1 e 2 per creare più ig-container-ids con il parametro is_carousel_item impostato su true. Quindi crea un contenitore carosello per includere tutti gli elementi carosello; gli elementi carosello possono essere combinati con immagini e video.

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=CAROUSEL" \
    -d "caption={caption}"\
    -d "collaborators={collaborator-usernames}" \
    -d "location_id={location-id}" \
    -d "product_tags={product-tags}" \
    -d "children=[{ig-container-id},{ig-container-id}...]" \
    -H "Authorization: OAuth {access-token}"

Passaggio 4: pubblicare i contenuti multimediali

Per reel e storie con video, per pubblicare il video viene utilizzato il parametro {ig-container-id} creato nel passaggio 1, mentre per pubblicare il contenitore carosello viene utilizzato il parametro {ig-container-id} creato nel passaggio 3.

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish" \
    -d "creation_id={ig-container-id}" \
    -H "Authorization: OAuth {access-token}"

Passaggio 5: ottenere lo stato dei contenuti multimediali

graph.facebook.com fornisce un endpoint GET per la lettura dello stato del caricamento e il campo video_status contiene i dettagli relativi alla procedura di caricamento in locale.

Il parametro uploading_phase indica se il file è stato caricato correttamente e quanti byte sono stati trasferiti.
Il parametro processing_phase contiene i dettagli relativi allo stato dell'elaborazione video dopo il caricamento del file video.

// GET status from graph.facebook.com
curl -X GET "https://graph.facebook.com/v19.0/{ig-container-id}?fields=id,status,status_code,video_status" \
    -H "Authorization: OAuth {access-token}"

Esempio di risposta dell'endpoint `graph.facebook.com`

// A successfully created ig container
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "complete",
      "bytes_transferred": 37006904
    },
    "processing_phase": {
      "status": "complete"
    }
  }
}

// An interrupted ig container creation, from here you can resume your upload in step 2 with offset=50002. 
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "in_progress",
      "bytes_transferred": 50002
    },
    "processing_phase": {
      "status": "not_started"
    }
  }
}

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.

Pubblicazione di contenuti

Requisiti

Token d'accesso

Autorizzazioni

Server pubblico

Autorizzazione alla pubblicazione sulle Pagine

Limitazioni

Rate limiting

Endpoint

Post con contenuto multimediale singolo

Esempio di richiesta

Esempio di risposta

Esempio di richiesta

Esempio di risposta

Post carosello

Parametri

Esempio di richiesta

Esempio di risposta

Parametri

Esempio di richiesta

Esempio di risposta

Parametri

Esempio di richiesta

Esempio di risposta

Post con reel

Post delle storie

Protocollo di caricamento ripristinabile

Endpoint

Suggerimenti per la codifica degli URL HTML

Passaggio 1: inizializzare una sessione di caricamento per reel, storie con video o elementi carosello

Esempio di richiesta di reel

Esempio di richiesta di video con storie

Esempio di richiesta di elementi video carosello

Esempio di risposta

Passaggio 2: caricare il video usando il Protocollo di caricamento ripristinabile

Esempio di richiesta di caricamento di un file video in locale

Esempio di richiesta di caricamento di un video ospitato pubblico

Esempio di risposta

Passaggio 3: (solo carosello) creare contenitori carosello

Passaggio 4: pubblicare i contenuti multimediali

Passaggio 5: ottenere lo stato dei contenuti multimediali

Esempio di risposta dell'endpoint graph.facebook.com

Tag dei collaboratori

Esempio di richiesta

Note

Tag della posizione

Limitazioni

Tag dei prodotti

Tag utente

Esempio di richiesta

Note

Risoluzione dei problemi

Errori

Esempio di risposta dell'endpoint `graph.facebook.com`