Piattaforma Messenger

Riferimento per l'API Send

L'API Send è l'API principale usata per inviare messaggi agli utenti, compresi testo, allegati, modelli, azioni del mittente e altro ancora.

Creazione

Crea e invia messaggi ai tuoi clienti o alle persone interessate alla tua Pagina Facebook.

Prima di iniziare

Ecco cosa ti servirà:

  • Un token d'accesso della Pagina richiesto da una persona che può eseguire l'attività MESSAGE sulla Pagina
  • L'autorizzazione pages_messaging
  • Il destinatario del messaggio deve aver inviato alla tua Pagina un messaggio nelle 24 ore precedenti o aver accettato di ricevere messaggi dalla tua Pagina al di fuori della finestra dei messaggi standard di 24 ore

Limitazioni

  • Non è possibile usare i tag dei messaggi per inviare contenuto promozionale.

Tieni presente che l'API Send non include il parametro recipient_id nella risposta per i messaggi inviati usando recipient.user_ref o recipient.phone_number per identificare il destinatario del messaggio.

Esempio di richiesta

Per inviare un messaggio a una persona, invia una richiesta POST all'endpoint /PAGE-ID/messsages con i parametri messaging_type e recipient impostati e il contenuto del messaggio.

Formattato per una maggiore leggibilità.

Il seguente esempio è una risposta inviata dalla tua Pagina al messaggio di una persona e contiene solo testo.

curl -X POST "https://graph.facebook.com/v20.0/{PAGE_ID}/messages" \
      -d "recipient={'id':'{PSID}'}" \
      -d "messaging_type=RESPONSE" \
      -d "message={'text':'hello, world'}" \
      -d "access_token={PAGE_ACCESS_TOKEN}"

Se l'azione viene eseguita correttamente, l'app riceve la seguente risposta JSON:

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
}

Parametri

ParametroDescrizione

message

oggetto

Il tipo di messaggio inviato dalla tua Pagina. Quando si utilizza questo parametro deve essere impostata una tra le opzioni text e attachement.

  • Oggetto attachment: visualizza in anteprima l'URL. Utilizzato per inviare messaggi con contenuto multimediale o messaggi strutturati. Deve essere impostata un'opzione tra text e attachment.

    • type: tipo di allegato. Può essere audio, file, image, template o video. Dimensioni massime del file: 25 MB.
    • payload: un oggetto con contenuto modello o contenuto file.

  • metadata: una stringa di dati aggiuntivi che desideri passare nel webhook message_echo. Deve contenere meno di 1000 caratteri.

  • quick_replies: un array di risposte rapide da inviare in un messaggio.
  • text: un messaggio contenente solo testo. Deve essere UTF-8 e contenere meno di 2000 caratteri.

messaging_type

enum

Obbligatorio

Il tipo di messaggio inviato.

  • RESPONSE: il messaggio è inviato in risposta a un messaggio ricevuto. Sono compresi messaggi promozionali e non promozionali inviati all'interno della finestra dei messaggi standard di 24 ore. Per esempio, utilizza questo tag per rispondere se una persona chiede la conferma di una prenotazione o un aggiornamento dello stato.
  • UPDATE: il messaggio viene inviato in modo proattivo e non in risposta a un messaggio ricevuto. Sono compresi messaggi promozionali e non promozionali inviati all'interno della finestra dei messaggi standard di 24 ore.
  • MESSAGE_TAG: il messaggio è non promozionale ed è inviato al di fuori della finestra dei messaggi standard di 24 ore con un tag nel messaggio. Il messaggio deve soddisfare il caso d'uso consentito per il tag.

notification_type

enum

Il tipo di notifica push ricevuta da una persona.

  • NO_PUSH: nessuna notifica.
  • REGULAR (predefinito): suono o vibrazione quando una persona riceve un messaggio.
  • SILENT_PUSH: solo notifica su schermo.

recipient

oggetto

Obbligatorio

