Sign inGet started

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);
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

VeldGrensAfgedwongen door
contact_cards1 tot 5 kaarten per berichtBird, bij acceptatie (422)
nameverplicht; formatted_name plus één ander naamdeelBird, bij acceptatie (422)
formatted_name, first_name, middle_name, last_namemaximaal 256 tekensBird, bij acceptatie (422)
prefix, suffixmaximaal 64 tekensBird, bij acceptatie (422)
birthdayoptioneel, YYYY-MM-DD, en een datum die in de kalender bestaatBird, bij acceptatie (422)
phone_numbers, emails, urls, addressesmaximaal 10 items elkBird, bij acceptatie (422)
phone_numbermaximaal 32 tekensBird, bij acceptatie (422)
emailmaximaal 254 tekensBird, bij acceptatie (422)
urlmaximaal 2048 tekens, niet gevalideerd als URLBird, bij acceptatie (422)
type op telefoon, e-mail, website of adresmaximaal 64 tekens vrije tekstBird, bij acceptatie (422)
company, department, titlemaximaal 128 tekensBird, bij acceptatie (422)
street, city, state, zip, country, country_codemaximaal 128 tekensBird, 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