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:
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);msg = client.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"}],
}
],
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
ContactCards: []bird.WhatsAppContactCardSend{{
Name: bird.WhatsAppContactNameSend{
FormattedName: "Barbara J. Johnson",
FirstName: bird.String("Barbara"),
LastName: bird.String("Johnson"),
},
PhoneNumbers: &[]bird.WhatsAppContactPhoneSend{{
PhoneNumber: "+16505559999",
Type: bird.String("Mobile"),
}},
}},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$name = (new WhatsAppContactCardSendName())
->setFormattedName('Barbara J. Johnson')
->setFirstName('Barbara')
->setLastName('Johnson');
$phone = (new WhatsAppContactPhoneSend())
->setPhoneNumber('+16505559999')
->setType('Mobile');
$card = (new WhatsAppContactCardSend())
->setName($name)
->setPhoneNumbers([$phone]);
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
contactCards: [$card],
);
echo $message->getId(), ' ', $message->getStatus();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"}]}]'curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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" }
]
}
]
}'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:
Codevoorbeeld
{
"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) |
| 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 WhatsAppContactNameIncomplete, die contact_cards.<n>.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 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}:
Codevoorbeeld
{
"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 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 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: het klantenservicevenster en het model dat elk servicebericht deelt
- Contactgegevensverzoeken: vraag een contact om hun nummer in plaats van er een te versturen
- WhatsApp-berichten ontvangen: inkomende berichten, media en de whatsapp.received-webhook
- WhatsApp-berichten versturen: de request-envelope, het 202-model en veilig opnieuw proberen
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Bekijk de gidsConnecting WhatsApp to Bird: from buying a number to a live channelBegrijp het conceptWhat is the 24-hour customer service window on WhatsApp?Gebruik de toolWhatsApp message builderOntdek de mogelijkheidWhatsApp
Probeer de oefening en ontvang een implementatieoverzicht