Sign inGet started

WhatsApp-Kontaktkarten

Eine Kontaktkarten-Nachricht teilt einen oder mehrere Kontakte: einen Namen, den der Empfänger auf der Karte sieht, und eine Profilansicht, die er darüber öffnet – mit Telefonnummern, E-Mail-Adressen, Websites, Adressen, einem Arbeitgeber und einem Geburtstag. Nutzen Sie sie, um einem Kunden die Nummer eines Kollegen, eines Kuriers oder Ihre eigene zu übermitteln, statt Ziffern in Text zu kopieren, den er dann erneut eintippen muss.

Eine Kontaktkarte senden

contact_cards ist ein Array. Jede Karte braucht einen name, und dieser Name braucht formatted_name plus mindestens einen weiteren Teil:
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 ist bei jeder Service-Nachricht erforderlich: eine Nummer, die Ihr Workspace besitzt, keine von Bird verwaltete.
Die vollständige Struktur ergänzt einen Arbeitgeber, einen Geburtstag und die weiteren Kontaktdetail-Arrays:
Codebeispiel
{
  "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"
        }
      ]
    }
  ]
}
Jedes type-Label – bei Telefon, E-Mail, Website oder Adresse gleichermaßen – ist Freitext, den Sie selbst schreiben. Er wird exakt so gesendet, wie Sie ihn geschrieben haben, und neben dem Wert in der Profilansicht des Empfängers angezeigt. WhatsApp definiert kein Vokabular dafür, also sind Mobile, Landline, Pop-Up und Work (old) alle gleichermaßen gültig.

Was einer Karte einen Button verschafft

Eine Telefonnummer im E.164-Format, mit Ländervorwahl und führendem +, verschafft der Karte einen Button, der einen WhatsApp-Chat mit dieser Nummer öffnet. Eine Nummer, die Bird nicht als E.164 lesen kann, wird trotzdem auf der Karte dargestellt, genau wie Sie sie geschrieben haben – sie bekommt nur keinen Button.
Das betrifft auch eine Nummer ohne führendes +. Bird ergänzt keins für Sie: Eine Nummer im nationalen Format aus einem Land kann als gültige Nummer in einem anderen Land geparst werden, sobald eine + angehängt wird, und der Button würde dann auf eine fremde Person zeigen. Nicht zu raten kostet einen Button; falsch zu raten kostet den Empfänger einen Chat mit der falschen Person.
Eine Karte ganz ohne Telefonnummer wird ohne Chat-Button dargestellt und kann nur in einem Adressbuch gespeichert werden.

Limits

FeldGrenzwertDurchgesetzt von
contact_cards1 bis 5 Karten pro NachrichtBird, bei Annahme (422)
nameerforderlich; formatted_name plus ein weiterer NamensteilBird, bei Annahme (422)
formatted_name, first_name, middle_name, last_namebis zu 256 ZeichenBird, bei Annahme (422)
prefix, suffixbis zu 64 ZeichenBird, bei Annahme (422)
birthdayoptional, YYYY-MM-DD, und ein Datum, das der Kalender enthältBird, bei Annahme (422)
phone_numbers, emails, urls, addressesjeweils bis zu 10 EinträgeBird, bei Annahme (422)
phone_numberbis zu 32 ZeichenBird, bei Annahme (422)
emailbis zu 254 ZeichenBird, bei Annahme (422)
urlbis zu 2048 Zeichen, nicht als URL validiertBird, bei Annahme (422)
type bei Telefon, E-Mail, Website oder Adressebis zu 64 Zeichen FreitextBird, bei Annahme (422)
company, department, titlebis zu 128 ZeichenBird, bei Annahme (422)
street, city, state, zip, country, country_codebis zu 128 ZeichenBird, bei Annahme (422)
Das Fünf-Karten-Limit stammt von Bird und liegt bewusst weit unter dem, was WhatsApp akzeptiert. Die eigene veröffentlichte API-Beschreibung von WhatsApp gibt fünf an, der Fließtext empfiehlt weniger aus Usability- und Negativfeedback-Gründen, und eine Nachricht, die als "Contact 1 and 256 other contacts" aufgeht, ist eher ein Spam-Vektor als ein Feature. Das Limit später zu erhöhen wäre eine additive Änderung – fragen Sie nach, wenn fünf für Ihren Anwendungsfall zu wenig sind.
Alle oben genannten Längenlimits stammen ebenfalls von Bird. WhatsApp setzt keine nennenswerten Grenzen durch, und sein Client kompensiert das nicht: Ein type mit 500 Zeichen wird als zehn Zeilen eines wiederholten Buchstabens dargestellt, und ein url mit 4000 Zeichen wird stillschweigend verworfen, sodass die Profilansicht leer bleibt. Ein 422, der das fehlerhafte Feld benennt, ist besser als eine Karte, die der Empfänger nicht lesen kann.

