# Schede contatto WhatsApp Un messaggio con scheda contatto condivide uno o più contatti: un nome che il destinatario vede sulla scheda e una vista profilo che può aprire, contenente numeri di telefono, email, siti web, indirizzi, un datore di lavoro e una data di nascita. Usalo per consegnare a un cliente il numero di un collega, di un corriere o il tuo, anziché incollare cifre in un testo che poi dovrà ricopiare. ## Inviare una scheda contatto `contact_cards` è un array. Ogni scheda richiede un `name`, e quel nome richiede `formatted_name` più almeno un'altra parte: **TypeScript** ```typescript const msg = await bird.whatsapp.send({ to: "+16505551234", from: "+13124495648", contact_cards: [ { name: { formatted_name: "Barbara J. Johnson", first_name: "Barbara", last_name: "Johnson", }, phone_numbers: [{ phone_number: "+16505559999", type: "Mobile" }], }, ], }); console.log(msg.id, msg.status); ``` Examples: [TypeScript](/it-it/documentazione/guides/whatsapp/message-types/contact-cards.ts.md) · [Python](/it-it/documentazione/guides/whatsapp/message-types/contact-cards.py.md) · [Go](/it-it/documentazione/guides/whatsapp/message-types/contact-cards.go.md) · [PHP](/it-it/documentazione/guides/whatsapp/message-types/contact-cards.php.md) · [CLI](/it-it/documentazione/guides/whatsapp/message-types/contact-cards.cli.md) · [cURL](/it-it/documentazione/guides/whatsapp/message-types/contact-cards.curl.md) `from` è obbligatorio su ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird. La struttura completa aggiunge un datore di lavoro, una data di nascita e gli altri array di dettagli contatto: ```json { "to": "+16505551234", "from": "+13124495648", "contact_cards": [ { "name": { "formatted_name": "Dr. Barbara J. Johnson Esq.", "prefix": "Dr.", "first_name": "Barbara", "middle_name": "Joana", "last_name": "Johnson", "suffix": "Esq." }, "org": { "company": "Lucky Shrub", "department": "Legal", "title": "Lead Counsel" }, "birthday": "1999-01-23", "phone_numbers": [ { "phone_number": "+16505559999", "type": "Landline" }, { "phone_number": "+19175559999", "type": "Mobile" } ], "emails": [{ "email": "bjohnson@example.com", "type": "Work" }], "urls": [{ "url": "https://example.com", "type": "Company" }], "addresses": [ { "street": "1 Lucky Shrub Way", "city": "Menlo Park", "state": "CA", "zip": "94025", "country": "United States", "country_code": "US", "type": "Office" } ] } ] } ``` Ogni etichetta `type`, su un telefono, un'email, un sito web o un indirizzo, è testo libero che scrivi tu, inviato esattamente come lo hai scritto e mostrato accanto al valore nella vista profilo del destinatario. WhatsApp non definisce un vocabolario per queste etichette, quindi `Mobile`, `Landline`, `Pop-Up` e `Work (old)` sono tutti ugualmente validi. ## Cosa fa ottenere un pulsante a una scheda Un numero di telefono scritto in E.164, con il prefisso internazionale e il `+` iniziale, fa ottenere alla scheda un pulsante che apre una chat WhatsApp con quel numero. Un numero che Bird non riesce a leggere come E.164 viene comunque mostrato sulla scheda, esattamente come lo hai scritto; semplicemente non ottiene alcun pulsante. Questo include un numero scritto senza il `+` iniziale. Bird non ne aggiungerà uno per te: un numero in formato nazionale di un Paese può risultare valido in un altro una volta aggiunto un `+`, e il pulsante punterebbe a uno sconosciuto. Rinunciare a indovinare costa un pulsante; indovinare sbagliato costa al destinatario una chat con la persona sbagliata. Una scheda priva di qualsiasi numero di telefono viene mostrata senza pulsante chat e può solo essere salvata in rubrica. ## Limiti | Campo | Vincolo | Imposto da | | ----------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------ | | `contact_cards` | Da 1 a 5 schede per messaggio | Bird, all'accettazione (`422`) | | `name` | obbligatorio; `formatted_name` più un'altra parte del nome | Bird, all'accettazione (`422`) | | `formatted_name`, `first_name`, `middle_name`, `last_name` | fino a 256 caratteri | Bird, all'accettazione (`422`) | | `prefix`, `suffix` | fino a 64 caratteri | Bird, all'accettazione (`422`) | | `birthday` | facoltativo, `YYYY-MM-DD`, e una data presente nel calendario | Bird, all'accettazione (`422`) | | `phone_numbers`, `emails`, `urls`, `addresses` | fino a 10 voci ciascuno | Bird, all'accettazione (`422`) | | `phone_number` | fino a 32 caratteri | Bird, all'accettazione (`422`) | | `email` | fino a 254 caratteri | Bird, all'accettazione (`422`) | | `url` | fino a 2048 caratteri, non validato come URL | Bird, all'accettazione (`422`) | | `type` su qualsiasi telefono, email, sito web o indirizzo | fino a 64 caratteri di testo libero | Bird, all'accettazione (`422`) | | `company`, `department`, `title` | fino a 128 caratteri | Bird, all'accettazione (`422`) | | `street`, `city`, `state`, `zip`, `country`, `country_code` | fino a 128 caratteri | Bird, all'accettazione (`422`) | **Il limite di cinque schede è di Bird, ed è deliberatamente molto inferiore a quanto WhatsApp accetta.** La descrizione API pubblicata da WhatsApp dichiara cinque, la sua documentazione ne raccomanda meno per motivi di usabilità e feedback negativo, e un messaggio che si apre come "Contact 1 and 256 other contacts" è un vettore di spam prima ancora di essere una funzionalità. Alzare il limite in futuro sarebbe un cambiamento additivo, quindi chiedi se cinque è insufficiente per ciò che stai costruendo. Anche ogni limite di lunghezza sopra indicato è di Bird. WhatsApp non ne impone alcuno degno di nota e il suo client non compensa: un `type` di 500 caratteri viene mostrato come dieci righe di una sola lettera ripetuta, e un `url` di 4000 caratteri viene scartato silenziosamente, lasciando la vista profilo vuota. Un `422` che indica il campo problematico è meglio di una scheda illeggibile per il destinatario. ## Due regole che lo schema non può esprimere **Un nome richiede una seconda parte.** Il solo `formatted_name` viene rifiutato con un `422` [`E15061`](/docs/api/errors/E15061) `WhatsAppContactNameIncomplete`, che indica `contact_cards..name`. Uno qualsiasi tra `prefix`, `first_name`, `middle_name`, `last_name` o `suffix` lo soddisfa, ma un valore vuoto o composto solo da spazi non conta, e un `org` non lo salva. Questo è un requisito di WhatsApp, non documentato da nessuna parte nel suo riferimento; Bird lo intercetta all'accettazione, così ottieni un errore utilizzabile anziché un fallimento asincrono. **La data di nascita deve essere una data reale.** `birthday` è `YYYY-MM-DD`; qualsiasi altro formato, e qualsiasi data che il calendario non contiene, come `2026-02-30`, viene rifiutato con un `422` [`E15062`](/docs/api/errors/E15062) `WhatsAppContactBirthdayInvalid`. WhatsApp stesso accetta `2026-02-30` e lo mostra al destinatario, il che sembra un bug nei tuoi dati. ## Rileggere una scheda Una scheda che hai inviato viene riletta sullo stesso campo `contact_cards` usato da una scheda in entrata, tramite la lista messaggi o `GET /v1/whatsapp/messages/{id}`: ```json { "id": "wam_01kyb2m4xq7whs0d8n3prv6tez", "direction": "outbound", "status": "delivered", "contact_cards": [ { "name": { "formatted_name": "Barbara J. Johnson", "first_name": "Barbara" }, "phone_numbers": [{ "phone_number": "+16505559999", "type": "Mobile" }] } ] } ``` `origin` e `vcard` sono assenti su una scheda che hai inviato: WhatsApp li imposta entrambi su una scheda condivisa da un contatto. Un'etichetta `type` che hai inviato viene riletta esattamente come scritta, mentre un'etichetta su una scheda ricevuta viene convertita in minuscolo. Vedi [Ricevere schede contatto WhatsApp](/docs/guides/whatsapp/receiving-whatsapp/contact-cards) per il lato in entrata. ## Casi limite - **La finestra del servizio clienti deve essere aperta.** L'invio di una scheda contatto è un messaggio di servizio, recapitabile solo all'interno di una finestra aperta; vedi la [finestra del servizio clienti](/docs/guides/whatsapp/message-types#the-customer-service-window) dell'hub. - **Non esiste un `wa_id` da inviare.** WhatsApp identifica il contatto di una scheda tramite un account ID; Bird lo ricava da ogni `phone_number` E.164 anziché accettarne uno, quindi il pulsante su una scheda non può mai puntare a qualcosa di diverso dalle cifre stampate su di essa. - **`vcard` è in sola lettura.** WhatsApp lo genera per una scheda condivisa da un contatto. Non c'è modo di inviare una scheda come testo vCard grezzo. - **Una scheda non è un record contatto.** Inviarne una condivide dei dettagli in un messaggio; non crea nulla nel tuo spazio di lavoro, e il salvataggio da parte del destinatario è una sua azione, invisibile per te. ## Prossimi passi - [Messaggi di servizio WhatsApp](/docs/guides/whatsapp/message-types): la finestra del servizio clienti e il modello condiviso da ogni messaggio di servizio - [Richieste di informazioni di contatto](/docs/guides/whatsapp/message-types/interactive/contact-info-requests): chiedi a un contatto il suo numero anziché inviarne uno - [Ricevere messaggi WhatsApp](/docs/guides/whatsapp/receiving-whatsapp): messaggi in entrata, media e il webhook `whatsapp.received` - [Inviare messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp): la struttura della richiesta, il modello `202` e i tentativi sicuri ## Related resources - [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video) - [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer) - [WhatsApp message builder](/tools/whatsapp-message-builder) (tool) - [WhatsApp](/products/whatsapp) (product) [Get an implementation brief](/learn/workspace?topic=whatsapp)