Template di utilità per WhatsApp

Un template di utilità dà seguito a qualcosa che il destinatario ha già fatto: un ordine, un pagamento, una prenotazione, un accesso. Il catalogo di Bird ne offre otto, tra cui bird_signin_alert e bird_delivery_update. Ricava la categoria di uno slug dall'elenco dei template e non dal suo nome: bird_signin_alert sembra un template di autenticazione ma non lo è, è di utilità.

Prima dell'invio

Scegli un template gestito dal catalogo oppure crea un template di utilità sul tuo account aziendale collegato.

Per inviare i template del catalogo di Bird non serve alcuna verifica da parte tua, come per l'autenticazione. Nemmeno per creare un tuo template di utilità serve una verifica: a differenza dell'autenticazione, il requisito di verifica aziendale di Meta non si applica mai ai template di utilità, quindi puoi crearli e modificarli in uno spazio di lavoro non verificato. Consulta Verifica aziendale di WhatsApp per sapere cosa sblocca la verifica in altri ambiti.

to può essere un numero di telefono E.164 o un ID utente limitato all'azienda. Un template di utilità non contiene un pulsante OTP, quindi non richiede un destinatario identificato solo dal numero di telefono, come invece avviene per l'autenticazione.

Ogni template di utilità gestito del catalogo è registrato solo in en, con on_missing_language: fail. Se richiedi una lingua non presente nel catalogo, l'invio non riesce, senza ripiegare sull'inglese o su un'altra lingua.

Inviare un template di utilità

POST /v1/whatsapp/messages con un oggetto template che indica uno slug del catalogo:

const msg = await bird.whatsapp.send({
  to: "+16505551234",
  template: {
    slug: "bird_order_confirmation",
    language: "en",
    parameters: { ref: "A1B2C3D4", amount: "USD 49.99" },
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+16505551234",
    template="bird_order_confirmation",
    language="en",
    parameters={"ref": "A1B2C3D4", "amount": "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)
	}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:         "+16505551234",
		Template:   "bird_order_confirmation",
		Language:   "en",
		Parameters: map[string]any{"ref": "A1B2C3D4", "amount": "USD 49.99"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $bird->whatsapp->send(
    to: '+16505551234',
    template: 'bird_order_confirmation',
    language: 'en',
    parameters: ['ref' => 'A1B2C3D4', 'amount' => 'USD 49.99'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"amount":"USD 49.99","ref":"A1B2C3D4"}' \
  --template 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",
        "parameters": {
          "ref": "A1B2C3D4",
          "amount": "USD 49.99"
        }
      }
    }'

Come per qualsiasi template gestito, ometti from: Bird sceglie il numero mittente in base alla categoria e alla regione, e se lo imposti ricevi 422 E15018 WhatsAppSenderNotAllowed. Creare e inviare un tuo template di utilità funziona come qualsiasi altro invio di un template creato da te; consulta Invio con un template per il contratto generale.

Compilare le variabili

Le variabili dei template utility hanno un nome, quindi ognuna è una chiave a sé in parameters, come ref e amount. Un pulsante URL con un suffisso numerato {{1}} usa invece la chiave button_url. Un suffisso con nome usa il proprio nome. L'invio contiene solo il valore, non l'indirizzo completo:

{ "parameters": { "ref": "A1B2C3D4", "button_url": "A-4192" } }

Un invio components indica invece ogni parametro del corpo, e l'ordine di un parametro con nome nell'array non ha alcun significato. Per le regole comuni su componenti, sub_type e sulla corrispondenza tra i components di un invio e i segnaposto dichiarati nel template, consulta Inviare con un template e Componenti e parametri.

Costi

Un template utility consegnato all'interno di una finestra di assistenza clienti aperta rientra nella tariffa gratuita di Meta fino al 30 settembre 2026; dal 1° ottobre 2026 Meta lo addebita come qualsiasi altro template utility (modifiche ai prezzi di ottobre 2026). La tariffa in uscita di Bird viene addebitata durante l'elaborazione del messaggio, prima dell'invio a Meta. È il successivo callback di consegna o di lettura a stabilire se si applica una tariffa di Meta. Per stimare il totale, considera entrambe le voci.

Consulta Costi e fatturazione per sapere quando viene addebitato un invio e Prezzi di WhatsApp per le tariffe.

Punti di attenzione

• Meta può ricategorizzare di propria iniziativa un template utility come marketing, e il messaggio continua a essere inviato al nuovo prezzo, più alto. Dall'aprile 2025, un'azienda già avvisata da Meta per una categorizzazione errata non riceve alcun preavviso: la modifica è immediata. Escludi dal testo di un template utility linguaggio promozionale, offerte o proposte di upsell, perché sono questi elementi a causare la ricategorizzazione. Consulta Linee guida per i template per sapere cosa viene considerato promozionale.
• Un'intestazione gif o un pulsante copy_code vengono rifiutati al di fuori del marketing. Entrambi sono componenti riservati al marketing; dichiararne uno in un template utility causa un errore.
• Prima dell'addebito, un invio components con un template creato da te non viene controllato sul numero di parametri. Se invii un numero errato di parametri in components su un tuo template, il messaggio viene accettato e addebitato, poi rifiutato da Meta. Un invio parameters a cui manca una chiave obbligatoria viene rifiutato prima di qualsiasi addebito, e gli invii con template gestiti del catalogo non presentano questo problema.
• Un mittente sul Business Account WhatsApp sbagliato viene rifiutato prima di qualsiasi addebito. from deve trovarsi sullo stesso account del template; altrimenti l'invio non riesce 422 E15023 WhatsAppSenderWABAMismatch.

Passaggi successivi

• Template WhatsApp: come consultare il catalogo e il contratto comune per l'invio tramite template
• Template di autenticazione: codici di verifica monouso e il requisito di verifica per crearne uno
• Template di marketing: invii promozionali e l'account necessario per crearne uno