Dokumentacja
Sign inGet started
Rozpocznij
Przewodniki
Referencja API
SDK
CLI
Baza wiedzy
Changelog

Tworzenie szablonów WhatsApp

Zarządzany katalog Bird obejmuje typowe przypadki, ale szablon napisany własnymi słowami musisz utworzyć na koncie WhatsApp Business Account, które masz podłączone. Ta strona opisuje tworzenie szablonu; Szablony WhatsApp opisuje przeglądanie i wysyłanie już istniejących.
Trzy rzeczy kształtują cały proces:
  • Szablon zawiera wersje, a wersja zawiera jeden wpis na język. Wysyłany jest konkretny język konkretnej wersji, nie sam szablon.
  • Treść zapisuje się w szkicu. Szablon może mieć co najwyżej jeden otwarty szkic i nic z niego nie trafia do WhatsApp, dopóki go nie wyślesz.
  • Zatwierdzenie przychodzi osobno dla każdego języka. Jeden język może zostać zatwierdzony, podczas gdy inny w tej samej wersji zostanie odrzucony.

Zanim zaczniesz

Potrzebujesz podłączonego własnego numeru, który daje Twojemu obszarowi roboczemu konto WhatsApp Business Account do tworzenia szablonów. Konto, którego nie podłączyłeś, zostanie odrzucone, podobnie jak edycja wbudowanych szablonów bird_ od Bird: te są na koncie Bird, więc zduplikuj wybrany na swoje konto.
Tworzenie szablonu authentication wymaga dodatkowo zweryfikowanej firmy; utility i marketing nie. Szczegóły znajdziesz w Authentication templates.
Twórz szablon w dashboardzie w sekcji WhatsApp > Templates, za pomocą bird CLI lub przez serwer MCP. Dashboard prowadzi przez te same kroki, które opisuje ta strona; przykłady poniżej używają CLI.

W dashboardzie

New template oferuje dwa sposoby. Start with a template otwiera galerię, czyli najszybszą ścieżkę: wybierz szablon, który mówi niemal to, czego potrzebujesz, w tym jeden od Bird, a kopia trafi na Twoje konto jako otwarty szkic.
Galeria szablonów w dashboardzie Bird: siatka kart szablonów, z których każda wyświetla podgląd wiadomości i jest opisana nazwą, slugiem, statusem, kategorią i językami, obok filtrów źródła szablonu, kategorii i języka
Start from scratch pyta o kategorię, nazwę i domyślny język przed otwarciem edytora. Szablon marketingowy wymaga też wyboru typu wiadomości. Nazwa staje się slugiem, a slug i kategoria to dwa wybory, których nie zmienisz później.
Krok Create a new template w dashboardzie Bird: kafelki kategorii Marketing, Utility i Authentication nad polem Name i selektorem Default language, z przyciskiem Create template
Edytor obsługuje jeden język naraz: pasek boczny wyświetla języki szablonu ze stanem przeglądu każdego z nich, środkowa kolumna zawiera treść, a podgląd telefonu renderuje wiadomość z podstawionymi przykładowymi wartościami.
Edytor szablonów w dashboardzie Bird dla szablonu utility Order update: English oznaczony jako Approved obok Dutch na pasku bocznym języków, a obok podgląd telefonu z wyrenderowaną wiadomością z przyciskami Track order i Contact support
Edytor zmienia kształt wraz z szablonem. Karuzela dodaje zakładkę na każdą kartę obok wiadomości, a każda karta musi powtarzać strukturę karty 1: ten sam format nagłówka i te same przyciski w tej samej kolejności.
Edytor szablonów w dashboardzie Bird dla karuzelowego szablonu marketingowego: zakładki Message, Card 1, Card 2 i Card 3 nad treścią wiadomości, sekcja Variable samples poniżej, a obok podgląd telefonu z wiadomością i przesuwanymi kartami ze zdjęciami, każda z przyciskiem Show me
Szablon authentication nie ma edytora wiadomości. WhatsApp pisze treść, więc edytor oferuje tylko dwa ustawienia, z których ją generuje: Add security recommendation i Code expiration (minutes).
Edytor szablonów w dashboardzie Bird dla szablonu authentication: panel Authentication settings z przełącznikiem Add security recommendation i polem Code expiration (minutes), a obok podgląd telefonu z wiadomością z kodem weryfikacyjnym, którą pisze WhatsApp, z przyciskiem Copy code
Save as draft zapisuje pracę bez kontaktowania się z WhatsApp. Submit for review zamraża wersję i wysyła ją do WhatsApp. Przesłanie przez CLI, opisane poniżej, wykonuje to samo zamrożenie.

