# Cartes de contact WhatsApp Un message de carte de contact partage un ou plusieurs contacts : un nom que le destinataire voit sur la carte, et une vue de profil qu'il ouvre depuis celle-ci contenant des numéros de téléphone, des e-mails, des sites web, des adresses, un employeur et une date de naissance. Utilisez-le pour transmettre à un client le numéro d'un collègue, d'un coursier ou le vôtre, au lieu de coller des chiffres dans un texte qu'il devra ensuite retaper. ## Envoyer une carte de contact `contact_cards` est un tableau. Chaque carte nécessite un `name`, et ce nom nécessite `formatted_name` plus au moins une autre partie : **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](/fr-fr/documentation/guides/whatsapp/message-types/contact-cards.ts.md) · [Python](/fr-fr/documentation/guides/whatsapp/message-types/contact-cards.py.md) · [Go](/fr-fr/documentation/guides/whatsapp/message-types/contact-cards.go.md) · [PHP](/fr-fr/documentation/guides/whatsapp/message-types/contact-cards.php.md) · [CLI](/fr-fr/documentation/guides/whatsapp/message-types/contact-cards.cli.md) · [cURL](/fr-fr/documentation/guides/whatsapp/message-types/contact-cards.curl.md) `from` est requis sur chaque message de service : un numéro que votre espace de travail possède, pas un numéro géré par Bird. La forme complète ajoute un employeur, une date de naissance et les autres tableaux de coordonnées : ```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" } ] } ] } ``` Chaque libellé `type`, sur un téléphone, un e-mail, un site web ou une adresse, est du texte libre que vous rédigez, envoyé exactement tel que vous l'avez écrit, et affiché à côté de la valeur dans la vue de profil du destinataire. WhatsApp ne définit aucun vocabulaire pour ces libellés, donc `Mobile`, `Landline`, `Pop-Up` et `Work (old)` sont tous également valides. ## Ce qui donne un bouton à une carte Un numéro de téléphone écrit en E.164, avec son indicatif pays et son `+` initial, donne à cette carte un bouton qui ouvre une conversation WhatsApp avec le numéro. Un numéro que Bird ne peut pas lire comme E.164 s'affiche quand même sur la carte, exactement tel que vous l'avez écrit ; il ne génère simplement aucun bouton. Cela inclut un numéro écrit sans son `+` initial. Bird n'en ajoutera pas pour vous : un numéro au format national d'un pays peut être interprété comme un numéro valide dans un autre pays une fois qu'un `+` y est ajouté, ce qui pointerait le bouton vers un inconnu. Renoncer à deviner coûte un bouton ; deviner faux coûte au destinataire une conversation avec la mauvaise personne. Une carte ne contenant aucun numéro de téléphone s'affiche sans bouton de conversation et ne peut qu'être enregistrée dans un carnet d'adresses. ## Limites | Champ | Limite | Appliquée par | | ----------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------- | | `contact_cards` | 1 à 5 cartes par message | Bird, à l'acceptation (`422`) | | `name` | requis ; `formatted_name` plus une autre partie du nom | Bird, à l'acceptation (`422`) | | `formatted_name`, `first_name`, `middle_name`, `last_name` | jusqu'à 256 caractères | Bird, à l'acceptation (`422`) | | `prefix`, `suffix` | jusqu'à 64 caractères | Bird, à l'acceptation (`422`) | | `birthday` | optionnel, `YYYY-MM-DD`, et une date que le calendrier reconnaît | Bird, à l'acceptation (`422`) | | `phone_numbers`, `emails`, `urls`, `addresses` | jusqu'à 10 entrées chacun | Bird, à l'acceptation (`422`) | | `phone_number` | jusqu'à 32 caractères | Bird, à l'acceptation (`422`) | | `email` | jusqu'à 254 caractères | Bird, à l'acceptation (`422`) | | `url` | jusqu'à 2 048 caractères, non validé comme URL | Bird, à l'acceptation (`422`) | | `type` sur tout téléphone, e-mail, site web ou adresse | jusqu'à 64 caractères de texte libre | Bird, à l'acceptation (`422`) | | `company`, `department`, `title` | jusqu'à 128 caractères | Bird, à l'acceptation (`422`) | | `street`, `city`, `state`, `zip`, `country`, `country_code` | jusqu'à 128 caractères | Bird, à l'acceptation (`422`) | **Le plafond de cinq cartes vient de Bird, et il est volontairement bien en dessous de ce que WhatsApp accepte.** La description API publiée par WhatsApp déclare cinq, sa documentation recommande moins pour des raisons d'utilisabilité et de retours négatifs, et un message qui s'ouvre comme "Contact 1 and 256 other contacts" est un vecteur de spam avant d'être une fonctionnalité. Relever le plafond plus tard serait un changement additif, donc demandez si cinq est insuffisant pour ce que vous construisez. Chaque limite de longueur ci-dessus vient aussi de Bird. WhatsApp n'en impose aucune digne de ce nom et son client ne compense pas : un `type` de 500 caractères s'affiche sur dix lignes d'une seule lettre répétée, et un `url` de 4 000 caractères est supprimé silencieusement, laissant la vue de profil vide. Une `422` nommant le champ fautif vaut mieux qu'une carte que le destinataire ne peut pas lire. ## Deux règles que le schéma ne peut pas exprimer **Un nom nécessite une deuxième partie.** `formatted_name` seul est refusé avec une `422` [`E15061`](/docs/api/errors/E15061) `WhatsAppContactNameIncomplete`, nommant `contact_cards..name`. N'importe lequel parmi `prefix`, `first_name`, `middle_name`, `last_name` ou `suffix` suffit, mais une valeur vide ou composée uniquement d'espaces ne compte pas, et un `org` ne le rattrape pas. C'est une exigence propre à WhatsApp, non documentée dans sa référence ; Bird l'intercepte à l'acceptation pour que vous obteniez une erreur exploitable au lieu d'un échec asynchrone. **Une date de naissance doit être une date réelle.** `birthday` est `YYYY-MM-DD` ; toute autre forme, et toute date que le calendrier ne reconnaît pas, comme `2026-02-30`, est refusée avec une `422` [`E15062`](/docs/api/errors/E15062) `WhatsAppContactBirthdayInvalid`. WhatsApp lui-même accepte `2026-02-30` et l'affiche au destinataire, ce qui ressemble à un bug dans vos données. ## Relire une carte Une carte que vous avez envoyée se relit sur le même champ `contact_cards` qu'utilise une carte entrante, via la liste de messages ou `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` et `vcard` sont absents sur une carte que vous avez envoyée : WhatsApp les définit tous deux sur une carte partagée par un contact. Un libellé `type` que vous avez envoyé se relit exactement tel qu'écrit, tandis qu'un libellé sur une carte reçue est mis en minuscules. Consultez [Recevoir des cartes de contact WhatsApp](/docs/guides/whatsapp/receiving-whatsapp/contact-cards) pour le côté entrant. ## Cas particuliers - **La fenêtre de service client doit être ouverte.** L'envoi d'une carte de contact est un message de service, livrable uniquement dans une fenêtre ouverte ; consultez la [fenêtre de service client](/docs/guides/whatsapp/message-types#the-customer-service-window) du hub. - **Il n'y a pas de `wa_id` à envoyer.** WhatsApp identifie le contact d'une carte par un identifiant de compte ; Bird le dérive de chaque `phone_number` E.164 au lieu d'en accepter un, de sorte que le bouton d'une carte ne peut jamais pointer ailleurs que sur les chiffres qui y sont imprimés. - **`vcard` est en lecture seule.** WhatsApp le génère pour une carte partagée par un contact. Il n'existe aucun moyen d'envoyer une carte sous forme de texte vCard brut. - **Une carte n'est pas un enregistrement de contact.** En envoyer une partage des coordonnées dans un message ; cela ne crée rien dans votre espace de travail, et l'enregistrement par le destinataire est sa propre action, invisible pour vous. ## Étapes suivantes - [Messages de service WhatsApp](/docs/guides/whatsapp/message-types) : la fenêtre de service client et le modèle partagé par tous les messages de service - [Demandes de coordonnées](/docs/guides/whatsapp/message-types/interactive/contact-info-requests) : demander son numéro à un contact au lieu d'en envoyer un - [Recevoir des messages WhatsApp](/docs/guides/whatsapp/receiving-whatsapp) : messages entrants, médias et le webhook `whatsapp.received` - [Envoyer des messages WhatsApp](/docs/guides/whatsapp/sending-whatsapp) : l'enveloppe de requête, le modèle `202` et les réessais sûrs ## 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)