Sign inGet started

Żądania informacji kontaktowych WhatsApp

Żądanie informacji kontaktowych umieszcza pod wiadomością WhatsApp jeden przycisk z prośbą o udostępnienie numeru telefonu. Używaj go, gdy potrzebujesz numeru do kontaktu z kimś, na przykład w celu oddzwonienia lub potwierdzenia rezerwacji, a nie zapisanego adresu. Jeśli potrzebujesz lokalizacji, użyj żądań lokalizacji.

Wyślij żądanie informacji kontaktowych

Ustaw interactive.type na request_contact_info z polem body_text i niczym więcej. WhatsApp renderuje sam przycisk, więc nie ma czym go podpisać:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "request_contact_info",
    body_text:
      "To confirm your booking we need a number to reach you on. Tap below to share yours.",
  },
});
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. Ten typ nie definiuje własnego pola, a schemat zabrania pola header, footer_text oraz każdego pola innego typu (buttons, list, cta_url, cards), więc body_text stanowi całą wiadomość, ograniczoną do 1024 znaków. Meta nie określa limitu długości treści dla tego typu; Bird stosuje limit 1024 znaków, który obowiązuje każdy inny typ interaktywny z wyjątkiem menu listowego.
in_reply_to_message_id nadal działa w tym typie i pozwala zacytować wcześniejszą wiadomość z tej samej konwersacji. Zobacz w hubie cytowanie wiadomości w celu skorelowania odpowiedzi, aby dowiedzieć się, jak działa rozwiązywanie i co może pominąć.

Odczytywanie udostępnionego kontaktu

Dotknięcie nie generuje interactive_reply. Przychodzi jako zwykła wiadomość przychodząca z tablicą contact_cards:
Przykład kodu
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234", "bsuid": "US.13491208655302741918" },
  "to": { "phone_number": "+13124495648" },
  "status": "received",
  "contact_cards": [
    {
      "origin": "contact_request",
      "phone_numbers": [{ "phone_number": "+14155550829", "type": "cell" }]
    }
  ],
  "created_at": "2026-08-26T10:00:00Z"
}
contact_cards to tablica, a wiadomość contacts, która nie zawierała karty, zwraca [] zamiast nieobecnego pola. To samo pole przenosi kartę, którą wysyłasz, więc kartę będącą odpowiedzią na to żądanie rozróżnia się po origin, a nie po polu, w którym przychodzi. Sprawdzenie origin jest obowiązkowe, zanim potraktujesz kartę jako swoją odpowiedź. origin ma wartość contact_request, gdy karta jest odpowiedzią na to żądanie, lub other, gdy kontakt udostępnił kartę spontanicznie, co może dotyczyć zupełnie innej osoby, a nie samego kontaktu. Dotknięcie zawiera tylko phone_numbers[].{phone_number, type} i pomija vcard; pełny obiekt kontaktu z name, org, birthday i resztą przychodzi tylko w origin: "other". Tę odpowiedź widzisz na liście wiadomości lub przez GET /v1/whatsapp/messages/{id}; zobacz w hubie odczytywanie odpowiedzi, aby poznać pełną ścieżkę.

Korelowanie odpowiedzi z pytaniem

W odróżnieniu od żądania lokalizacji Meta nie umieszcza context w odpowiedzi tego typu, więc in_reply_to_message_id jest pomijane zamiast rozwiązywane. Koreluj po from plus niedawno wysłana wiadomość własna albo zaakceptuj, że nie jest to możliwe. Dwa nierozstrzygnięte żądania do tego samego kontaktu są nierozróżnialne: nic w odpowiedzi nie wskazuje, na które żądanie odpowiada, więc obszar roboczy, który wyśle drugie żądanie informacji kontaktowych przed uzyskaniem odpowiedzi na pierwsze, nie jest w stanie stwierdzić, która karta odpowiada na które.
To celowy kontrast z żądaniami lokalizacji: odpowiedź tego typu zawiera własny context Mety, więc in_reply_to_message_id jest rozwiązywane i mechanizm huba cytowanie wiadomości w celu skorelowania odpowiedzi sam łączy odpowiedź z pytaniem. Odpowiedź na żądanie informacji kontaktowych nie ma takiego mechanizmu, na którym można się oprzeć.

