Documentazione
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Ricevere messaggi di testo WhatsApp

Un contatto che scrive nella chat produce un messaggio in entrata con text. È il tipo di messaggio in entrata più comune, e quello che apre o azzera la finestra di servizio clienti.

Cosa contiene un messaggio di testo in entrata

text.body contiene ciò che il contatto ha digitato, e nient'altro è presente sul ramo:
Esempio di codice
{
  "id": "wam_01kya19eknftrs2s6p82asmvnh",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "text": { "body": "Is my order out for delivery yet?" },
  "created_at": "2026-08-25T09:04:11Z"
}
preview_url è un campo lato invio. Un messaggio di testo in entrata non porta alcun flag per l'anteprima del link, indipendentemente da ciò che il client del contatto ha mostrato, quindi un URL in body viene restituito come parte del testo.
Lo schema di lettura non dichiara un massimo per un body in entrata. Il limite di 4096 caratteri appartiene al lato invio, quindi dimensiona il tuo storage come testo illimitato anziché su un limite che il ramo in entrata non garantisce.

Un messaggio di testo inviato come risposta citata

Quando il contatto risponde a uno dei tuoi messaggi citandolo, il ramo resta invariato e in_reply_to_message_id indica il messaggio a cui ha risposto:
Esempio di codice
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "text": { "body": "Yes, that one" },
  "created_at": "2026-08-25T09:06:02Z"
}
WhatsApp non contrassegna ogni risposta, e una risposta non contrassegnata non porta alcun ID. Consulta le risposte citate nell'hub per capire cosa la risoluzione può mancare e come correlare senza di essa.

Il payload del webhook

whatsapp.received porta lo stesso ramo nell'envelope dell'evento, quindi un endpoint può agire sul testo senza rileggere il messaggio:
Esempio di codice
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:04:11.118Z",
  "data": {
    "whatsapp_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
    "to": { "phone_number": "+13124495569" },
    "text": { "body": "Is my order out for delivery yet?" },
    "tags": null,
    "metadata": null
  }
}

Aspetti da tenere d'occhio

  • Un messaggio di testo è il modo più economico per un contatto di riaprire la finestra. Qualsiasi messaggio in entrata azzera la finestra di servizio a 24 ore, e un messaggio di testo è ciò che la maggior parte dei contatti invia; una risposta libera da parte tua è recapitabile da quel momento.
  • from può arrivare senza un numero di telefono. Un contatto che ha adottato un nome utente WhatsApp ti raggiunge tramite user ID con ambito business, quindi leggi l'identità da from anziché dare per scontato che from.phone_number sia impostato.
  • Il corpo è ciò che il contatto ha digitato. Un tap su qualcosa che hai inviato arriva invece come risposta interattiva su un ramo a sé.

Prossimi passi

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channelComprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builderEsplora la funzionalitàWhatsApp
Prova l'esercitazione e ottieni un brief di implementazione