La persona che riceverà il messaggio inviato dalla tua Pagina.

  • id: l'ID per singola Pagina per la persona utilizzato per rispondere a un messaggio ricevuto dalla tua Pagina entro 24 ore o per una persona che ha accettato di ricevere messaggi dalla tua Pagina al di fuori della finestra dei messaggi standard di 24 ore.
  • user_ref: il riferimento per la persona utilizzato per inviare un messaggio in risposta a un plug-in della casella di spunta o per la chat.
  • comment_id: l'ID per il commento utilizzato per inviare un messaggio come risposta privata al commento di un ospite su un post della tua Pagina.
  • post_id: l'ID per il post della Pagina utilizzato per inviare un messaggio come risposta privata al post di un ospite sulla tua Pagina.

sender_action

enum

L'icona di azione mostrata nella finestra dei messaggi che rappresenta l'azione della Pagina su un messaggio ricevuto da una persona.

  • typing_on: visualizza il fumetto di digitazione mentre la Pagina sta scrivendo una risposta.
  • typing_off: non visualizza il fumetto di digitazione.
  • mark_seen: visualizza l'icona di visualizzato per i messaggi che sono stati visualizzati dalla Pagina.

Può essere inviato solo con il parametro recipient. Non può essere inviato con il parametro message, deve essere inviato come richiesta separata.

tag

enum

Un tag che abilita la tua Pagina all'invio di un messaggio a una persona al di fuori della finestra dei messaggi standard di 24 ore.

  • ACCOUNT_UPDATE: tagga il messaggio che invii al cliente come aggiornamento non ricorrente dell'app o dell'account di quel cliente. Visualizza gli usi consentiti.

    Non disponibile per l'API per i messaggi di Instagram.

  • CONFIRMED_EVENT_UPDATE: tagga il messaggio che invii al cliente come promemoria di un evento in programma o un aggiornamento per un evento in corso per cui il cliente si è registrato. Visualizza gli usi consentiti.

    Non disponibile per l'API per i messaggi di Instagram.

  • CUSTOMER_FEEDBACK: tagga il messaggio che invii al cliente come sondaggio sul feedback dei clienti . I messaggi relativi ai feedback dei clienti devono essere inviati entro 7 giorni dall'ultimo messaggio del cliente. Visualizza gli usi consentiti.

    Non disponibile per l'API per i messaggi di Instagram.

  • HUMAN_AGENT: obbligatorio per l'API per i messaggi di Instagram. L'aggiunta di questo tag a un messaggio destinato a una persona consente a un operatore reale di rispondere. I messaggi possono essere inviati entro 7 giorni dal messaggio di quella persona. Il supporto con operatore reale viene utilizzato per la risoluzione di problemi che non possono essere risolti entro la finestra dei messaggi standard. Visualizza gli usi consentiti.
    • Le app devono richiedere l'autorizzazione Human Agent tramite la Dashboard gestione app per sviluppatori. Accedi a Dashboard gestione app -> Analisi dell'app -> Autorizzazioni e funzioni -> Human Agent. Le app precedentemente approvate per l'accesso beta all'autorizzazione Human Agent non devono richiedere nuovamente l'accesso.

    L'autorizzazione Human Agent non è disponibile in accesso standard o in modalità sviluppatore. Dovrai completare il processo di analisi dell'app prima di poter sfruttare il tag Human Agent. Durante l'invio per l'analisi dell'app, fornisci istruzioni chiare e una dimostrazione su come intendi sfruttare il tag Human Agent nelle tue esperienze.

  • POST_PURCHASE_UPDATE: tagga il messaggio che invii al cliente come aggiornamento per un acquisto recente effettuato dal cliente. Visualizza gli usi consentiti.

    Non disponibile per l'API per i messaggi di Instagram.

Utilizzo dei tag dei messaggi

La tabella seguente elenca i tipi di messaggi per ogni tag.

Tag nel messaggioUtilizzo

ACCOUNT_UPDATE

