Sign inGet Started

Szablony uwierzytelniające WhatsApp

Szablon uwierzytelniający dostarcza jednorazowy kod weryfikacyjny. Treść szablonu dostarcza Meta podczas jego tworzenia. Przy wysyłce podaj kod jako parametr treści.

Przed wysłaniem

Zdecyduj, czy użyć szablonu zarządzanego przez Bird, czy utworzyć szablon na własnym koncie firmowym.

Wysyłanie gotowych szablonów z katalogu Bird, bird_otp i bird_otp_authifly, nie wymaga Twojej weryfikacji. Te szablony znajdują się na własnych kontach WhatsApp Business Accounts firmy Bird, a ścieżka wysyłki szablonów zarządzanych nigdy nie sprawdza statusu weryfikacji Twojej firmy.

Gdy połączone konto firmowe zgłasza not_verified, Bird odrzuca tworzenie lub duplikowanie szablonów uwierzytelniających z błędem 412 E15043 WhatsAppTemplateBusinessNotVerified. Sprawdź połączone konto i jego ostatnio zsynchronizowany status. Proces weryfikacji i obsługę statusów opisuje strona Weryfikacja firmy WhatsApp.

Ten wymóg nie dotyczy tworzenia szablonów użytkowych i marketingowych; możesz nadal je tworzyć i edytować niezależnie od statusu weryfikacji.

Twórz szablony w panelu, za pomocą bird CLI lub przez serwer MCP. Pełny proces opisuje strona Tworzenie szablonów uwierzytelniających.

Wysyłanie kodu weryfikacyjnego

POST /v1/whatsapp/messages z obiektem template wskazującym slug z katalogu:

const msg = await bird.whatsapp.send({
  to: "+14155550100",
  template: {
    slug: "bird_otp",
    language: "en",
    parameters: { code: "481920" },
  },
});
console.log(msg.id, msg.status);

W tej kategorii obowiązują cztery szczególne zasady:

  • Pomiń from. Szablon zarządzany przez Bird sam wybiera nadawcę na podstawie kategorii i regionu, więc ustawienie from zwraca 422 E15018 WhatsAppSenderNotAllowed. Wysyłka wiadomości o dowolnej treści działa odwrotnie i wymaga from, co warto pamiętać, jeśli trafiasz tu ze stron o wiadomościach interaktywnych.
  • to musi być numerem telefonu w formacie E.164. Szablonu uwierzytelniającego nie można wysłać na identyfikator użytkownika przypisany do firmy; taka próba zwraca 422 E15014 WhatsAppRecipientNotSupportedForTemplate.
  • Kod umieść w parameters.code. Wypełnia on symbol zastępczy w treści i przycisk kopiowania kodu. Wysyłka components przyjmuje natomiast dokładnie jeden pozycyjny parametr treści, czyli kod. Brak parametrów lub nadanie parametrowi nazwy zwraca 422 E15003 WhatsAppTemplateParameterMismatch.
  • Okno obsługi klienta nie jest potrzebne. Wysyłki szablonów nie zależą od okna i właśnie dlatego istnieje szablon z kodem weryfikacyjnym: musi docierać do osoby, która nigdy wcześniej do Ciebie nie pisała.

Dostępne języki dla bird_otp lub bird_otp_authifly odczytasz z katalogu szablonów. Jeśli żądany język jest niedostępny, wysyłka kończy się błędem i nie jest zastępowana innym językiem.

Przycisk kopiowania kodu

Meta sama tworzy treść szablonu uwierzytelniającego jako gotowy wzór z jednym symbolem zastępczym kodu, więc podajesz flagi, a nie tekst. Wysyłka parameters wypełnia przycisk na podstawie code. W wysyłce components komponent przycisku jest opcjonalny: jeśli go nie dodasz, Bird doda go za Ciebie z tym samym kodem co w treści. Możesz też podać go samodzielnie:

