IT
Tutorial

Inviare messaggi con l'API Facebook Messenger: tutorial Node.js, Python e PHP

Le regole della Send API di Meta nel 2026, poi una sola chiamata REST per inviare dagli account dei vostri utenti.

La tua app Live
FacebookAnna LeePersonale FacebookNorthwind BakeryPagina
Chat personale
Tom BeckerDa Anna Lee
Possiamo spostare la demo?
Giovedì alle 10 per me va bene.
Visualizzato
Chat della Pagina
Maya RossA Northwind Bakery
Consegnate anche la domenica?
Sì, dalle 9 alle 12.
Consegnato
GETchats POSTmessages/send POSTchats/send 200 OK
In breve

Esistono due modi per inviare un messaggio Facebook Messenger via API. La Send API di Meta invia da una Pagina Facebook, con un Page access token, solo alle persone che hanno scritto alla Pagina nelle ultime 24 ore. Un'API unificata come Unipile invia dall'account collegato del vostro utente (un account personale o una Pagina che gestisce) con una sola chiamata REST: POST /v2/{account_id}/chats/{chat_id}/messages/send.

POST/{PAGE-ID}/messagesMeta: rispondere come Pagina
POST/v2/{account_id}/chats/{chat_id}/messages/sendUnipile: rispondere in una chat esistente
POST/v2/{account_id}/chats/sendUnipile: scrivere per primi
Con Unipile

Inviate un messaggio Messenger in tre passaggi

  1. 1

    Collegate. L'utente collega il suo account Facebook o la sua Pagina tramite Hosted Auth. Nessuna app Meta, nessuna App Review.

  2. 2

    Inviate. Chiamate POST /v2/{account_id}/chats/{chat_id}/messages/send con la vostra X-API-KEY e un text.

  3. 3

    Ascoltate. Il webhook message.new conferma l'invio e riporta le risposte.

Scegliere una strada

Due modi per inviare un messaggio Messenger via API

La Send API di Meta agisce per una Pagina gestita dalla vostra app. Unipile agisce per l'account collegato dal vostro utente finale.

CriterioSend API di MetaAPI Unipile
MittenteUna Pagina FacebookL'account personale dell'utente o una Pagina che gestisce
ConfigurazioneApp Meta, Page token con pages_messaging, App Review per servire le Pagine di altre aziendeChiave API e un account_id ottenuto da Hosted Auth, nessuna app Meta
Chi scrive per primoSempre la personaUn account personale può farlo; una Pagina può solo rispondere
Finestra24 ore, fino a 7 giorni dopo un'inserzione Click-to-MessengerNessuna finestra della Send API; Facebook può rifiutare un destinatario
Mittente
Send API di MetaUna Pagina Facebook
API UnipileL'account personale dell'utente o una Pagina che gestisce
Configurazione
Send API di MetaApp Meta, Page token con pages_messaging, App Review per servire le Pagine di altre aziende
API UnipileChiave API e un account_id ottenuto da Hosted Auth, nessuna app Meta
Chi scrive per primo
Send API di MetaSempre la persona
API UnipileUn account personale può farlo; una Pagina può solo rispondere
Finestra
Send API di Meta24 ore, fino a 7 giorni dopo un'inserzione Click-to-Messenger
API UnipileNessuna finestra della Send API; Facebook può rifiutare un destinatario

Un bot per la vostra Pagina si adatta alla strada di Meta; un CRM, un helpdesk o un agente IA nelle conversazioni dei vostri clienti ha bisogno di un account collegato. Per la mappa completa, vedete come si combinano le API di Facebook.

Send API di Meta

Come inviare un messaggio con la Facebook Graph API (Send API)

La strada ufficiale di Meta è la Send API della Messenger Platform: POST https://graph.facebook.com/v27.0/{PAGE-ID}/messages con un Page access token che dispone di pages_messaging, un recipient.id, un messaging_type e un oggetto message. Risponde solo alle persone che hanno scritto alla vostra Pagina.

1

Creare un'app Meta e collegare una Pagina

Aggiungere Messenger, collegare la Pagina.

2

Ottenere un Page access token

Con pages_messaging; App Review per servire altre aziende. Consultate la nostra guida al token di accesso dell'API Facebook.

3

Inviare la richiesta

Indicare la persona tramite il suo PSID (Page-scoped ID), letto dal webhook messages.

