Szablony WhatsApp

Wiadomości WhatsApp inicjowane przez firmę korzystają z wcześniej zatwierdzonego szablonu. Szablon zawiera stały tekst i zmienne, więc przy wysyłce podajesz tylko wartości, takie jak kod OTP lub numer zamówienia.

Bird udostępnia zarządzany katalog, rejestruje jego zawartość w WhatsApp i wysyła go z własnych numerów Bird; slugi tych szablonów zaczynają się od bird_. Obszar roboczy, który podłączył własny numer, może też tworzyć szablony na własnym koncie WhatsApp Business Account. Strona Approved templates pokazuje każdy szablon, który obszar roboczy może wysłać, oraz sposób jego wyświetlania.

Przeglądanie szablonów w panelu

Otwórz Approved templates w WhatsApp > Approved templates. Your templates zawiera szablony utworzone w tym obszarze roboczym; All templates dodaje katalog zarządzany przez Bird. Wyszukuj po nazwie lub filtruj według statusu i kategorii, a między widokiem kart a widokiem listy przełączaj się przełącznikiem obok filtrów.

W widoku listy każdy wiersz pokazuje pola potrzebne do wybrania i wysłania szablonu:

Status: czy szablon można ogólnie wysyłać. Szablony z zarządzanego katalogu mają status active; własny szablon pokazuje stan swojego zatwierdzenia. Sprawdź listę języków, aby potwierdzić, że wymagany język jest dostępny.
Name: wyświetlana etykieta, a pod nią slug szablonu. Wysyłaj, używając slug.
Languages: języki, w których szablon jest zarejestrowany, na przykład angielski i niderlandzki.
Category: authentication, utility lub marketing. Kategoria określa, jak WhatsApp traktuje wiadomość, z którego numeru Bird wysyłany jest szablon zarządzany, a razem z krajem docelowym także cenę.
WABA: Bird-managed w przypadku szablonów z katalogu. Własny szablon pokazuje konto WhatsApp Business Account, na którym się znajduje, i jest wysyłany wyłącznie z numeru należącego do tego samego konta.
Updated: kiedy szablon został ostatnio zmieniony.

Kliknij wiersz, aby otworzyć szczegóły szablonu.

Co zawiera szablon

Widok szczegółów renderuje treść wiadomości, zmienne i przyciski w podglądzie w stylu WhatsApp.

Widok szczegółów zawiera też przykład cURL dla POST /v1/whatsapp/messages, który korzysta z hosta regionalnego i przykładowych wartości szablonu. Przed wysłaniem zastąp klucz API, odbiorcę i wartości zmiennych.

Przykład najszybciej pokazuje strukturę, do której musi pasować wysyłka. Przez API ta sama treść pochodzi z wersji szablonu (Odczytywanie treści szablonu).

Pobieranie listy szablonów przez API

GET /v1/whatsapp/templates zwraca katalog z paginacją opartą na kursorze. Żądanie wymaga uprawnień do odczytu whatsapp_management. Użyj HTTP lub metody wysyłania surowych żądań z SDK.

type Templates = { data: Array<{ slug: string; status: string }> };

const templates = await bird.request<Templates>({
  method: "GET",
  path: "/v1/whatsapp/templates",
});

templates = client.get("/v1/whatsapp/templates")

