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);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 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
| 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) |
| 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 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
- WhatsApp-Service-Nachrichten: das Kundenservice-Fenster und das Modell, das alle Service-Nachrichten gemeinsam haben
- Kontaktinfo-Anfragen: einen Kontakt nach seiner Nummer fragen, statt eine zu senden
- WhatsApp-Nachrichten empfangen: eingehende Nachrichten, Medien und der whatsapp.received-Webhook
- WhatsApp-Nachrichten senden: der Request-Envelope, das 202-Modell und sicheres erneutes Senden
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Anleitung ansehenConnecting WhatsApp to Bird: from buying a number to a live channelDas Konzept verstehenWhat is the 24-hour customer service window on WhatsApp?Das Tool verwendenWhatsApp message builderDie Funktion erkundenWhatsApp
Übung ausprobieren und ein Implementierungs-Briefing erhalten