Facebook Richiesta alla Send API
access_tokenPage access token
recipient.idIl PSID della persona
messaging_typeRESPONSE, UPDATE o MESSAGE_TAG
message.text"Ciao, mondo!"
responserecipient_id, message_id
POST graph.facebook.com/v27.0/{PAGE-ID}/messages 200 OK
  • RESPONSE: una risposta, entro la finestra.
  • UPDATE: un messaggio inviato su vostra iniziativa, entro la finestra.
  • MESSAGE_TAG: fuori dalla finestra, con un tag e contenuto non promozionale.

Da dove arriva il PSID

1In entrata

Una persona scrive alla vostra Pagina

Messenger
2POST

Meta chiama il vostro webhook

evento messages
3PSID

Leggere l'ID del mittente

messaging[0].sender.id
4POST

Rispondere con la Send API

recipient.id = PSID

Nell'evento messages, sender.id è il PSID della persona e recipient.id è l'ID della vostra Pagina. Copiate la richiesta dalle schede Meta cURL, Node.js, Python e PHP del blocco di codice qui sotto.

Fonti: la documentazione Send a Message e evento webhook messages di Meta. Ultima verifica: 17 novembre 2026.

Regole

La finestra di 24 ore di Messenger e i message tag nel 2026

La Send API scrive solo alle persone che hanno scritto alla Pagina, per 24 ore dopo il loro ultimo messaggio, o fino a 7 giorni dopo un'inserzione Click-to-Messenger. Oltre, HUMAN_AGENT copre una risposta umana entro 7 giorni, mentre tre tag di aggiornamento falliscono con l'errore 100 dal 27 aprile 2026.

Inizio

La persona scrive

Si apre la finestra standard.

Da 0 a 24 h

Finestra aperta

Inviare con RESPONSE o UPDATE.

Fino a 7 giorni

Operatore umano

Tag HUMAN_AGENT, per una risposta scritta da una persona.

Dopo

Finestra chiusa

Attendere un nuovo messaggio.

Ritirati il 27 aprile 2026

Le richieste con i tag CONFIRMED_EVENT_UPDATE, ACCOUNT_UPDATE o POST_PURCHASE_UPDATE ora falliscono con il codice di errore 100.

Fonti: il riferimento della Send API e Send a Message di Meta. Ultima verifica: novembre 2026.

Tutorial

Inviare un messaggio Facebook Messenger da un account collegato (Node.js, Python, PHP, cURL)

Il vostro utente collega il proprio account Facebook una sola volta e voi ottenete un account_id. Elencate le sue chat, poi inviate in un chat_id. Le richieste vanno a https://api.unipile.com con la vostra chiave nell'header X-API-KEY, tramite l'API Facebook Messenger di Unipile. Le schede Meta inviano la stessa risposta con la Send API di Meta, da una Pagina che gestite.

1

Collegare l'account

L'utente accede da una pagina Hosted Auth. Dettagli nella nostra guida all'API Messenger per account personali.

2

Elencare le chat

GET /v2/{account_id}/chats restituisce fino a 100 chat per pagina.

3

Inviare il messaggio

Un solo POST con un campo text.

# 1. List chats
curl --request GET \
     --url 'https://api.unipile.com/v2/acc_123456789/chats?limit=20' \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json'

# 2. Send a message
curl --request POST \
     --url https://api.unipile.com/v2/acc_123456789/chats/CHAT_ID/messages/send \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{ "text": "Thanks, your order ships today." }'
// npm i @unipile/sdk
import { UnipileMessaging } from '@unipile/sdk';

const request_options = {
  baseUrl: 'https://api.unipile.com',
  headers: { 'X-API-KEY': 'YOUR_API_KEY' },
  throwOnError: true,
};
const messagingApi = new UnipileMessaging();

// 1. List chats
const chats = await messagingApi.getChatsList({
  ...request_options,
  path: { account_id: 'acc_123456789' },
  query: { limit: 20 },
});

// 2. Send a message
await messagingApi.sendMessage({
  ...request_options,
  path: { account_id: 'acc_123456789', chat_id: 'CHAT_ID' },
  body: { text: 'Thanks, your order ships today.' },
});
import unipile

configuration = unipile.Configuration()
configuration.api_key["apiKey"] = "YOUR_API_KEY"
api_client = unipile.ApiClient(configuration)
messaging_api = unipile.MessagingApi(api_client)

# 1. List chats
chats = messaging_api.get_chats_list("acc_123456789", limit=20)

# 2. Send a message
messaging_api.send_message(
    "CHAT_ID",
    "acc_123456789",
    {"text": "Thanks, your order ships today."},
)
<?php
$base = 'https://api.unipile.com/v2/acc_123456789';
$headers = ['X-API-KEY: YOUR_API_KEY', 'accept: application/json'];

