Sign inGet started

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

PoleOgraniczenieEgzekwowane przez
contact_cardsod 1 do 5 wizytówek na wiadomośćBird, przy przyjęciu (422)
namewymagane; formatted_name plus jedna dodatkowa część nazwyBird, przy przyjęciu (422)
formatted_name, first_name, middle_name, last_namedo 256 znakówBird, przy przyjęciu (422)
prefix, suffixdo 64 znakówBird, przy przyjęciu (422)
birthdayopcjonalne, YYYY-MM-DD, data istniejąca w kalendarzuBird, przy przyjęciu (422)
phone_numbers, emails, urls, addressesdo 10 wpisów każdaBird, przy przyjęciu (422)
phone_numberdo 32 znakówBird, przy przyjęciu (422)
emaildo 254 znakówBird, przy przyjęciu (422)
urldo 2048 znaków, bez walidacji jako URLBird, przy przyjęciu (422)
type na dowolnym telefonie, e-mailu, stronie lub adresiedo 64 znaków dowolnego tekstuBird, przy przyjęciu (422)
company, department, titledo 128 znakówBird, przy przyjęciu (422)
street, city, state, zip, country, country_codedo 128 znakówBird, 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