# 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: **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](/pl-pl/dokumentacja/guides/whatsapp/message-types/contact-cards.ts.md) · [Python](/pl-pl/dokumentacja/guides/whatsapp/message-types/contact-cards.py.md) · [Go](/pl-pl/dokumentacja/guides/whatsapp/message-types/contact-cards.go.md) · [PHP](/pl-pl/dokumentacja/guides/whatsapp/message-types/contact-cards.php.md) · [CLI](/pl-pl/dokumentacja/guides/whatsapp/message-types/contact-cards.cli.md) · [cURL](/pl-pl/dokumentacja/guides/whatsapp/message-types/contact-cards.curl.md) `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: ```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" } ] } ] } ``` 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`) | | `email` | 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`](/docs/api/errors/E15061) `WhatsAppContactNameIncomplete`, wskazując `contact_cards..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`](/docs/api/errors/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}`: ```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` 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](/docs/guides/whatsapp/receiving-whatsapp/contact-cards), ż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](/docs/guides/whatsapp/message-types#the-customer-service-window) 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](/docs/guides/whatsapp/message-types): okno obsługi klienta i model wspólny dla wszystkich wiadomości serwisowych - [Żądania informacji kontaktowych](/docs/guides/whatsapp/message-types/interactive/contact-info-requests): poproś kontakt o jego numer zamiast wysyłać swój - [Odbieranie wiadomości WhatsApp](/docs/guides/whatsapp/receiving-whatsapp): wiadomości przychodzące, multimedia i webhook `whatsapp.received` - [Wysyłanie wiadomości WhatsApp](/docs/guides/whatsapp/sending-whatsapp): koperta żądania, model `202` i bezpieczne ponawianie ## 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)