Dwa sposoby na start

Duplikowanie istniejącego szablonu

Duplikat przenosi treść źródła jako otwarty szkic i nie wywołuje WhatsApp ani razu, więc nic nie zostanie przesłane, dopóki sam tego nie zrobisz. Dwie rzeczy warto wiedzieć o kopii, zanim ją utworzysz:
  • Kategoria jest dziedziczona i nie można jej zmienić. Jeśli potrzebujesz innej kategorii, zacznij od zera.
  • Możesz zawęzić zestaw języków, ale nigdy go rozszerzyć. Szablon katalogowy z 70 językami nie musi stać się 70 językami u Ciebie: wybierz podzbiór, który faktycznie będziesz utrzymywać. Żądanie języka, którego źródło nie zawiera, jest odrzucane z E15060, a odpowiedź wskazuje, które języki nie pasowały. Dodatkowe języki dodaj do kopii później.
Podzbiór języków to tablica, więc trafia do ciała żądania, a nie jako flaga:
Przykład kodu
bird whatsapp templates duplicate bird_order_confirmation --body-file copy.json
Przykład kodu
{
  "waba": "102290129340398",
  "slug": "acme_order_update",
  "include_languages": ["en", "es-ES"],
  "default_language": "en"
}
Pomiń include_languages, a kopia przejmie wszystkie języki źródła. Pomiń default_language, a kopia zachowa domyślny język źródła, jeśli Twój podzbiór go zawiera; w przeciwnym razie przyjmie pierwszy z języków kopii według kanonicznego tagu, co niekoniecznie jest pierwszym na Twojej liście, więc ustaw go jawnie, jeśli ma to znaczenie.

Tworzenie od zera

Utworzenie szablonu wymaga sluga, konta, kategorii i domyślnego języka:
Przykład kodu
bird whatsapp templates create order_update \
  --waba 102290129340398 \
  --category utility \
  --default-language en
Slug i kategoria są trwałe. WhatsApp wyprowadza własną nazwę szablonu ze sluga i ani jej, ani kategorii nie można później zmienić; inna wartość oznacza nowy szablon. Prefiks bird_ jest zarezerwowany dla katalogu Bird. Wybrana kategoria niekoniecznie odpowiada kategorii, według której naliczana jest opłata za wysyłkę: Meta przypisuje własną kategorię na język i może ją zmienić, a cena podąża za kategorią Mety.

Pisanie każdej wersji językowej

Otwórz szkic, a potem pisz jeden język naraz:
Przykład kodu
bird whatsapp templates versions create order_update
bird whatsapp templates versions languages set order_update <version-id> en --body-file en.json
Otwieranie szkicu można bezpiecznie powtarzać: szablon ma tylko jeden, więc wywołanie zwraca otwarty szkic zamiast tworzyć drugi. Szablon raportuje go również jako draft_version_id.
Zapis języka zastępuje go w całości, nie scala się z nim. Plik za każdym razem zawiera kompletną treść components danego języka, więc najpierw odczytaj język i zapisz go z powrotem w całości; wysłanie tylko zmienionego bloku usunie resztę.
Każda zmienna wymaga przykładowej wartości. WhatsApp sprawdza wypełnioną wiadomość, a nie szablon, więc blok z placeholderami bez przykładowych parametrów zostanie odrzucony przy przesyłaniu, nie przy zapisie.

Sprawdź, potem wyślij