// 1. List chats
$ch = curl_init("$base/chats?limit=20");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);
$chats = json_decode(curl_exec($ch), true);
curl_close($ch);

// 2. Send a message
$ch = curl_init("$base/chats/CHAT_ID/messages/send");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => array_merge($headers, ['content-type: application/json']),
    CURLOPT_POSTFIELDS => json_encode(['text' => 'Thanks, your order ships today.']),
    CURLOPT_RETURNTRANSFER => true,
]);
$sent = json_decode(curl_exec($ch), true);
curl_close($ch);
# Meta Send API: reply to a person who messaged your Page
curl -X POST \
     "https://graph.facebook.com/v27.0/PAGE_ID/messages?access_token=PAGE_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "recipient": { "id": "PSID" },
       "messaging_type": "RESPONSE",
       "message": { "text": "Thanks, your order ships today." }
     }'
// Node.js 18+: built-in fetch, no SDK
const url = 'https://graph.facebook.com/v27.0/PAGE_ID/messages'
  + '?access_token=' + process.env.PAGE_ACCESS_TOKEN;

const res = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    recipient: { id: 'PSID' },
    messaging_type: 'RESPONSE',
    message: { text: 'Thanks, your order ships today.' },
  }),
});
const data = await res.json(); // { recipient_id, message_id }
# pip install requests
import requests

resp = requests.post(
    "https://graph.facebook.com/v27.0/PAGE_ID/messages",
    params={"access_token": "PAGE_ACCESS_TOKEN"},
    json={
        "recipient": {"id": "PSID"},
        "messaging_type": "RESPONSE",
        "message": {"text": "Thanks, your order ships today."},
    },
)
print(resp.json())  # {"recipient_id": "...", "message_id": "..."}
<?php
$url = 'https://graph.facebook.com/v27.0/PAGE_ID/messages?access_token=PAGE_ACCESS_TOKEN';
$payload = [
    'recipient' => ['id' => 'PSID'],
    'messaging_type' => 'RESPONSE',
    'message' => ['text' => 'Thanks, your order ships today.'],
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
]);
$sent = json_decode(curl_exec($ch), true); // recipient_id, message_id
curl_close($ch);
200 OK · { "object": "MessageSent", "message_id": "..." }
200 OK · { "recipient_id": "PAGE-SCOPED-ID", "message_id": "AG5Hz2U..." }

Le prime quattro schede chiamano Unipile per un account collegato; la stessa richiesta funziona per LinkedIn, WhatsApp, Instagram e Telegram. Le schede Meta chiamano la Send API di Meta per la vostra Pagina, con un Page access token e il PSID della persona (come ottenere il PSID). Riferimenti: Unipile Facebook, Send messages e Meta Send a Message (v27.0, verificato il 17 novembre 2026).

Primo messaggio

Come avviare una nuova conversazione Messenger via API

Quando non esiste ancora una chat, chiamate POST /v2/{account_id}/chats/send con l'ID della persona in users_ids e il vostro text. La Send API di Meta non lo consente.

Base URL https://api.unipile.com
POST/v2/{account_id}/chats/sendStart a Chat
users_idsID di una persona o di una Pagina
text"Ciao Tom, una domanda veloce"
attachmentsFile facoltativi
SDK: startChat (Node.js), start_chat (Python) 200 OK

La risposta restituisce il nuovo chat_id e il message_id.

Se Facebook non consente all'account di scrivere a questa persona, la richiesta fallisce con provider/access_restricted.

Limiti dell'inbox di una Pagina

Una Pagina non può avviare una conversazione (501 api/not_implemented) né eliminare i propri messaggi.

Pagine

Come rispondere come Pagina Facebook via API

Una Pagina gestita dall'utente risponde tramite lo stesso account_id: elencate le inbox, aprite l'inbox della Pagina, poi inviate con l'ID di una chat della Pagina. Come funzionano le Pagine e i loro token lato Meta è spiegato nella nostra guida all'API Pagine Facebook.

Facebook Inbox personale · INBOX
Tom BeckerGiovedì alle 10 per me va bene.Personale
chat_id: {chat_id}
Facebook Inbox della Pagina · PAGE_<page_id>_INBOX
Maya RossConsegnate anche la domenica?Pagina
chat_id: PAGE_<page_id>_<thread_key>
GET/v2/{account_id}/inboxesElenca le inbox delle Pagine
GET/v2/{account_id}/inboxes/{inbox_id}/chatsElenca le chat della Pagina
POST/v2/{account_id}/chats/PAGE_1357020157484056_100001234567890/messages/sendRisponde come Pagina