Utilizzi consentiti

  • Notifica di un cambiamento di stato per un'app, ad esempio per una carta di credito o una candidatura a un lavoro.
  • Notifica di attività sospette, come avvisi di frode.

Utilizzi non consentiti (non è un elenco completo)

  • Contenuto promozionale, tra cui il contenuto ricorrente di offerte, promozioni, coupon e sconti (ad esempio, l'estratto conto è pronto, la bolletta è in scadenza, nuove offerte di lavoro).
  • Messaggi relativi a qualsiasi survey, sondaggio o recensione non correlato a una precedente interazione in Messenger.

Non disponibile per l'API per i messaggi di Instagram.

CONFIRMED_EVENT_UPDATE

Utilizzi consentiti

  • Promemoria per una lezione, un appuntamento o un evento in programma che un utente ha pianificato.
  • Conferma della prenotazione o della partecipazione dell'utente a un evento o a un appuntamento accettato.
  • Notifica del trasporto o del viaggio programmato da un utente, come arrivo, cancellazione, ritardo del bagaglio o altri cambiamenti di stato.

Utilizzi non consentiti (non è un elenco completo)

  • Contenuti promozionali, inclusi ma non limitati a promozioni, offerte, coupon e sconti.
  • Contenuti relativi a un evento a cui l'utente non si è registrato (ad es. promemoria per l'acquisto di biglietti per eventi, cross-selling di altri eventi, programmi di tour, ecc.).
  • Messaggi relativi ad eventi passati.
  • Messaggi relativi a qualsiasi survey, sondaggio o recensione non correlato a una precedente interazione in Messenger.

Non disponibile per l'API per i messaggi di Instagram.

CUSTOMER_FEEDBACK

Utilizzi consentiti

  • Un sondaggio per acquisire feedback sull'assistenza agli acquisti.
  • Un sondaggio per acquisire feedback su un evento.
  • Recensioni dei prodotti.

Utilizzi non consentiti (non è un elenco completo)

  • Il tag può essere usato solo con il Modello di feedback del cliente. L'utilizzo in qualsiasi altra forma è vietato e non andrà a buon fine.

Non disponibile per l'API per i messaggi di Instagram.

HUMAN_AGENT

Utilizzi consentiti

  • Supporto di un operatore per problemi che non possono essere risolti entro la finestra dei messaggi standard di 24 ore (ad esempio, risoluzione di problemi al di fuori dei normali orari di apertura o di problemi la cui risoluzione richiede più di 24 ore).

Utilizzi non consentiti (non è un elenco completo)

  • Messaggi automatici.
  • Contenuto non correlato alla richiesta dell'utente.

Obbligatorio per l'API per i messaggi di Instagram.

POST_PURCHASE_UPDATE

Utilizzi consentiti

  • Conferma della transazione, come fatture o ricevute.
  • Aggiornato di stato della spedizione, come prodotto in transito, spedito, consegnato o in ritardo.
  • Aggiornamento di stato che richiede a un utente di eseguire una determinata azione in relazione a un ordine effettuato, come ad esempio carta di credito rifiutata, articoli in riassortimento o altri aggiornamenti dell'ordine che richiedono un'azione da parte dell'utente.

Utilizzi non consentiti (non è un elenco completo)

  • Contenuti promozionali, compresi, a titolo esemplificativo, offerte, promozioni, coupon e sconti.
  • Messaggi di cross-selling o up-selling di prodotti o servizi.
  • Messaggi relativi a qualsiasi survey, sondaggio o recensione non correlato a una precedente interazione in Messenger.

Non disponibile per l'API per i messaggi di Instagram.

Lettura

Non puoi eseguire questa operazione su questo endpoint.

Per ottenere informazioni sulle conversazioni della tua Pagina, consulta il riferimento sulle conversazioni della Pagina.

Aggiornamento

Non puoi eseguire questa operazione su questo endpoint.

Eliminazione

Non puoi eseguire questa operazione su questo endpoint.

Altri contenuti da consultare

Assistenza per gli sviluppatori