Template WhatsApp

Gli invii WhatsApp avviati dall'azienda usano un template pre-approvato. Un template contiene testo fisso e variabili, quindi un invio fornisce solo valori come un codice OTP o un numero d'ordine.

Bird fornisce un catalogo gestito, ne registra i contenuti presso WhatsApp e lo invia dai numeri di Bird; i suoi slug iniziano con bird_. Uno spazio di lavoro che ha collegato un proprio numero può anche creare template sul proprio WhatsApp Business Account. La pagina Approved templates mostra tutti i template che lo spazio di lavoro può inviare e come viene visualizzato ciascuno.

Sfogliare i template nella dashboard

Apri Approved templates da WhatsApp > Approved templates. Your templates contiene i template creati da questo spazio di lavoro; All templates aggiunge il catalogo gestito da Bird. Cerca per nome o filtra per stato e categoria, e passa dalla griglia di schede alla vista elenco con l'interruttore accanto ai filtri.

Nella vista elenco, ogni riga mostra i campi necessari per scegliere e inviare un template:

Status: indica se il template è inviabile nel complesso. I template del catalogo gestito riportano active; un template tuo riporta lo stato della sua approvazione. Controlla l'elenco delle lingue per verificare che la lingua richiesta sia disponibile.
Name: l'etichetta visualizzata, con il slug del template sotto. Per l'invio usa il slug.
Languages: le lingue in cui il template è registrato, ad esempio inglese e olandese.
Category: authentication, utility o marketing. La categoria determina come WhatsApp tratta il messaggio, da quale numero Bird viene inviato un template gestito e, insieme al paese di destinazione, il prezzo.
WABA: Bird-managed per i template del catalogo. Un template di tua proprietà mostra il WhatsApp Business Account che lo contiene e viene inviato solo da un numero dello stesso account.
Updated: quando il template è stato modificato l'ultima volta.

Fai clic su una riga per aprire il dettaglio del template.

Cosa contiene un template

La vista di dettaglio mostra il corpo del messaggio, le variabili e i pulsanti in un'anteprima in stile WhatsApp.

Il dettaglio fornisce anche un esempio cURL per POST /v1/whatsapp/messages, che usa l'host regionale e i valori di esempio del template. Prima dell'invio, sostituisci la chiave API, il destinatario e i valori delle variabili.

L'esempio è il modo più rapido per vedere la struttura che un invio deve rispettare. Tramite API, lo stesso contenuto proviene dalla versione del template (Leggere il contenuto di un template).

Elencare i template tramite API

GET /v1/whatsapp/templates restituisce un catalogo con paginazione a cursore. La richiesta richiede l'accesso in lettura whatsapp_management. Usa HTTP o un metodo di richiesta diretta di 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"

Ogni voce identifica il template, la sua categoria e le lingue disponibili. Per il contenuto del messaggio, leggi separatamente la versione attiva.

Esempio di codice

{
  "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"
}

La risposta di esempio abbrevia gli elenchi di lingue bird_otp.

I campi da cui dipende un invio:

slug: l'identificativo usato in un invio. Gli slug dei template gestiti iniziano con bird_, un prefisso riservato a loro.
waba: il WhatsApp Business Account che detiene le lingue del template presso Meta, a cui deve appartenere il numero mittente. È assente nei template gestiti, perché è Bird a gestirne l'account.
available_languages: le lingue che si possono inviare. Una lingua in pausa, disattivata, archiviata o limitata esce da questo elenco.
on_missing_language: cosa succede quando la lingua richiesta non è disponibile. I template WhatsApp gestiti da Bird usano fail, che rifiuta l'invio invece di sostituire un'altra lingua.

Stato e stato della lingua

I template gestiti da Bird riportano status: active. languages.<tag>.status riporta lo stato assegnato da WhatsApp a una singola lingua, ad esempio approved, paused o disabled.

Un template attivo può comunque avere una lingua non disponibile. Usa available_languages per stabilire se una lingua si può inviare.

Leggere il contenuto di un template

Il contenuto del messaggio appartiene a una lingua della versione attiva. Leggi live_version_id dal template, poi richiedi la lingua che ti serve:

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"

Il riferimento al template accetta un ID slug o wat_. GET …/versions/{version_id}/languages elenca le lingue della versione senza il loro contenuto.

Esempio di codice

{
  "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"
}

Un invio compila questi segnaposto per nome. example_parameters identifica ciascuno di essi. In questo esempio, il campo parameters dell'invio accetta le chiavi ref e amount. Le chiavi di un template posizionale sono i suoi numeri, ad esempio 1, con due eccezioni: il codice di un template di autenticazione usa code e il suffisso numerato di un pulsante url usa button_url. I pulsanti con parametri hanno un proprio example_parameters.

Il campo category della lingua è la categoria Meta usata per il prezzo. Può differire dalla categoria registrata del template se Meta riclassifica la lingua.

L'elenco variables della versione riassume ogni segnaposto con chiave, tipo, flag di obbligatorietà e vincolo. I segnaposto con nome usano il proprio nome come chiave. I segnaposto posizionali usano il proprio numero, tranne il codice di autenticazione (code) e il suffisso di un pulsante url (button_url). Il campo parameters di un invio accetta queste chiavi.

Inviare con un template

Indica il template nell'oggetto template dell'invio e compila le sue variabili tramite parameters. Per il payload completo, consulta Inviare messaggi 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" }
    }
  }'

Inviare in base alla categoria

Ogni template ha una delle tre categorie di Meta. La categoria determina cosa devi fare perché un invio vada a buon fine e quanto costa. Per creare o copiare un tuo template di autenticazione serve un'azienda verificata, ma per inviarlo no: il bird_otp gestito da Bird si trova sul WhatsApp Business Account di Bird e invia senza alcuna tua verifica. I template di marketing vengono sempre inviati da un tuo WhatsApp Business Account, tramite una seconda API di Meta verso cui Bird instrada automaticamente. I template di utilità sono quelli con meno prerequisiti tra i tre.

Template di autenticazione: codici monouso, il pulsante di copia del codice e il requisito di verifica per crearne uno
Template di utilità: aggiornamenti sugli ordini, promemoria di appuntamenti e avvisi sull'account
Template di marketing: invii promozionali, il business account necessario e l'obbligo di offrire la disiscrizione

Passaggi successivi

Inviare messaggi WhatsApp: il payload di invio completo in cui si inserisce l'oggetto template
Linee guida per i template WhatsApp: le regole in base a cui Meta esamina un template
Template di autenticazione: codici di verifica monouso e il requisito di verifica aziendale per crearne uno
Prezzi di WhatsApp: come la categoria e la destinazione determinano il prezzo

Continua con la documentazione, le guide e gli esempi per questo argomento.

Prova l'esercitazione e ottieni un brief di implementazione

Risorse correlate