Wizytówki kontaktowe WhatsApp
Wiadomość z wizytówką kontaktową udostępnia jeden lub więcej kontaktów: imię i nazwisko widoczne na karcie dla odbiorcy oraz widok profilu, który otwiera się po kliknięciu i zawiera numery telefonów, adresy e-mail, strony internetowe, adresy pocztowe, pracodawcę i datę urodzin. Użyj jej, żeby przekazać klientowi numer kolegi, kuriera albo swój własny, zamiast wklejać cyfry w tekst, który odbiorca musi potem przepisywać ręcznie.
Wyślij wizytówkę kontaktową
contact_cards to tablica. Każda wizytówka wymaga name, a ta nazwa wymaga formatted_name oraz co najmniej jednej dodatkowej części:
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 jest wymagane w każdej wiadomości serwisowej: numer należący do Twojego obszaru roboczego, a nie zarządzany przez Bird.
Pełna struktura dodaje pracodawcę, datę urodzin i pozostałe tablice danych kontaktowych:
Przykład kodu
{
"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"
}
]
}
]
}Każda etykieta type, niezależnie czy dotyczy telefonu, e-maila, strony internetowej czy adresu, to dowolny tekst wpisany przez Ciebie, wysyłany dokładnie tak, jak go wpisałeś, i wyświetlany obok wartości w widoku profilu odbiorcy. WhatsApp nie definiuje żadnego słownika dla tych etykiet, więc Mobile, Landline, Pop-Up i Work (old) są równie poprawne.
Co daje wizytówce przycisk
Numer telefonu zapisany w formacie E.164, z kodem kraju i wiodącym +, daje wizytówce przycisk otwierający czat WhatsApp z tym numerem. Numer, którego Bird nie może odczytać jako E.164, nadal wyświetla się na wizytówce dokładnie tak, jak go wpisałeś, ale nie otrzymuje przycisku.
Dotyczy to też numeru zapisanego bez wiodącego +. Bird nie doda go za Ciebie: numer w formacie krajowym z jednego kraju może zostać sparsowany jako poprawny numer w innym kraju po dodaniu +, co skierowałoby przycisk do obcej osoby. Rezygnacja z odgadywania kosztuje przycisk; błędne odgadnięcie kosztuje odbiorcę czat z niewłaściwą osobą.
Wizytówka bez żadnego numeru telefonu wyświetla się bez przycisku czatu i można ją jedynie zapisać w książce adresowej.
Limity
| Pole | Ograniczenie | Egzekwowane przez |
|---|---|---|
| contact_cards | od 1 do 5 wizytówek na wiadomość | Bird, przy przyjęciu (422) |
| name | wymagane; formatted_name plus jedna dodatkowa część nazwy | Bird, przy przyjęciu (422) |
| formatted_name, first_name, middle_name, last_name | do 256 znaków | Bird, przy przyjęciu (422) |
| prefix, suffix | do 64 znaków | Bird, przy przyjęciu (422) |
| birthday | opcjonalne, YYYY-MM-DD, data istniejąca w kalendarzu | Bird, przy przyjęciu (422) |
| phone_numbers, emails, urls, addresses | do 10 wpisów każda | Bird, przy przyjęciu (422) |
| phone_number | do 32 znaków | Bird, przy przyjęciu (422) |
| do 254 znaków | Bird, przy przyjęciu (422) | |
| url | do 2048 znaków, bez walidacji jako URL | Bird, przy przyjęciu (422) |
| type na dowolnym telefonie, e-mailu, stronie lub adresie | do 64 znaków dowolnego tekstu | Bird, przy przyjęciu (422) |
| company, department, title | do 128 znaków | Bird, przy przyjęciu (422) |
| street, city, state, zip, country, country_code | do 128 znaków | Bird, przy przyjęciu (422) |
Limit pięciu wizytówek pochodzi od Bird i celowo jest znacznie poniżej tego, co akceptuje WhatsApp. Opublikowany opis API od WhatsApp deklaruje pięć, dokumentacja zaleca mniejszą liczbę ze względu na użyteczność i ryzyko negatywnych reakcji, a wiadomość otwierająca się jako "Contact 1 and 256 other contacts" to wektor spamu, zanim stanie się funkcją. Podniesienie limitu później byłoby zmianą addytywną, więc zapytaj, jeśli pięć to za mało dla tego, co budujesz.
Każdy powyższy limit długości też pochodzi od Bird. WhatsApp nie egzekwuje żadnych godnych uwagi, a jego klient tego nie kompensuje: 500-znakowe type renderuje się jako dziesięć linii jednej powtarzanej litery, a 4000-znakowe url jest po cichu odrzucane, pozostawiając widok profilu pusty. 422 wskazujący problematyczne pole jest lepszy niż wizytówka, której odbiorca nie może odczytać.
Dwie reguły, których schemat nie może wyrazić
Nazwa wymaga drugiej części. Samo formatted_name jest odrzucane z 422 E15061 WhatsAppContactNameIncomplete, wskazując contact_cards.<n>.name. Dowolne z prefix, first_name, middle_name, last_name lub suffix spełnia ten wymóg, ale pusta wartość lub sama biała spacja się nie liczy, a org go nie ratuje. To własny wymóg WhatsApp, nigdzie nieudokumentowany w jego referencji; Bird przechwytuje go przy przyjęciu, dzięki czemu dostajesz konkretny błąd zamiast asynchronicznej awarii.
Data urodzin musi być prawdziwą datą. birthday to YYYY-MM-DD; każdy inny format i każda data nieistniejąca w kalendarzu, na przykład 2026-02-30, jest odrzucana z 422 E15062 WhatsAppContactBirthdayInvalid. Sam WhatsApp akceptuje 2026-02-30 i wyświetla to odbiorcy, co wygląda jak błąd w Twoich danych.
Odczyt wizytówki
Wysłana wizytówka jest zwracana na tym samym polu contact_cards, którego używa wizytówka przychodząca, przez listę wiadomości lub GET /v1/whatsapp/messages/{id}:
Przykład kodu
{
"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 i vcard są nieobecne na wysłanej wizytówce: WhatsApp ustawia oba na wizytówce udostępnionej przez kontakt. Wysłana etykieta type jest zwracana dokładnie tak, jak została zapisana, natomiast etykieta na odebranej wizytówce jest zamieniana na małe litery. Zobacz Odbieranie wizytówek kontaktowych WhatsApp, żeby poznać stronę przychodzącą.
Przypadki brzegowe
- Okno obsługi klienta musi być otwarte. Wysłanie wizytówki kontaktowej to wiadomość serwisowa, dostarczalna tylko w otwartym oknie; zobacz okno obsługi klienta w hubie.
- Nie ma wa_id do wysłania. WhatsApp identyfikuje kontakt wizytówki po ID konta; Bird wyprowadza go z każdego phone_number w formacie E.164 zamiast go przyjmować, więc przycisk na wizytówce nigdy nie może wskazywać czegoś innego niż cyfry na niej wydrukowane.
- vcard jest tylko do odczytu. WhatsApp generuje go dla wizytówki udostępnionej przez kontakt. Nie ma możliwości wysłania wizytówki jako surowego tekstu vCard.
- Wizytówka to nie rekord kontaktu. Wysłanie jej udostępnia dane w wiadomości; nie tworzy niczego w Twoim obszarze roboczym, a zapisanie jej przez odbiorcę to jego własna czynność, niewidoczna dla Ciebie.
Następne kroki
- Wiadomości serwisowe WhatsApp: okno obsługi klienta i model wspólny dla wszystkich wiadomości serwisowych
- Żądania informacji kontaktowych: poproś kontakt o jego numer zamiast wysyłać swój
- Odbieranie wiadomości WhatsApp: wiadomości przychodzące, multimedia i webhook whatsapp.received
- Wysyłanie wiadomości WhatsApp: koperta żądania, model 202 i bezpieczne ponawianie
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Obejrzyj przewodnikConnecting WhatsApp to Bird: from buying a number to a live channelZrozum koncepcjęWhat is the 24-hour customer service window on WhatsApp?Użyj narzędziaWhatsApp message builderPoznaj możliwościWhatsApp
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy