API Facebook Stories di Meta

Questo documento ti mostra come usare l'API Facebook Stories per pubblicare storie sulle Pagine Facebook.

Per pubblicare una storia, devi procedere in questo modo:

1. Carica i tuoi contenuti multimediali sui server di Meta
2. Pubblica il contenuto multimediale sulla tua Pagina come storia

Prima di iniziare

Questa guida presuppone che tu abbia letto la Panoramica sull'API Pages e abbia implementato i componenti necessari, completando con successo i passaggi descritti dalla guida Primi passi.

• Dovrai implementare Facebook Login o Facebook Login for Business per chiedere agli utenti della tua app le autorizzazioni necessarie per accedere alle loro Pagine Facebook e ricevere token d'accesso della Pagina.

• Gli utenti della tua app dovranno essere in grado di eseguire l'attività CREATE_CONTENT sulla Pagina rappresentata nel token d'accesso della Pagina e concedere alla tua app le seguenti autorizzazioni:

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

Se usi un utente di sistema aziendale nelle tue richieste API, avrai bisogno anche dell'autorizzazione business_management.

Requisiti per i contenuti multimediali

Devi fornire una foto o un video che corrisponda alle seguenti specifiche.

Specifiche della foto

Specifiche del video

Limitazioni

• Una foto o un video caricati per una storia non possono essere stati usati in un post pubblicato in precedenza
• Una storia con video non può superare i 60 secondi
• Per includere le storie archiviate nelle tue richieste GET per vedere una lista delle tue storie, devi attivare l'archivio delle storie di Facebook

Best practice

Gli esempi di codice contenuti in questo documento sono formattati per una maggiore leggibilità. Sostituisci i valori corsivi in grassetto, come page_id, con i tuoi valori.

Storie con video

Per pubblicare una storia con video su una Pagina Facebook, dovrai iniziare una sessione di caricamento video con i server di Meta, caricare il video sui server di Meta e, a quel punto, potrai pubblicare la storia con video.

Passaggio 1: inizializzare la sessione

Per iniziare un sessione di caricamento, invia una richiesta POST all'endpoint /page_id/video_stories dove page_id è l'ID per la tua Pagina Facebook, con il parametro upload_phase impostato su start.

Esempio di richiesta

curl -X POST "https://graph.facebook.com/v21.0/page_id/video_stories" \
      -d '{
           "upload_phase":"start",
         }'

In caso di azione eseguita correttamente, la tua app riceve una risposta JSON con l'ID per il video e l'URL Facebook dove caricare il video.

Esempio di risposta

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v21.0/video_id",
}  

Passaggio 2: caricare un video

Ora che hai iniziato una sessione di caricamento e ricevuto l'URL di caricamento, puoi caricare il video. Puoi caricare uno di questi due file:

• un file video ospitato su un server http/https aperto al pubblico, come un CDN
• un file video locale dal tuo dispositivo

Caricamento di un file ospitato

Per caricare un file ospitato, invia una richiesta POST all'endpoint upload_url che hai ricevuto durante il passaggio di inizializzazione con i seguenti parametri:

• file_url impostato sull'URL per il tuo file video

Esempio di richiesta

curl -X POST "https://rupload.facebook.com/video-upload/v21.0/video_id" \
	-H "file_url: https://some.cdn.url/video.mp4"

Caricamento di un file locale

Per caricare un file locale, invia una richiesta POST all'endpoint upload_url che hai ricevuto durante il passaggio di inizializzazione con i seguenti parametri:

• offset impostato su 0
• file_size impostato sulle dimensioni totale in byte del video da caricare

Esempio di richiesta

curl -X POST "https://rupload.facebook.com/video-upload/v21.0/video_id" \
	-H "offset: 0" \
        -H "file_size: file_size_in_bytes" \
	--data-binary "@/path/to/file/my_video_file.mp4"

In caso di caricamento eseguito correttamente, l'app riceve la seguente risposta JSON con success impostato su true.

Esempio di risposta di caricamento

{
    "success": true
}  

Caricamento interrotto

Se il caricamento del video viene interrotto, puoi riavviare il caricamento o riprenderlo.

• Per riavviare il caricamento, invia di nuovo la richiesta POST e imposta offset su 0.
• Per riprendere il caricamento, invia di nuovo la richiesta POST con offset impostato sul valore bytes_transfered ottenuto da un controllo dello stato.

Ottenere lo stato del caricamento

Per controllare lo stato del tuo video, durante il caricamento o la pubblicazione, invia una richiesta GET all'endpoint /video_id con il seguente parametro:

• fields impostato su status

