Ricevere schede contatto WhatsApp

contact_cards è l'unico canale che trasporta lo stesso campo in entrambe le direzioni. Un contatto può condividere una scheda dalla propria rubrica, e un tocco su una richiesta di informazioni di contatto che hai inviato arriva qui allo stesso modo, con il numero che ha scelto di comunicare.

Cosa contiene una scheda contatto in ingresso

contact_cards è sempre un array e origin indica come è arrivata la scheda:

Esempio di codice

{
  "id": "wam_01kyg9v3timy1w7n0r4cbh9ukf",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "contact_cards": [
    {
      "origin": "contact_request",
      "phone_numbers": [{ "phone_number": "+14155550100", "type": "cell" }]
    }
  ],
  "created_at": "2026-08-25T09:27:45Z"
}

origin	Come è arrivata la scheda
contact_request	Il contatto ha toccato un pulsante che hai inviato per chiedere il suo numero
other	Il contatto ha condiviso una scheda nella chat, spontaneamente

Controlla origin prima di trattare una scheda come risposta alla tua richiesta. È l'unico segnale che distingue i due casi, e una scheda condivisa spontaneamente può indicare interamente un terzo soggetto anziché il contatto. La lista dei valori è aperta, quindi tratta un valore che non riconosci come un'altra modalità di condivisione aggiunta successivamente.

Una scheda inviata da questo spazio di lavoro viene restituita senza alcun origin, ed è così che una scheda in uscita si distingue da una in ingresso sullo stesso campo.

Cosa contiene un tocco e cosa contiene una scheda condivisa

I due casi arrivano con quantità di dettaglio diverse, e nessun campo della scheda è obbligatorio: WhatsApp invia le parti presenti nella scheda e omette il resto, quindi una scheda con solo un origin arriva comunque anziché essere scartata.

Campo	Su un tocco del pulsante	Su una scheda condivisa nella chat
phone_numbers[].phone_number, type	Il numero che il contatto ha scelto di comunicare	I numeri presenti nella scheda
vcard	Omesso; un tocco contiene solo il numero	La scheda in formato vCard
name, org, birthday, emails, urls, addresses	Ciò che WhatsApp invia, di solito nulla	Presenti quando la scheda li contiene

Esempio di codice

{
  "contact_cards": [
    {
      "origin": "other",
      "vcard": "BEGIN:VCARD\nVERSION:3.0\nN:Johnson;Barbara;;;\nTEL;type=CELL:+16505551234\nEND:VCARD\n",
      "name": {
        "formatted_name": "Barbara J. Johnson",
        "first_name": "Barbara",
        "last_name": "Johnson"
      },
      "org": { "company": "Northside Plumbing" },
      "phone_numbers": [{ "phone_number": "+16505551234", "type": "cell" }]
    }
  ]
}

Due campi richiedono attenzione durante il parsing. phone_number è normalizzato in E.164 dove è possibile analizzarlo, e passato esattamente come il dispositivo del contatto lo ha memorizzato dove non è possibile (un interno fra questi), quindi analizzalo in modo difensivo anziché dare per scontato E.164. birthday arriva dal dispositivo senza validazione ed è passato come testo in formato YYYY-MM-DD anziché tipizzato come data, quindi non dare per scontato che sia analizzabile. Un'etichetta type su una scheda ricevuta è in minuscolo, e WhatsApp non definisce un vocabolario per essa, quindi confrontala senza distinzione tra maiuscole e minuscole anziché fare switch su CELL.

Il numero di telefono comunicato da un contatto

Un contatto che ha adottato un nome utente WhatsApp ti raggiunge tramite user ID con scope business senza numero di telefono su from. Una richiesta di informazioni di contatto è il modo per chiedere il numero, e questo canale è dove arriva la risposta, con origin: "contact_request" e il numero in phone_numbers.

Il numero comunicato non è garantito essere il numero da cui il contatto chatta: Meta avverte che l'identificativo di un utente e il numero di telefono potrebbero non corrispondere sempre, quindi memorizza il numero comunicato come dato a sé anziché sovrascrivere l'identità su from.

Il payload del webhook

whatsapp.received contiene l'array contact_cards nell'envelope dell'evento:

Esempio di codice

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:27:45.019Z",
  "data": {
    "whatsapp_id": "wam_01kyg9v3timy1w7n0r4cbh9ukf",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100", "bsuid": "US.13491208655302741918" },
    "to": { "phone_number": "+13124495569" },
    "contact_cards": [
      {
        "origin": "contact_request",
        "phone_numbers": [{ "phone_number": "+14155550100", "type": "cell" }]
      }
    ],
    "tags": null,
    "metadata": null
  }
}

Aspetti da tenere d'occhio

Una richiesta rifiutata non produce nulla. WhatsApp mostra al contatto un foglio di condivisione, e chiuderlo non invia alcun messaggio né attiva alcun webhook, quindi un flusso in attesa di un numero ha bisogno di un proprio timeout anziché di un evento di rifiuto da monitorare.
Due richieste in sospeso sono indistinguibili. Una scheda che risponde a una richiesta di informazioni di contatto non contiene alcun in_reply_to_message_id, quindi una seconda richiesta inviata prima che la prima abbia ricevuto risposta non può essere associata alla propria risposta.
L'array può contenere più schede. Un contatto che condivide più schede in un unico messaggio riempie più voci, ciascuna con il proprio origin.
Una scheda è un dato di contatto che non hai raccolto tu. Può contenere nome, numeri e data di nascita di un terzo soggetto, quindi applica le stesse regole di conservazione e consenso che applicheresti a qualsiasi altro dato personale prima di memorizzarla.

Passi successivi

Come funziona la ricezione: l'envelope in ingresso, il recupero dei media e il webhook whatsapp.received
Schede contatto WhatsApp: il lato invio dello stesso canale
User ID con scope business: perché un contatto arriva senza numero di telefono e come la richiesta si inserisce nella conversazione
Richieste di informazioni di contatto WhatsApp: il pulsante che chiede un numero

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 channel Comprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builder Esplora la funzionalitàWhatsApp

Prova l'esercitazione e ottieni un brief di implementazione