Zwei Regeln, die das Schema nicht ausdrücken kann

Ein Name braucht einen zweiten Teil. formatted_name allein wird mit einem 422 E15061 WhatsAppContactNameIncomplete abgelehnt, der contact_cards.<n>.name benennt. Jeder einzelne von prefix, first_name, middle_name, last_name oder suffix erfüllt die Anforderung, aber ein leerer oder nur aus Leerzeichen bestehender Wert zählt nicht, und ein org rettet ihn nicht. Das ist eine eigene Anforderung von WhatsApp, die nirgends in seiner Referenz dokumentiert ist; Bird fängt sie bei der Annahme ab, sodass Sie einen verwertbaren Fehler statt eines asynchronen Fehlschlags erhalten.
Ein Geburtstag muss ein echtes Datum sein. birthday ist YYYY-MM-DD; jede andere Form und jedes Datum, das der Kalender nicht enthält, wie 2026-02-30, wird mit einem 422 E15062 WhatsAppContactBirthdayInvalid abgelehnt. WhatsApp selbst akzeptiert 2026-02-30 und zeigt es dem Empfänger an, was wie ein Fehler in Ihren Daten aussieht.

Eine Karte zurücklesen

Eine gesendete Karte wird über dasselbe contact_cards-Feld zurückgelesen, das auch eine eingehende Karte nutzt, über die Nachrichtenliste oder GET /v1/whatsapp/messages/{id}:
Codebeispiel
{
  "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 und vcard fehlen bei einer von Ihnen gesendeten Karte: WhatsApp setzt beides bei einer Karte, die ein Kontakt geteilt hat. Ein von Ihnen gesendetes type-Label wird exakt wie geschrieben zurückgegeben, während ein Label auf einer empfangenen Karte in Kleinbuchstaben umgewandelt wird. Siehe WhatsApp-Kontaktkarten empfangen für die eingehende Seite.

Sonderfälle

  • Das Kundenservice-Fenster muss offen sein. Das Senden einer Kontaktkarte ist eine Service-Nachricht, die nur innerhalb eines offenen Fensters zustellbar ist; siehe das Kundenservice-Fenster im Hub.
  • Es gibt kein wa_id zum Senden. WhatsApp identifiziert den Kontakt einer Karte über eine Account-ID; Bird leitet sie aus jedem E.164-phone_number ab, statt eine zu akzeptieren, sodass der Button auf einer Karte nie auf etwas anderes als die aufgedruckten Ziffern zeigen kann.
  • vcard ist schreibgeschützt. WhatsApp generiert es für eine Karte, die ein Kontakt geteilt hat. Es gibt keine Möglichkeit, eine Karte als rohen vCard-Text zu senden.
  • Eine Karte ist kein Kontaktdatensatz. Beim Senden werden Details in einer Nachricht geteilt; es wird nichts in Ihrem Workspace angelegt, und das Speichern durch den Empfänger ist dessen eigene Aktion, die für Sie unsichtbar bleibt.

Nächste Schritte