Esempio di richiesta

curl -X GET "https://graph.facebook.com/v21.0/video_id" \
	-d "fields=status"

In caso di azione eseguita correttamente, l'app riceve una risposta JSON contenente:

• un oggetto status che a sua volta contiene:

  • video_status con un valore di ready, processing, expired o error
  • l'oggetto uploading_phase con la seguente coppia di chiave-valore:

    • status impostato su in_progress, not_started, complete o error
    • bytes_transfered impostato sui byte che sono stati caricati; può essere utilizzato come valore per offset se il caricamento viene interrotto
  • l'oggetto processing_phase con la seguente coppia di chiave-valore:

    • status impostato su in_progress, not_started, complete o error
  • l'oggetto processing_phase con la seguente coppia di chiave-valore:

    • status impostato su in_progress, not_started, complete o error
    • publish_status impostato su published o not_published
    • publish_time impostato su un'indicazione temporale UNIX dell'ora effettiva o pubblicata

Esempio di risposta

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "in_progress", 
      "bytes_transfered": 50002 
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "published",
      "publish_time": 234523452 
    }
  }
}

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "complete"
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started"
    }
  }
}

Passaggio 3: pubblicare una storia con video

Per pubblicare una storia con video sulla tua Pagina, dovrai inviare un POST all'endpoint /page_id/video_stories con i seguenti parametri:

• video_id impostato come l'ID per il video caricato
• upload_phase impostato su finish

Esempio di richiesta

curl -X POST "https://graph.facebook.com/v21.0/page_id/video_stories" \
      -d '{
           "video_id": "video_id",
           "upload_phase": "finish"
         }'

In caso di azione eseguita correttamente, l'app riceve una risposta JSON contenente la seguente coppia chiave-valore:

• success impostato su true
• post_id impostato sull'ID per la pubblicazione della tua storia

Esempio di risposta

{
  "success": true,
  "post_id": 1234
}

Storie con foto

Passaggio 1: caricare una foto

Consulta il riferimento ai post della Pagina per sapere come caricare una foto sui server Meta usando l'endpoint /page_id/photos. Assicurati di includere il parametro published e di impostarlo su false.

Passaggio 2: pubblicare una storia con foto

Per pubblicare una storia con foto sulla tua Pagina, dovrai inviare un POST all'endpoint /page_id/photo_stories con i seguenti parametri:

• photo_id impostato come l'ID per la foto caricata

Esempio di richiesta

curl -X POST "https://graph.facebook.com/v21.0/page_id/photo_stories" \
      -d '{
           "photo_id": "photo_id"
         }'

In caso di azione eseguita correttamente, l'app riceve una risposta JSON contenente la seguente coppia chiave-valore:

• success impostato su true
• post_id impostato sull'ID per la pubblicazione della tua storia

Esempio di risposta

{
  "success": true,
  "post_id": 1234
}

Acquisire storie

Per ottenere una lista di tutte le storie per una Pagina e i dati relativi a ogni storia, invia una richiesta GET all'endpoint /page_id/stories dove page_id è l'ID per la Pagina che desideri visualizzare.

Esempio di richiesta

    
curl -i -X GET "https://graph.facebook.com/v21.0/page_id/stories"

In caso di azione eseguita correttamente, la tua app riceve una risposta JSON con un array di oggetti in cui ogni oggetto contiene informazioni su una storia pubblicata sulla Pagina. Ogni oggetto contiene le seguenti coppie di chiave-valore:

• post_id impostato sull'ID per la pubblicazione della storia
• status impostato su PUBLISHED, ARCHIVED
• creation_time impostato sull'indicazione temporale UNIX relativa alla pubblicazione della storia
• media_type impostato su video o photo
• media_id impostato sull'ID per il video o la foto contenuti nella storia pubblicata
• url impostato sull'URL di Facebook per la pubblicazione della storia, come https://facebook.com/stories/8283482737484972

Esempio di risposta

{
  "data": [
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "video",
      "media_id": "video_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "ARCHIVED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    ...
  ],
}

Puoi filtrare le storie per stato (pubblicato o archiviato) e data (usando i parametri since e until).

Altri contenuti da consultare

Scopri di più sui vari endpoint e concetti menzionati in questa guida.

Guide pertinenti

• Utente di sistema aziendale
• Facebook Login
• Facebook Login for Business
• API Graph - Risultati paginati con da e a

Riferimenti per gli endpoint

• Riferimento per la Pagina
• Riferimento per le storie con video della Pagina
• Riferimento per le storie con foto della Pagina
• Riferimento per i video
• Riferimento per gli insight sulle storie