Zwaliduj przed zamrożeniem czegokolwiek. Przesłanie tylko do walidacji uruchamia wszystkie sprawdzenia we wszystkich językach i zgłasza każdy problem w jednym przebiegu, nic nie wysyłając do WhatsApp:
Przykład kodu
bird whatsapp templates versions submit order_update <version-id> --validate-only
Odczytaj valid i errors; każdy błąd wskazuje język, pole i kod, z jakim prawdziwe przesłanie by się nie powiodło. Następnie wyślij naprawdę, usuwając flagę. To zamraża szkic jako niezmienną wersję i odpowiada 202. Użyj innego klucza idempotentności dla sprawdzenia i przesłania, ponieważ ponowne użycie tego samego klucza ze zmienionym ciałem żądania jest odrzucane.
Do WhatsApp trafiają tylko języki, których treść różni się od zatwierdzonej kopii. Język, który już się zgadza, zachowuje zatwierdzenie, więc przesłanie bez zmian rozwiązuje się natychmiast i nie ma czego pollować. Nowy szkic nie otwiera się automatycznie: następna runda edycji zaczyna się od ponownego utworzenia szkicu.
Czysta walidacja nie przewiduje decyzji WhatsApp. WhatsApp nie oferuje możliwości zapytania z wyprzedzeniem, więc może nadal odrzucić treść, która przeszła każde lokalne sprawdzenie.

Śledzenie przeglądu

Zatwierdzenie przychodzi później i osobno dla każdego języka. pending_version_id szablonu pozostaje ustawiony, dopóki jakikolwiek język jest nierozstrzygnięty, a lista per język zawiera każdy werdykt:
  • approved umożliwia wysyłkę. available_languages na szablonie zawiera dokładnie te języki, które można teraz wybrać przy wysyłce.
  • rejected, submit_failed, paused wymagają edycji w nowym szkicu. WhatsApp akceptuje edycję wstrzymanego języka, a ponowne przesłanie to sposób na wyczyszczenie tego stanu.
  • disabled, limit_exceeded, in_appeal odrzucają edycję całkowicie; wymagają jedynie ponownego odczytu, dopóki WhatsApp nie zmieni ich stanu.
Własny status szablonu jest agregatem: active oznacza, że co najmniej jeden język jest gotowy do wysyłki, a nie wszystkie.

Wysyłanie utworzonego szablonu

Utworzony szablon wysyła się przez ten sam endpoint co każdy inny, z jedną różnicą w stosunku do katalogu Bird: musisz wskazać from, a musi to być numer na tym samym koncie WhatsApp Business Account co szablon. Nadawca z innego konta jest odrzucany 422 E15023, zanim cokolwiek zostanie naliczone.
Szablon może wymagać języka odbiorcy przez language_source_required. W przeciwnym razie on_missing_language kontroluje, czy wybór języka kończy się błędem, czy może użyć zatwierdzonego języka bazowego lub default_language. Przetestuj skonfigurowaną politykę na tle zatwierdzonych available_languages szablonu; niezatwierdzony domyślny język uniemożliwia wysyłkę. Wartości, które podajesz, muszą wypełnić placeholdery tego języka, który faktycznie zostanie wybrany, więc odczytaj treść tego języka przed wysyłką. Pełną strukturę danych żądania znajdziesz w Wysyłanie wiadomości WhatsApp.

Na co uważać

  • Najnowsza wersja to nie ta, która wysyła. Lista wersji jest od najnowszej i zawiera otwarty szkic, więc górny wiersz to często szkic lub wersja jeszcze pod przeglądem. Szablon wskazuje wersję w użyciu jako live_version_id; szablon bez aktywnej wersji nie może być w ogóle wysłany.
  • Język w trakcie przeglądu odmawia zapisu. WhatsApp blokuje go do zakończenia przeglądu, więc edycja w trakcie pending kończy się błędem, a nie kolejkowaniem.
  • Wiersz na liście nie zawiera treści. Listowanie szablonów znajduje je i pokazuje stan cyklu życia; odczyt tego, co szablon faktycznie mówi, wymaga odczytu wersji.
  • Usunięcie jest nieodwracalne. Usunięcie wersji językowej, usunięcie szkicu i usunięcie szablonu wymagają jawnego potwierdzenia, a usunięcie szablonu zatrzymuje każdą wysyłkę po tym slugu.

Następne kroki

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Zrozum koncepcjęWhat is a WhatsApp message template?Poznaj możliwościWhatsApp templatesPodążaj ścieżką naukiBuild your first integration
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy