# 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: **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](/de-de/dokumentation/guides/whatsapp/message-types/contact-cards.ts.md) · [Python](/de-de/dokumentation/guides/whatsapp/message-types/contact-cards.py.md) · [Go](/de-de/dokumentation/guides/whatsapp/message-types/contact-cards.go.md) · [PHP](/de-de/dokumentation/guides/whatsapp/message-types/contact-cards.php.md) · [CLI](/de-de/dokumentation/guides/whatsapp/message-types/contact-cards.cli.md) · [cURL](/de-de/dokumentation/guides/whatsapp/message-types/contact-cards.curl.md) `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: ```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" } ] } ] } ``` 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 | Feld | Grenzwert | Durchgesetzt von | | ----------------------------------------------------------- | --------------------------------------------------------------- | ------------------------- | | `contact_cards` | 1 bis 5 Karten pro Nachricht | Bird, bei Annahme (`422`) | | `name` | erforderlich; `formatted_name` plus ein weiterer Namensteil | Bird, bei Annahme (`422`) | | `formatted_name`, `first_name`, `middle_name`, `last_name` | bis zu 256 Zeichen | Bird, bei Annahme (`422`) | | `prefix`, `suffix` | bis zu 64 Zeichen | Bird, bei Annahme (`422`) | | `birthday` | optional, `YYYY-MM-DD`, und ein Datum, das der Kalender enthält | Bird, bei Annahme (`422`) | | `phone_numbers`, `emails`, `urls`, `addresses` | jeweils bis zu 10 Einträge | Bird, bei Annahme (`422`) | | `phone_number` | bis zu 32 Zeichen | Bird, bei Annahme (`422`) | | `email` | bis zu 254 Zeichen | Bird, bei Annahme (`422`) | | `url` | bis zu 2048 Zeichen, nicht als URL validiert | Bird, bei Annahme (`422`) | | `type` bei Telefon, E-Mail, Website oder Adresse | bis zu 64 Zeichen Freitext | Bird, bei Annahme (`422`) | | `company`, `department`, `title` | bis zu 128 Zeichen | Bird, bei Annahme (`422`) | | `street`, `city`, `state`, `zip`, `country`, `country_code` | bis zu 128 Zeichen | Bird, 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`](/docs/api/errors/E15061) `WhatsAppContactNameIncomplete` abgelehnt, der `contact_cards..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`](/docs/api/errors/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}`: ```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` 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](/docs/guides/whatsapp/receiving-whatsapp/contact-cards) 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](/docs/guides/whatsapp/message-types#the-customer-service-window) 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 - [WhatsApp-Service-Nachrichten](/docs/guides/whatsapp/message-types): das Kundenservice-Fenster und das Modell, das alle Service-Nachrichten gemeinsam haben - [Kontaktinfo-Anfragen](/docs/guides/whatsapp/message-types/interactive/contact-info-requests): einen Kontakt nach seiner Nummer fragen, statt eine zu senden - [WhatsApp-Nachrichten empfangen](/docs/guides/whatsapp/receiving-whatsapp): eingehende Nachrichten, Medien und der `whatsapp.received`-Webhook - [WhatsApp-Nachrichten senden](/docs/guides/whatsapp/sending-whatsapp): der Request-Envelope, das `202`-Modell und sicheres erneutes Senden ## 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)