var out struct {
	Data []struct {
		Slug   string `json:"slug"`
		Status string `json:"status"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/whatsapp/templates", &out); err != nil {
	log.Fatal(err)
}

$templates = $bird->get('/v1/whatsapp/templates');

curl https://us1.platform.bird.com/v1/whatsapp/templates \
  -H "Authorization: Bearer $BIRD_API_KEY"

Każdy wpis identyfikuje szablon, jego kategorię i dostępne języki. Aby uzyskać treść wiadomości, odczytaj osobno aktywną wersję.

Przykład kodu

{
  "available_languages": ["en", "es", "pt-BR", "..."],
  "category": "authentication",
  "default_language": "en",
  "description": "One-time passcode",
  "id": "wat_01ky4x8e4genzb7way45txfkm1",
  "languages": {
    "en": { "status": "approved" },
    "es": { "status": "approved" },
    "pt-BR": { "status": "approved" },
    "...": "..."
  },
  "name": "bird_otp",
  "on_missing_language": "fail",
  "scope": "system",
  "slug": "bird_otp",
  "status": "active"
}

Przykładowa odpowiedź skraca listy języków bird_otp.

Pola, od których zależy wysyłka:

slug: identyfikator używany w wysyłce. Slugi szablonów zarządzanych zaczynają się od bird_, prefiksu zarezerwowanego dla nich.
waba: konto WhatsApp Business Account, na którym znajdują się wersje językowe szablonu w Meta, i zarazem konto, do którego musi należeć numer nadawcy. Pole nie występuje w szablonie zarządzanym, ponieważ jego kontem zarządza Bird.
available_languages: języki, w których można wysyłać. Język wstrzymany, wyłączony, zarchiwizowany lub ograniczony znika z tej listy.
on_missing_language: co się dzieje, gdy żądany język jest niedostępny. Szablony WhatsApp zarządzane przez Bird używają fail, co odrzuca wysyłkę zamiast podstawiać inny język.

Status i status języka

Szablony zarządzane przez Bird zgłaszają status: active. languages.<tag>.status zgłasza stan nadany przez WhatsApp dla jednego języka, na przykład approved, paused lub disabled.

Aktywny szablon może mimo to mieć niedostępny język. O tym, czy można wysłać wiadomość w danym języku, decyduj na podstawie available_languages.

Odczytywanie treści szablonu

Treść wiadomości należy do języka w aktywnej wersji. Odczytaj live_version_id z szablonu, a następnie pobierz potrzebny język:

const language = await bird.request({
  method: "GET",
  path: "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
});

language = client.get(
    "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en"
)

var language map[string]any
if err := client.Get(context.Background(),
	"/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
	&language); err != nil {
	log.Fatal(err)
}

$language = $bird->get('/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en');

curl https://us1.platform.bird.com/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en \
  -H "Authorization: Bearer $BIRD_API_KEY"

Odwołanie do szablonu przyjmuje identyfikator slug lub wat_. GET …/versions/{version_id}/languages wymienia języki wersji bez ich treści.

Przykład kodu

{
  "category": "utility",
  "components": [
    {
      "example_parameters": [
        { "name": "ref", "text": "A1B2C3D4", "type": "text" },
        { "name": "amount", "text": "USD 49.99", "type": "text" }
      ],
      "text": "Your order {{ref}} has been confirmed for a total of {{amount}}. Thanks for shopping with us.",
      "type": "body"
    }
  ],
  "language": "en",
  "status": "approved"
}

Wysyłka wypełnia te symbole zastępcze według nazwy. Każdy z nich identyfikuje example_parameters. W tym przykładzie parameters wysyłki przyjmuje klucze ref i amount. W szablonie pozycyjnym kluczami są numery, na przykład 1, z dwoma wyjątkami: kod szablonu uwierzytelniającego przyjmuje code, a numerowany sufiks przycisku url przyjmuje button_url. Przyciski z parametrami mają własne example_parameters.

Pole category języka to kategoria Meta używana do wyceny. Może się różnić od zarejestrowanej kategorii szablonu, jeśli Meta zmieni klasyfikację tego języka.

Lista variables wersji opisuje każdy symbol zastępczy: jego klucz, typ, flagę wymagalności i ograniczenie. Nazwane symbole zastępcze używają swoich nazw jako kluczy. Symbole pozycyjne używają swojego numeru, z wyjątkiem kodu uwierzytelniającego (code) i sufiksu przycisku url (button_url). Pole parameters wysyłki przyjmuje te klucze.

Wysyłanie z użyciem szablonu

Wskaż szablon w obiekcie template wysyłki i uzupełnij jego zmienne przez parameters. Pełny ładunek opisuje strona Wysyłanie wiadomości WhatsApp:

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

msg = client.whatsapp.send(
    to="+15551234567",
    template="bird_otp",
    language="en",
    parameters={"code": "123456"},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:         "+15551234567",
	Template:   "bird_otp",
	Language:   "en",
	Parameters: map[string]any{"code": "123456"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    parameters: ['code' => '123456'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"code":"123456"}' \
  --template bird_otp \
  --to +15551234567

curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "parameters": { "code": "481920" }
    }
  }'

Wysyłanie według kategorii

Każdy szablon ma jedną z trzech kategorii Meta. Kategoria określa, co musisz zrobić, aby wysyłka się powiodła, oraz ile kosztuje. Tworzenie lub kopiowanie własnego szablonu uwierzytelniającego wymaga zweryfikowanej firmy, ale jego wysyłanie już nie: zarządzany bird_otp od Bird znajduje się na własnym koncie WhatsApp Business Account firmy Bird i jest wysyłany bez Twojej weryfikacji. Szablony marketingowe zawsze są wysyłane z Twojego własnego konta WhatsApp Business Account, przez drugi API Meta, do którego Bird kieruje je automatycznie. Szablony użytkowe mają najmniej wymagań wstępnych z całej trójki.

Szablony uwierzytelniające: jednorazowe kody weryfikacyjne, przycisk kopiowania kodu i wymóg weryfikacji przy tworzeniu takiego szablonu
Szablony użytkowe: aktualizacje zamówień, przypomnienia o wizytach i powiadomienia o koncie
Szablony marketingowe: wysyłki promocyjne, wymagane konto firmowe i oczekiwana możliwość rezygnacji

Dalsze kroki

Wysyłanie wiadomości WhatsApp: pełny ładunek wysyłki, w którym umieszcza się obiekt template
Wytyczne dotyczące szablonów WhatsApp: zasady, według których Meta sprawdza szablon
Szablony uwierzytelniania: jednorazowe kody weryfikacyjne oraz wymóg weryfikacji firmy przy tworzeniu takiego szablonu
Cennik WhatsApp: jak kategoria i kraj docelowy wpływają na cenę

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.

Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy

Powiązane zasoby