L'elenco generale delle chat restituisce solo le chat personali. Il prefisso PAGE_ fa agire Unipile come la Pagina. Dettagli nella documentazione Facebook Pages.

Allegati

Inviare immagini e file in una chat Messenger

Aggiungete un array attachments allo stesso endpoint di invio. Per i file di grandi dimensioni, usate il multipart.

POST/v2/{account_id}/chats/{chat_id}/messages/sendSend a Message
textDidascalia facoltativa, può essere ""
contentIl file codificato in base64
content_type"image/png"
filename"image.png"
File di grandi dimensioni: multipart/form-data 200 OK

Chat crittografate. Nelle chat personali con crittografia end-to-end, ogni file viene inviato come messaggio separato.

Equivalente Meta. La Send API accetta un oggetto attachment con un type e un url, fino a 30 immagini per invio.

Tempo reale

Confermare la consegna e ricevere le risposte con i webhook

Un 200 significa che Facebook ha accettato il messaggio, non che è stato consegnato. La consegna è confermata dall'evento webhook message.new, che porta anche le risposte.

1POST

La vostra app invia

messages/send
2Accettato

Unipile risponde

200 MessageSent
3Confermato

Webhook: inviato

message.new
4Conferme

Consegnato, poi letto

message.receipt.delivery message.receipt.read
Facebook Evento message.new
type"message.new"
account_idL'account collegato
payloadUn oggetto Message: id, chat_id, sender_id, text, timestamp, is_sender

Si attiva per i messaggi inviati e ricevuti; vedete is_sender.

Smistate gli eventi delle Pagine in base al prefisso PAGE_<page_id>_ del loro chat_id, che può differire da quello dell'API. Configurazione in Configure a webhook.

Lato Meta, un bot di Pagina costruito sulla Send API richiede un proprio webhook Messenger. È anche il punto in cui leggete il PSID prima di rispondere.

Fonte: i webhook Messenger di Meta. Ultima verifica: 17 novembre 2026.

Facebook Webhook Messenger di Meta
VerificaGET con hub.mode=subscribe e il vostro hub.verify_token: restituite hub.challenge
FirmaX-Hub-Signature-256: SHA256 del payload con il vostro App Secret
Campimessages, message_deliveries
Risposta200 OK entro 5 secondi
Errori

Errori nell'invio di messaggi Messenger

La maggior parte degli errori di invio deriva da una regola: un nuovo tentativo fallisce di nuovo. Un token senza pages_messaging blocca ogni chiamata alla Send API.

ErroreSignificatoSoluzione
Meta 100Parametro non valido, o un tag ritirato il 27 aprile 2026Verificate il PSID, eliminate il tag
Meta 10 / 2018278Messaggio inviato fuori dalla finestra consentitaAttendete un nuovo messaggio, oppure inviate una risposta HUMAN_AGENT
Meta 200 / 2018028Impossibile scrivere a persone che non sono amministratori, sviluppatori o tester dell'app: pages_messaging non ancora approvatoCompletate l'App Review, nel frattempo testate con i ruoli dell'app
Meta 551Questa persona al momento non riceve i vostri messaggiNon riprovate
Meta 613Rate limit superatoInviate meno spesso
Unipile provider/access_restrictedFacebook rifiuta questo destinatario per l'accountNon riprovate
Unipile 403 api/insufficient_permissionsPagina non attivata sull'accountAttivatela alla riconnessione
Unipile 501 api/not_implementedUna Pagina ha avviato una chat o eliminato un messaggioRispondete in una chat esistente
Meta 100
SignificatoParametro non valido, o un tag ritirato il 27 aprile 2026
SoluzioneVerificate il PSID, eliminate il tag
Meta 10 / 2018278
SignificatoMessaggio inviato fuori dalla finestra consentita
SoluzioneAttendete un nuovo messaggio, oppure inviate una risposta HUMAN_AGENT
Meta 200 / 2018028
SignificatoImpossibile scrivere a persone che non sono amministratori, sviluppatori o tester dell'app: pages_messaging non ancora approvato
SoluzioneCompletate l'App Review, nel frattempo testate con i ruoli dell'app
Meta 551
SignificatoQuesta persona al momento non riceve i vostri messaggi
SoluzioneNon riprovate
Meta 613
SignificatoRate limit superato
SoluzioneInviate meno spesso
Unipile provider/access_restricted
SignificatoFacebook rifiuta questo destinatario per l'account
SoluzioneNon riprovate
Unipile 403 api/insufficient_permissions
SignificatoPagina non attivata sull'account
SoluzioneAttivatela alla riconnessione
Unipile 501 api/not_implemented
SignificatoUna Pagina ha avviato una chat o eliminato un messaggio
SoluzioneRispondete in una chat esistente

