# WhatsApp-contactkaarten Een contactkaartbericht deelt een of meer contacten: een naam die de ontvanger op de kaart ziet, en een profielweergave die ze vandaaruit openen met telefoonnummers, e-mailadressen, websites, adressen, een werkgever en een geboortedatum. Gebruik het om een klant het nummer van een collega, een koerier of jezelf te geven, in plaats van cijfers in tekst te plakken die ze dan opnieuw moeten intypen. ## Een contactkaart versturen `contact_cards` is een array. Elke kaart heeft een `name` nodig, en die naam vereist `formatted_name` plus minstens één ander onderdeel: **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](/nl-nl/documentatie/guides/whatsapp/message-types/contact-cards.ts.md) · [Python](/nl-nl/documentatie/guides/whatsapp/message-types/contact-cards.py.md) · [Go](/nl-nl/documentatie/guides/whatsapp/message-types/contact-cards.go.md) · [PHP](/nl-nl/documentatie/guides/whatsapp/message-types/contact-cards.php.md) · [CLI](/nl-nl/documentatie/guides/whatsapp/message-types/contact-cards.cli.md) · [cURL](/nl-nl/documentatie/guides/whatsapp/message-types/contact-cards.curl.md) `from` is verplicht bij elk servicebericht: een nummer dat je werkruimte bezit, geen door Bird beheerd nummer. De volledige structuur voegt een werkgever, een geboortedatum en de overige contactdetail-arrays toe: ```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" } ] } ] } ``` Elk `type`-label, op een telefoon, e-mail, website of adres, is vrije tekst die je zelf schrijft, exact zo verstuurd als je het schreef, en naast de waarde getoond in de profielweergave van de ontvanger. WhatsApp definieert hiervoor geen woordenschat, dus `Mobile`, `Landline`, `Pop-Up` en `Work (old)` zijn allemaal even geldig. ## Wanneer krijgt een kaart een knop Een telefoonnummer in E.164-formaat, met landcode en voorloopteken `+`, levert die kaart een knop op die een WhatsApp-chat met het nummer opent. Een nummer dat Bird niet als E.164 kan lezen, verschijnt nog steeds op de kaart precies zoals je het schreef; het levert alleen geen knop op. Dat geldt ook voor een nummer zonder voorloopteken `+`. Bird voegt er niet zelf een toe: een nummer in nationaal formaat uit het ene land kan als geldig nummer in een ander land worden gelezen zodra er een `+` aan wordt geplakt, waardoor de knop naar een onbekende wijst. Niet raden kost een knop; fout raden kost de ontvanger een chat met de verkeerde persoon. Een kaart zonder telefoonnummer verschijnt zonder chatknop en kan alleen worden opgeslagen in een adresboek. ## Limieten | Veld | Grens | Afgedwongen door | | ----------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------- | | `contact_cards` | 1 tot 5 kaarten per bericht | Bird, bij acceptatie (`422`) | | `name` | verplicht; `formatted_name` plus één ander naamdeel | Bird, bij acceptatie (`422`) | | `formatted_name`, `first_name`, `middle_name`, `last_name` | maximaal 256 tekens | Bird, bij acceptatie (`422`) | | `prefix`, `suffix` | maximaal 64 tekens | Bird, bij acceptatie (`422`) | | `birthday` | optioneel, `YYYY-MM-DD`, en een datum die in de kalender bestaat | Bird, bij acceptatie (`422`) | | `phone_numbers`, `emails`, `urls`, `addresses` | maximaal 10 items elk | Bird, bij acceptatie (`422`) | | `phone_number` | maximaal 32 tekens | Bird, bij acceptatie (`422`) | | `email` | maximaal 254 tekens | Bird, bij acceptatie (`422`) | | `url` | maximaal 2048 tekens, niet gevalideerd als URL | Bird, bij acceptatie (`422`) | | `type` op telefoon, e-mail, website of adres | maximaal 64 tekens vrije tekst | Bird, bij acceptatie (`422`) | | `company`, `department`, `title` | maximaal 128 tekens | Bird, bij acceptatie (`422`) | | `street`, `city`, `state`, `zip`, `country`, `country_code` | maximaal 128 tekens | Bird, bij acceptatie (`422`) | **De limiet van vijf kaarten is van Bird, en ligt bewust ver onder wat WhatsApp accepteert.** De eigen gepubliceerde API-beschrijving van WhatsApp stelt vijf, de bijbehorende tekst raadt er minder aan vanwege bruikbaarheid en negatieve feedback, en een bericht dat opent als "Contact 1 and 256 other contacts" is eerder een spamvector dan een feature. De limiet later verhogen zou een additieve wijziging zijn, dus vraag het als vijf te weinig is voor wat je bouwt. Elke lengtelimiet hierboven is ook van Bird. WhatsApp dwingt geen noemenswaardige limiet af en de client compenseert niet: een `type` van 500 tekens wordt weergegeven als tien regels van één herhaalde letter, en een `url` van 4000 tekens wordt stilletjes weggelaten, waardoor de profielweergave leeg blijft. Een `422` die het problematische veld benoemt, is beter dan een kaart die de ontvanger niet kan lezen. ## Twee regels die het schema niet kan uitdrukken **Een naam heeft een tweede deel nodig.** `formatted_name` alleen wordt geweigerd met een `422` [`E15061`](/docs/api/errors/E15061) `WhatsAppContactNameIncomplete`, die `contact_cards..name` benoemt. Elk van `prefix`, `first_name`, `middle_name`, `last_name` of `suffix` voldoet, maar een lege of alleen-uit-spaties-bestaande waarde telt niet mee, en een `org` helpt niet. Dit is een eigen vereiste van WhatsApp, nergens gedocumenteerd in de referentie; Bird vangt het bij acceptatie af zodat je een bruikbare fout krijgt in plaats van een asynchroon probleem. **Een geboortedatum moet een echte datum zijn.** `birthday` is `YYYY-MM-DD`; elke andere vorm, en elke datum die niet in de kalender bestaat, zoals `2026-02-30`, wordt geweigerd met een `422` [`E15062`](/docs/api/errors/E15062) `WhatsAppContactBirthdayInvalid`. WhatsApp zelf accepteert `2026-02-30` en toont het aan de ontvanger, wat eruitziet als een bug in je data. ## Een kaart teruglezen Een kaart die je verstuurde, lees je terug via hetzelfde `contact_cards`-veld dat een inkomende kaart gebruikt, via de berichtenlijst of `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` en `vcard` ontbreken op een kaart die je verstuurde: WhatsApp stelt beide in op een kaart die een contact deelde. Een `type`-label dat je verstuurde wordt exact zo teruggelezen als geschreven, terwijl een label op een ontvangen kaart in kleine letters staat. Zie [WhatsApp-contactkaarten ontvangen](/docs/guides/whatsapp/receiving-whatsapp/contact-cards) voor de inkomende kant. ## Randgevallen - **Het klantenservicevenster moet open zijn.** Het versturen van een contactkaart is een servicebericht, alleen bezorgbaar binnen een open venster; zie het [klantenservicevenster](/docs/guides/whatsapp/message-types#the-customer-service-window) van de hub. - **Er is geen `wa_id` om te versturen.** WhatsApp identificeert het contact van een kaart aan de hand van een account-ID; Bird leidt dat af uit elke E.164 `phone_number` in plaats van er een te accepteren, zodat de knop op een kaart nooit ergens anders naartoe kan wijzen dan de cijfers die erop staan. - **`vcard` is alleen-lezen.** WhatsApp genereert het voor een kaart die een contact deelde. Er is geen manier om een kaart als ruwe vCard-tekst te versturen. - **Een kaart is geen contactrecord.** Er een versturen deelt gegevens in een bericht; het maakt niets aan in je werkruimte, en als de ontvanger het opslaat is dat hun eigen actie, onzichtbaar voor jou. ## Volgende stappen - [WhatsApp-serviceberichten](/docs/guides/whatsapp/message-types): het klantenservicevenster en het model dat elk servicebericht deelt - [Contactgegevensverzoeken](/docs/guides/whatsapp/message-types/interactive/contact-info-requests): vraag een contact om hun nummer in plaats van er een te versturen - [WhatsApp-berichten ontvangen](/docs/guides/whatsapp/receiving-whatsapp): inkomende berichten, media en de `whatsapp.received`-webhook - [WhatsApp-berichten versturen](/docs/guides/whatsapp/sending-whatsapp): de request-envelope, het `202`-model en veilig opnieuw proberen ## 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)