Żądanie w szablonie zamiast wiadomości interaktywnej

Wiadomość interaktywna request_contact_info jest swobodnym odpowiednikiem przycisku szablonu REQUEST_CONTACT_INFO, który prosi o tę samą kartę kontaktową, ale może dotrzeć do odbiorcy, którego okno obsługi klienta jest zamknięte. Użyj wiadomości interaktywnej, gdy odbiorca niedawno do Ciebie napisał i chcesz dostosować treść prośby do tej konwersacji; użyj przycisku szablonu, gdy okno jest zamknięte lub gdy prośba towarzyszy wiadomości, którą już wysyłasz jako szablon. Zobacz szablony WhatsApp, aby dowiedzieć się, jak wysyłać za pomocą szablonu.

Na co uważać

  • Okno obsługi klienta musi być otwarte. Żądanie informacji kontaktowych jest wiadomością serwisową, dostarczalną tylko w otwartym oknie; zobacz w hubie okno obsługi klienta. Sprawdzenie okna kończy się wynikiem pozytywnym w razie wątpliwości, więc 202 nie jest dowodem, że okno było faktycznie otwarte w momencie wysyłki.
  • from musi być numerem należącym do Twojego obszaru roboczego, a okno, które musi być otwarte, jest powiązane z tym numerem, nie z całym obszarem roboczym.
  • Odpowiedzi nie da się powiązać z żądaniem po id. Brak context po stronie Mety oznacza, że in_reply_to_message_id jest pomijane w odpowiedzi; koreluj po from plus niedawno wysłana wiadomość własna.
  • Odmowa jest cicha. WhatsApp pokazuje odbiorcy arkusz udostępniania, a jego odrzucenie nie generuje żadnej wiadomości ani webhooka. Brak wiadomości contact_cards to jedyny sygnał, więc każdy przepływ oczekujący na odpowiedź potrzebuje własnego limitu czasu zamiast zdarzenia odmowy, na które mógłby nasłuchiwać.
  • Brak nagłówka, stopki i etykiety przycisku. Schemat zabrania header i footer_text w tym typie, a przycisk nie ma pola na etykietę. Wszystko, co odbiorca przeczyta, musi znajdować się w body_text.
  • Udostępniony numer nie musi być numerem, z którego kontakt prowadzi czat. Meta ostrzega, że ID użytkownika i numer telefonu nie zawsze muszą się zgadzać, więc nie zakładaj, że udostępniony numer jest równy from.phone_number. Nie ma też gwarancji formatu E.164: Bird normalizuje go tam, gdzie da się go sparsować, a tam, gdzie nie, przekazuje dosłownie.
  • Odpowiedź jest wiadomością contact_cards, a nie interactive_reply. Integracja, która nasłuchuje tylko interactive_reply w oczekiwaniu na dotknięcie, przeoczy ten typ całkowicie, podobnie jak integracja, która nasłuchuje tylko przychodzących location dla drugiego typu żądań.
Wszystko, co schemat jest w stanie tu wyrazić: za długi body_text, header, footer_text lub dowolne z buttons, list, cta_url, cards, to zwykły błąd walidacji żądania bez kodu katalogowego. Cytat, który nie rozwiązuje się, powoduje odrzucenie żądania, zanim cokolwiek zostanie utworzone lub naliczone: 404 E15071, gdy id wskazuje wiadomość, której ten obszar roboczy nie posiada, 422 E15072, gdy wskazuje wiadomość, której nie można zacytować. Zobacz w hubie błędy, aby poznać pełną tabelę błędów interaktywnych, oraz Wysyłanie wiadomości WhatsApp, aby poznać błędy, na które może natrafić każde wysłanie WhatsApp.

Następne kroki