Fonti: i codici di errore di Messenger di Meta e le risposte di errore di Unipile. Ultima verifica: 17 novembre 2026.

Conformità

Ogni utente invia dal proprio account

Unipile è un'azienda indipendente, non un'app ufficiale di Meta né un Meta Partner. Agisce per conto degli utenti autenticati, che restano vincolati ai termini di Meta. Usatela per assistenza clienti, CRM e conversazioni dirette.

Inviate il vostro primo messaggio

La Send API di Meta è adatta a un bot sulla vostra Pagina. Per inviare messaggi con l'API Facebook Messenger dagli account dei vostri utenti, collegateli tramite Unipile.

Commissione europea
Regolamentato dall'UE Digital Markets Act (DMA)

Ogni utente collega il proprio account, senza archiviazione dei profili. Unipile non è un Meta Partner. Il nostro approccio al Digital Markets Act

Tutti gli endpoint dell'API Facebook in un unico posto

I messaggi ne sono solo una parte. Consultate tutti gli endpoint Facebook disponibili con Unipile, dai post ai commenti fino a profili e webhook, oppure leggete la guida completa all'API Facebook.

FAQ: inviare messaggi con l'API Facebook Messenger

Risposte rapide sull'invio di messaggi Messenger via API.

No. La Send API raggiunge solo le persone che hanno scritto alla vostra Pagina, entro la finestra di messaggistica, e una Pagina non scrive mai per prima. Una nuova conversazione deve partire da un account personale collegato, ad esempio con POST /v2/{account_id}/chats/send di Unipile.

Meta non indica alcun SDK Python ufficiale per la Send API: inviate un POST a /{PAGE-ID}/messages con requests, come nella scheda Meta Python qui sopra. Unipile fornisce un SDK Python, importato come unipile, con get_chats_list e send_message.

Inviate un POST HTTP con cURL o Guzzle: a /{PAGE-ID}/messages sulla Graph API con un Page access token (scheda Meta PHP), oppure a /v2/{account_id}/chats/{chat_id}/messages/send su Unipile con la vostra X-API-KEY (scheda PHP).

Installate @unipile/sdk e chiamate sendMessage con account_id, chat_id e text, come nella scheda Node.js qui sopra. Per la Send API di Meta, inviate un POST a /{PAGE-ID}/messages con fetch, come nella scheda Meta Node.js.

Con la Send API: una finestra chiusa (errore 10, sottocodice 2018278), un tag ritirato il 27 aprile 2026 (errore 100), un token senza pages_messaging approvato (errore 200, sottocodice 2018028) o una persona che blocca i vostri messaggi (errore 551). Con Unipile: provider/access_restricted quando Facebook rifiuta il destinatario, oppure una Pagina che tenta di avviare una conversazione.

Per un bot di Pagina sulla piattaforma di Meta, il vostro endpoint risponde alla verifica GET restituendo hub.challenge, controlla la firma X-Hub-Signature-256 con il vostro App Secret e si iscrive a messages; il sender.id di ogni evento è il PSID a cui rispondete. Con Unipile, registrate un solo URL e ricevete gli eventi message.new per ogni account collegato.

No. Unipile è un'azienda indipendente: non è un Meta Partner e non è sostenuta, sponsorizzata né approvata da Meta. Le schede Meta di questa pagina chiamano la Send API pubblica di Meta; le altre schede chiamano l'API di Unipile. Facebook e Messenger sono marchi di Meta Platforms, Inc.

No. L'app Meta, il Page token e l'App Review riguardano solo la strada della Send API. Con Unipile, i vostri utenti collegano il proprio account Facebook, o le Pagine che gestiscono, tramite l'autenticazione ospitata, e voi inviate con un account_id e la vostra chiave API.

Unipile è progettata nello spirito del Digital Markets Act: ogni utente collega il proprio account e i messaggi partono per suo conto, nelle sue conversazioni, senza che Unipile memorizzi i profili utente. Dettagli nella nostra pagina sul Digital Markets Act.

Sì. Ogni account collegato resta vincolato alle Condizioni d'uso di Meta. Inviate messaggi per esigenze legittime come risposte di assistenza, follow-up CRM e conversazioni che le persone si aspettano; i messaggi non richiesti in massa e lo spam possono portare alla limitazione dell'account.

Avete ancora domande? Il nostro team è qui per aiutarvi.

Parla con un esperto