Przykład kodu
{ "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }

W obu przypadkach do WhatsApp trafia dokładnie jeden przycisk, czyli przycisk kopiowania kodu: jego dotknięcie kopiuje kod do schowka. Bird obsługuje wyłącznie copy_code; dwa pozostałe zachowania przycisków, które Meta opisuje dla szablonów uwierzytelniających, czyli autouzupełnianie jednym dotknięciem i bez dotknięcia, nie są dostępne w Bird.

Przycisk tworzonego szablonu ma taki sam układ: jeden przycisk otp, a szablon nie przyjmuje innych typów przycisków. Zamiast pisać tekst, podajesz add_security_recommendation (wartość logiczną wyświetlaną w treści) i code_expiration_minutes (od 1 do 90, wyświetlane w stopce).

Co Meta dopuszcza w szablonie uwierzytelniającym

Meta ustala strukturę szablonu uwierzytelniającego i weryfikuje jego treść: w całym szablonie nie mogą występować adresy URL, multimedia ani emoji, a parametr kodu może mieć maksymalnie 15 znaków. Kategoria zmienia też sposób, w jaki WhatsApp dostarcza wiadomość: trafia ona tylko na główne urządzenie odbiorcy. Pełny opis stałej struktury, limitów znaków i procesu weryfikacji znajdziesz w sekcji Wytyczne dotyczące szablonów.

Koszt

Cenę wyznaczają kategoria i kraj docelowy. Na stronie WhatsApp authentication-international rates sprawdzisz, jak wysyłka do kraju innego niż Twoja główna lokalizacja może ją zmienić, a na stronie Koszty i rozliczenia, kiedy wysyłka jest obciążana opłatą. Stawki znajdziesz w cenniku WhatsApp pricing.

Na co uważać

  • Szablony z katalogu Bird nie docierają do dziewięciu krajów. bird_otp i bird_otp_authifly są wysyłane z własnych kont WhatsApp Business Accounts firmy Bird, a te konta nie dostarczają wiadomości uwierzytelniających do Egiptu, Indii, Indonezji, Malezji, Nigerii, Pakistanu, Arabii Saudyjskiej, Republiki Południowej Afryki ani Zjednoczonych Emiratów Arabskich. Taka wysyłka jest odrzucana z kodem 422 E15063 WhatsAppDestinationRestricted, zanim zostanie naliczona jakakolwiek opłata. Szablon utworzony na Twoim własnym koncie i wysłany z Twojego numeru normalnie dociera do tych krajów. Verify również do nich dociera, samodzielnie przenosząc kod weryfikacyjny na inny kanał.
  • Wysyłka własnego szablonu wymaga from, który musi należeć do tego samego konta WhatsApp Business Account co szablon. Nadawca z innego konta jest odrzucany z kodem 422 E15023 WhatsAppSenderWABAMismatch, zanim zostanie naliczona jakakolwiek opłata.
  • Wysłać można tylko język, którego wersja jest zatwierdzona i aktywna. Języka w wersji roboczej, oczekującej, odrzuconej lub wstrzymanej nie można wysłać.
  • Meta może z własnej inicjatywy zmienić kategorię szablonu. Nie można z tego zrezygnować, a zmiana przenosi szablon pod reguły cenowe i reguły dostarczania nowej kategorii.
  • Kategoria szablonu i kategoria jego języka mogą się różnić. Na stronie WhatsApp templates sprawdzisz, jak ścieżka wysyłki rozwiązuje tę różnicę.
  • Zaimportowanego szablonu uwierzytelniającego nie można zduplikować. Bird nie potrafi odczytać tekstu wygenerowanego przez WhatsApp z powrotem do ustawień, z których buduje się nowy szablon; zwraca wtedy 422 E15024 WhatsAppTemplateContentNotDuplicable. Zamiast tego utwórz nowy szablon z własną rekomendacją bezpieczeństwa i czasem wygaśnięcia kodu.

Następne kroki