# 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](/docs/guides/whatsapp/templates) 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](/docs/guides/whatsapp/phone-number-setup), 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](/docs/guides/whatsapp/templates/authentication#before-you-send).

Twórz szablon w dashboardzie w sekcji **WhatsApp** > **Templates**, za pomocą [`bird` CLI](/docs/cli) lub przez [serwer MCP](/docs/ai/mcp-server). 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](/images/docs/dashboard-whatsapp-template-gallery.png)

**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](/images/docs/dashboard-whatsapp-template-details.png)

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](/images/docs/dashboard-whatsapp-template-builder.png)

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](/images/docs/dashboard-whatsapp-template-builder-carousel.png)

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](/images/docs/dashboard-whatsapp-template-builder-auth.png)

**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`](/docs/api/errors/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:

```bash
bird whatsapp templates duplicate bird_order_confirmation --body-file copy.json
```

```json
{
  "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:

```bash
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:

```bash
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:

```bash
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`](/docs/api/errors/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](/docs/guides/whatsapp/sending-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

- [Szablony WhatsApp](/docs/guides/whatsapp/templates): katalog, kategorie i wspólny kontrakt wysyłki przez szablon
- [Wytyczne dotyczące szablonów](/docs/knowledge-base/whatsapp/template-guidelines): czego szuka przegląd Mety
- [Konfiguracja numeru telefonu](/docs/guides/whatsapp/phone-number-setup): podłączanie konta, na którym tworzysz szablony
- [Wysyłanie wiadomości WhatsApp](/docs/guides/whatsapp/sending-whatsapp): pełny ładunek wysyłki
- [Tworzenie i przesyłanie szablonu WhatsApp](/learn/whatsapp/building-and-submitting-a-whatsapp-template): wideo, w którym tworzony jest szablon utility i karuzela marketingowa

## Related resources

- [What is a WhatsApp message template?](/explained/whatsapp/what-is-a-whatsapp-message-template) (answer)
- [WhatsApp templates](/products/whatsapp/templates) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=whatsapp-templates)