Szablony utility WhatsApp
Szablon utility nawiązuje do czegoś, co odbiorca już zrobił: zamówienia, płatności, rezerwacji, logowania. Katalog Bird zawiera osiem takich szablonów, w tym bird_signin_alert i bird_delivery_update. Kategorię slugu sprawdzaj na liście szablonów, a nie po nazwie: bird_signin_alert wygląda jak szablon authentication, ale nim nie jest, to utility.
Zanim wyślesz
Wybierz szablon z zarządzanego katalogu lub utwórz własny na połączonym koncie biznesowym.
Wysyłanie gotowych szablonów z katalogu Bird nie wymaga żadnej weryfikacji z Twojej strony, tak samo jak authentication. Tworzenie własnego szablonu utility też jej nie wymaga: w przeciwieństwie do authentication bramka weryfikacji biznesowej Meta nigdy nie dotyczy utility, więc możesz tworzyć i edytować szablony utility w niezweryfikowanym obszarze roboczym. Zobacz WhatsApp weryfikacja biznesowa, żeby sprawdzić, co weryfikacja odblokowuje gdzie indziej.
to może być numerem telefonu w formacie E.164 lub identyfikatorem użytkownika w zakresie biznesowym. Szablon utility nie zawiera przycisku OTP, więc nie wymaga odbiorcy podanego wyłącznie jako numer telefonu, jak ma to miejsce w authentication.
Każdy zarządzany szablon utility z katalogu jest zarejestrowany wyłącznie w en, z on_missing_language: fail. Żądanie języka, którego nie ma w katalogu, powoduje błąd wysyłki zamiast powrotu do angielskiego lub czegokolwiek innego.
Wysyłanie szablonu utility
POST /v1/whatsapp/messages z obiektem template wskazującym slug katalogu:
const msg = await bird.whatsapp.send({
to: "+16505551234",
template: {
slug: "bird_order_confirmation",
language: "en",
components: [
{
type: "body",
parameters: [
{ type: "text", name: "ref", text: "A1B2C3D4" },
{ type: "text", name: "amount", text: "USD 49.99" },
],
},
],
},
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
template="bird_order_confirmation",
language="en",
components=[
{
"type": "body",
"parameters": [
{"type": "text", "name": "ref", "text": "A1B2C3D4"},
{"type": "text", "name": "amount", "text": "USD 49.99"},
],
}
],
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
ref := "A1B2C3D4"
amount := "USD 49.99"
refName := "ref"
amountName := "amount"
components := []bird.WhatsAppMessageTemplateComponent{{
Type: "body",
Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
{Type: "text", Name: &refName, Text: &ref},
{Type: "text", Name: &amountName, Text: &amount},
},
}}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
Template: "bird_order_confirmation",
Language: "en",
Components: components,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$components = [
(new WhatsAppMessageTemplateComponent())
->setType('body')
->setParameters([
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('amount')->setText('USD 49.99'),
]),
];
$message = $bird->whatsapp->send(
to: '+16505551234',
template: 'bird_order_confirmation',
language: 'en',
components: $components,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"amount","text":"USD 49.99","type":"text"}],"type":"body"}]' \
--language en \
--template bird_order_confirmation \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"template": {
"components": [
{
"parameters": [
{
"name": "ref",
"text": "A1B2C3D4",
"type": "text"
},
{
"name": "amount",
"text": "USD 49.99",
"type": "text"
}
],
"type": "body"
}
],
"language": "en",
"slug": "bird_order_confirmation"
},
"to": "+16505551234"
}
}curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"template": {
"slug": "bird_order_confirmation",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"name": "ref",
"text": "A1B2C3D4"
},
{
"type": "text",
"name": "amount",
"text": "USD 49.99"
}
]
}
]
}
}'Tak jak przy każdym zarządzanym szablonie, pomiń from: Bird wybiera numer wysyłkowy na podstawie kategorii i regionu, a ustawienie go zwraca 422 E15018 WhatsAppSenderNotAllowed. Tworzenie własnego szablonu utility i wysyłanie go działa tak samo jak każda autorska wysyłka; zobacz Wysyłanie za pomocą szablonu, żeby poznać ogólny kontrakt.
Wypełnianie zmiennych
Parametry utility są nazwane, odwrotnie niż pojedynczy pozycyjny kod w authentication. Każdy parametr zawiera name, a kolejność nazwanych parametrów w tablicy nie ma znaczenia. Wyślij jeden wpis components dla każdego bloku, który faktycznie zawiera placeholder; body bez zmiennych w ogóle nie potrzebuje wpisu components.
Przycisk URL jest jedynym wyjątkiem: jego zmienna jest zawsze pozycyjna {{1}}, a wysyłka zawiera samą wartość, a nie pełny adres:
Przykład kodu
{ "type": "button", "parameters": [{ "type": "text", "text": "A-4192" }] }Wspólne zasady dotyczące komponentów, sub_type oraz sposobu, w jaki components wysyłki odpowiadają zadeklarowanym placeholderom szablonu, znajdziesz w Wysyłanie za pomocą szablonu i Komponenty i parametry.
Koszt
Szablon utility dostarczony w otwartym oknie obsługi klienta może kwalifikować się do bezpłatnej stawki Meta. Opłata wychodząca Bird jest naliczana podczas przetwarzania wiadomości, przed wysłaniem. Późniejszy callback dostarczenia lub odczytu określa, czy opłata Meta ma zastosowanie. Uwzględnij oba składniki przy szacowaniu łącznego kosztu.
Zobacz Koszt i rozliczenia, aby dowiedzieć się, kiedy wysyłka jest naliczana, oraz Cennik WhatsApp po stawki.
Na co uważać
- Meta może z własnej inicjatywy przekategoryzować szablon utility na marketing, a wiadomość dalej jest wysyłana po nowej, wyższej cenie. Firma, którą Meta już ostrzegła za błędną kategoryzację, od kwietnia 2025 nie dostaje żadnego wcześniejszego powiadomienia; zmiana następuje natychmiast. Nie umieszczaj w treści szablonu utility języka promocyjnego, ofert ani upselli, bo to właśnie wywołuje przeniesienie. Zobacz Wytyczne dotyczące szablonów, żeby sprawdzić, co jest odczytywane jako promocyjne.
- Nagłówek gif lub przycisk copy_code jest odrzucany poza kategorią marketing. Oba to komponenty dostępne wyłącznie w marketing; zadeklarowanie któregokolwiek z nich w szablonie utility kończy się błędem.
- Autorska wysyłka nie jest sprawdzana pod kątem liczby parametrów przed naliczeniem opłaty. Wyślij nieprawidłową liczbę parametrów we własnym szablonie, a wiadomość zostanie zaakceptowana i obciążona opłatą, po czym odrzucona przez Meta. Zarządzane wysyłki z katalogu nie mają tej luki.
- Nadawca na niewłaściwym WhatsApp Business Account jest odrzucany przed jakąkolwiek opłatą. from musi znajdować się na tym samym koncie co szablon; w przeciwnym razie wysyłka kończy się błędem 422 E15023 WhatsAppSenderWABAMismatch.
Następne kroki
- Szablony WhatsApp: przeglądanie katalogu i wspólny kontrakt wysyłki przez szablon
- Szablony authentication: jednorazowe kody weryfikacyjne i bramka weryfikacji przy tworzeniu szablonu
- Szablony marketing: wysyłki promocyjne i konto potrzebne do utworzenia szablonu
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Obejrzyj przewodnikConnecting WhatsApp to Bird: from buying a number to a live channelZrozum koncepcjęWhat is the 24-hour customer service window on WhatsApp?Użyj narzędziaWhatsApp message builderPoznaj możliwościWhatsApp
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy