Documentazione
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Creare template WhatsApp

Il catalogo gestito di Bird copre i casi più comuni, ma un template scritto con le tue parole deve essere creato su un WhatsApp Business Account che hai connesso. Questa pagina spiega come crearne uno; Template WhatsApp spiega come sfogliare e inviare quelli già esistenti.
Tre aspetti definiscono l'intero flusso:
  • Un template contiene versioni, e una versione contiene una voce per lingua. Ciò che viene effettivamente inviato è una lingua di una versione, non il template.
  • Il contenuto viene scritto in una bozza. Un template ha al massimo una bozza aperta, e nulla al suo interno raggiunge WhatsApp finché non la invii.
  • L'approvazione arriva per lingua. Una lingua può essere approvata mentre un'altra sulla stessa versione viene rifiutata.

Prima di iniziare

Ti serve un numero tuo connesso, che è ciò che dà al tuo spazio di lavoro un WhatsApp Business Account su cui creare template. Un account che non hai connesso viene rifiutato, così come la modifica di uno dei template bird_ integrati di Bird: questi risiedono sull'account di Bird, quindi duplicane uno sul tuo.
Creare un template di authentication richiede inoltre un'azienda verificata; utility e marketing no. Consulta Authentication templates per questo requisito.
Crea un template nella dashboard sotto WhatsApp > Templates, con la CLI di bird, oppure tramite il server MCP. La dashboard segue gli stessi passaggi descritti in questa pagina; gli esempi più avanti usano la CLI.

Nella dashboard

New template offre due strade. Start with a template apre la galleria, il percorso più rapido: scegli un template che dice già quasi quello che ti serve, incluso uno di Bird, e la copia viene creata sul tuo account come bozza aperta.
La galleria dei template nella dashboard Bird: una griglia di schede template, ciascuna con l'anteprima del messaggio e l'indicazione di nome, slug, stato, categoria e lingue, accanto a filtri per origine del template, categoria e lingua
Start from scratch chiede la categoria, un nome e una lingua predefinita prima di aprire l'editor. Un template marketing chiede anche un tipo di messaggio. Il nome diventa lo slug, e lo slug e la categoria sono le due scelte che non puoi modificare in seguito.
Il passaggio Create a new template nella dashboard Bird: riquadri delle categorie Marketing, Utility e Authentication sopra un campo Name e un selettore Default language, con un pulsante Create template
L'editor scrive una lingua alla volta: la barra laterale elenca le lingue del template con lo stato di revisione di ciascuna, la colonna centrale contiene il contenuto e l'anteprima su telefono mostra il messaggio con i valori di esempio sostituiti.
L'editor di template nella dashboard Bird per il template utility Order update: English contrassegnato come Approved accanto a Dutch nella barra laterale delle lingue, e un'anteprima su telefono del messaggio renderizzato con i pulsanti Track order e Contact support
L'editor cambia forma in base al template. Un carousel aggiunge una scheda per ogni card accanto al messaggio, e ogni card deve ripetere la struttura della card 1: lo stesso formato di intestazione e gli stessi pulsanti nello stesso ordine.
L'editor di template nella dashboard Bird per un template carousel marketing: schede Message, Card 1, Card 2 e Card 3 sopra il corpo del messaggio, con una sezione Variable samples sotto, accanto a un'anteprima su telefono che mostra il messaggio seguito da card con immagini scorrevoli, ciascuna con un pulsante Show me
Un template di authentication non ha un editor del messaggio. WhatsApp scrive il testo, quindi l'editor offre solo le due impostazioni da cui lo genera: Add security recommendation e Code expiration (minutes).
L'editor di template nella dashboard Bird per un template di authentication: un pannello Authentication settings con un toggle Add security recommendation e un campo Code expiration (minutes), accanto a un'anteprima su telefono del messaggio con il codice di verifica scritto da WhatsApp, con il pulsante Copy code
Save as draft salva il lavoro senza contattare WhatsApp. Submit for review congela la versione e la invia a WhatsApp. Il submit della CLI, descritto più avanti, esegue lo stesso congelamento.

Due modi per iniziare

Duplicare un template esistente

Un duplicato porta il contenuto dell'originale come bozza aperta e chiama WhatsApp zero volte, quindi nulla viene inviato finché non lo decidi tu. Due cose su una copia vale la pena sapere prima di crearne una:
  • La categoria viene ereditata e non può essere cambiata. Se ti serve una categoria diversa, crea da zero.
  • Puoi ridurre le lingue, mai aggiungerne. Un template del catalogo con 70 lingue non deve per forza diventare 70 lingue tue: scegli il sottoinsieme che manterrai effettivamente. Richiedere una lingua che l'originale non contiene viene rifiutato con E15060, e la risposta indica quali non corrispondevano. Aggiungi altre lingue alla copia in seguito.
Il sottoinsieme di lingue è un array, quindi va nel corpo della richiesta anziché in un flag:
Esempio di codice
bird whatsapp templates duplicate bird_order_confirmation --body-file copy.json
Esempio di codice
{
  "waba": "102290129340398",
  "slug": "acme_order_update",
  "include_languages": ["en", "es-ES"],
  "default_language": "en"
}
Ometti include_languages e la copia prende tutte le lingue dell'originale. Ometti default_language e la copia mantiene la lingua predefinita dell'originale se il tuo sottoinsieme la include ancora; altrimenti prende la prima delle lingue della copia per tag canonico, che non è necessariamente la prima che hai indicato, quindi impostala esplicitamente se è importante.

Creare da zero

Creare un template richiede uno slug, un account, una categoria e una lingua predefinita:
Esempio di codice
bird whatsapp templates create order_update \
  --waba 102290129340398 \
  --category utility \
  --default-language en
Lo slug e la categoria sono entrambi permanenti. WhatsApp deriva il proprio nome del template dallo slug, e né esso né la categoria possono essere cambiati in seguito; uno diverso significa un nuovo template. Il prefisso bird_ è riservato al catalogo di Bird. La categoria che scegli non è necessariamente quella a cui viene tariffato l'invio: Meta applica la propria categoria per lingua e può spostarla, e il prezzo segue quella di Meta.

Scrivere ogni lingua

Apri la bozza, poi scrivi una lingua alla volta:
Esempio di codice
bird whatsapp templates versions create order_update
bird whatsapp templates versions languages set order_update <version-id> en --body-file en.json
Aprire una bozza è sicuro da ripetere: un template ne ha una sola, quindi questa chiamata restituisce quella aperta anziché crearne una seconda. Il template la riporta anche come draft_version_id.
Scrivere una lingua ne sostituisce tutto il contenuto, senza unirlo a quello esistente. Il file porta il contenuto completo components di quella lingua ogni volta, quindi leggi prima la lingua e riscrivila per intero; inviare solo il blocco che hai modificato cancella il resto.
Ogni variabile ha bisogno di un valore di esempio. WhatsApp revisiona il messaggio compilato e non il template, quindi un blocco con segnaposto e senza parametri di esempio viene rifiutato all'invio, non al momento della scrittura.

Controlla, poi invia

Valida prima di congelare qualsiasi cosa. Un invio di sola validazione esegue ogni controllo su tutte le lingue e segnala ogni problema in un unico passaggio, senza inviare nulla a WhatsApp:
Esempio di codice
bird whatsapp templates versions submit order_update <version-id> --validate-only
Leggi valid e errors; ogni errore indica la lingua, il campo e il codice con cui un invio reale fallirebbe. Poi invia per davvero rimuovendo il flag. Questo congela la bozza come versione immutabile e risponde con 202. Usa una chiave di idempotenza diversa per il controllo e per l'invio, perché riutilizzare la stessa chiave con un corpo modificato viene rifiutato.
Solo le lingue il cui contenuto differisce dalla copia approvata vengono inviate a WhatsApp. Una lingua che corrisponde già porta con sé la propria approvazione, quindi un invio in cui nulla è cambiato si conclude immediatamente senza nulla da interrogare. Nessuna bozza sostitutiva si apre in seguito: il prossimo ciclo di modifiche inizia creando di nuovo una bozza.
Un esito positivo della sola validazione non predice la decisione di WhatsApp. WhatsApp non offre alcun modo per chiederlo in anticipo, quindi può comunque rifiutare contenuti che hanno superato tutti i controlli locali.

Monitorare la revisione

L'approvazione arriva in un secondo momento e per lingua. Lo stato pending_version_id del template resta impostato finché almeno una lingua è ancora in attesa di esito, e l'elenco per lingua riporta ogni verdetto:
  • approved invia. available_languages sul template è esattamente ciò che un invio può risolvere in questo momento.
  • rejected, submit_failed, paused richiedono una modifica su una nuova bozza. WhatsApp accetta una modifica a una lingua in pausa, e il reinvio è ciò che la sblocca.
  • disabled, limit_exceeded, in_appeal rifiutano subito qualsiasi modifica; richiedono solo una rilettura finché WhatsApp non cambia lo stato della lingua.
Lo stato status del template è un aggregato: active significa che almeno una lingua è inviabile, non tutte.

Inviare ciò che hai creato

Un template creato da te viene inviato attraverso lo stesso endpoint di qualsiasi altro, con una differenza rispetto al catalogo di Bird: devi specificare from, e deve essere un numero sullo stesso WhatsApp Business Account del template. Un mittente su un account diverso viene rifiutato con 422 E15023 prima che qualsiasi cosa venga addebitata.
Un template può richiedere una lingua del destinatario tramite language_source_required. In caso contrario, on_missing_language controlla se la risoluzione fallisce o può usare una lingua base approvata o default_language. Testa la policy configurata rispetto ai available_languages approvati del template; una lingua predefinita non approvata non è inviabile. I valori che fornisci devono riempire i segnaposto della lingua che viene effettivamente risolta, quindi leggi il contenuto di quella lingua prima dell'invio. Consulta Inviare messaggi WhatsApp per il payload completo.

Aspetti da tenere d'occhio

  • La versione più recente non è quella che invia. Un elenco di versioni è ordinato dalla più recente e include eventuali bozze aperte, quindi la prima riga è spesso una bozza o una versione ancora in revisione. Il template indica la versione in servizio come live_version_id; un template senza versione live non può essere inviato.
  • Una lingua in revisione rifiuta una scrittura. WhatsApp la blocca fino al termine della revisione, quindi una modifica durante pending fallisce anziché accodarsi.
  • Una riga dell'elenco non contiene contenuto. L'elenco dei template li trova e ne mostra lo stato del ciclo di vita; leggere cosa dice effettivamente un template richiede una lettura della versione.
  • L'eliminazione è irreversibile. Scartare una lingua, eliminare una bozza ed eliminare un template richiedono tutti una conferma esplicita, e l'eliminazione di un template interrompe ogni invio con quello slug.

Passaggi successivi

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoWhat is a WhatsApp message template?Esplora la funzionalitàWhatsApp templatesSegui il percorso di apprendimentoBuild your first integration
Prova l'esercitazione e ottieni un brief di implementazione