Template di autenticazione WhatsApp

Un template di autenticazione recapita un codice di verifica monouso. Il testo lo fornisce Meta quando crei il template. Quando lo invii, passa il codice come parametro del corpo.

Prima di inviare

Scegli se usare un template gestito da Bird o creare un template sul tuo account aziendale.

Per inviare i template del catalogo predefinito di Bird, bird_otp e bird_otp_authifly, non serve alcuna verifica da parte tua. Questi template si trovano sugli account WhatsApp Business di Bird, e il percorso di invio gestito non controlla mai lo stato di verifica della tua azienda.

Quando l'account aziendale collegato riporta not_verified, Bird rifiuta la creazione o la duplicazione di template di autenticazione con 412 E15043 WhatsAppTemplateBusinessNotVerified. Controlla l'account collegato e il suo ultimo stato sincronizzato. Consulta Verifica aziendale WhatsApp per il processo di verifica e la gestione degli stati.

Questo requisito non riguarda la creazione di template di utilità e di marketing: puoi continuare a crearli e modificarli indipendentemente dallo stato di verifica.

Crea i template nella dashboard, con bird CLI o tramite il server MCP. Consulta Creare template di autenticazione per il flusso completo.

Inviare un codice di verifica

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

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

msg = client.whatsapp.send(
    to="+14155550100",
    template="bird_otp",
    language="en",
    parameters={"code": "481920"},
)
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:         "+14155550100",
		Template:   "bird_otp",
		Language:   "en",
		Parameters: map[string]any{"code": "481920"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

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

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

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

Questa categoria prevede quattro regole specifiche:

Ometti from. Un template gestito da Bird sceglie il proprio mittente in base alla categoria e alla regione, quindi impostare from restituisce 422 E15018 WhatsAppSenderNotAllowed. È l'opposto di un invio in formato libero, che richiede from: tienilo presente se arrivi dalle pagine sui messaggi interattivi.
to deve essere un numero di telefono E.164. Un template di autenticazione non può essere inviato a un ID utente associato all'azienda; in quel caso ottieni 422 E15014 WhatsAppRecipientNotSupportedForTemplate.
Il codice va in parameters.code. Compila il segnaposto del corpo e il pulsante di copia del codice. Un invio components accetta invece esattamente un parametro posizionale del corpo, cioè il codice. Se non passi alcun parametro, o se assegni un nome al parametro, ottieni 422 E15003 WhatsAppTemplateParameterMismatch.
Non serve una finestra di assistenza clienti. Gli invii di template non dipendono dalla finestra, ed è proprio per questo che esiste un template per il codice di verifica: deve raggiungere anche chi non ti ha mai scritto.

Leggi le lingue disponibili per bird_otp o bird_otp_authifly dal catalogo dei template. Se la lingua richiesta non è disponibile, l'invio non riesce e non viene sostituita con un'altra lingua.

Il pulsante di copia del codice

Meta scrive autonomamente il corpo di un template di autenticazione, come testo predefinito con un unico segnaposto per il codice, quindi fornisci dei flag anziché del testo. Un invio parameters compila il pulsante a partire da code. In un invio components il componente pulsante è facoltativo: se non lo includi, Bird lo aggiunge per te, con lo stesso codice del corpo. Puoi anche fornirlo tu:

Esempio di codice

{ "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }

In entrambi i casi a WhatsApp arriva esattamente un pulsante, quello di copia del codice: toccandolo, il codice viene copiato negli appunti. Bird supporta solo copy_code; gli altri due comportamenti dei pulsanti che Meta documenta per i template di autenticazione, la compilazione automatica con un tocco e senza tocchi, non sono disponibili su Bird.

Il pulsante si crea con la stessa struttura anche quando crei il template: un solo pulsante otp, e il template non accetta altri tipi di pulsante. Invece di scrivere il testo, fornisci add_security_recommendation (un valore booleano mostrato nel corpo) e code_expiration_minutes (da 1 a 90, mostrato nel piè di pagina).

Cosa consente Meta in un template di autenticazione

Meta stabilisce la struttura di un template di autenticazione e ne revisiona il contenuto: niente URL, contenuti multimediali o emoji in nessuna parte del template, e un limite di 15 caratteri per il parametro del codice. La categoria cambia anche il modo in cui WhatsApp consegna il messaggio, che arriva solo al dispositivo principale del destinatario. Consulta Linee guida per i template per i dettagli completi su struttura fissa, limiti di caratteri e processo di revisione.

Costi

Il prezzo dipende dalla categoria e dalla destinazione. Consulta Tariffe WhatsApp authentication-international per sapere come l'invio verso un paese diverso dalla tua sede principale può modificarlo, e Costi e fatturazione per sapere quando un invio viene addebitato. Le tariffe si trovano in Prezzi di WhatsApp.

Punti di attenzione

I template predefiniti di Bird non vengono recapitati in nove paesi. bird_otp e bird_otp_authifly vengono inviati dai WhatsApp Business Account di Bird, e questi account non recapitano messaggi di autenticazione in Egitto, India, Indonesia, Malesia, Nigeria, Pakistan, Arabia Saudita, Sudafrica ed Emirati Arabi Uniti. Un invio di questo tipo viene rifiutato con 422 E15063 WhatsAppDestinationRestricted prima di qualsiasi addebito. Un template creato sul tuo account e inviato dal tuo numero raggiunge normalmente questi paesi. Anche Verify li raggiunge, spostando autonomamente il codice di verifica su un altro canale.
Un invio di un template creato da te richiede from, che deve trovarsi sullo stesso WhatsApp Business Account del template. Un mittente su un account diverso viene rifiutato con 422 E15023 WhatsAppSenderWABAMismatch prima di qualsiasi addebito.
Puoi inviare solo una lingua la cui versione è approvata e attiva. Una lingua in bozza, in attesa, rifiutata o sospesa non è inviabile.
Meta può ricategorizzare un template di propria iniziativa. Non è possibile rifiutarlo, e la modifica cambia le regole di prezzo e di recapito legate alla categoria.
La categoria del template e quella della sua lingua possono non coincidere. Consulta Template WhatsApp per sapere come il percorso di invio risolve questa differenza.
Un template di autenticazione importato non può essere duplicato. Bird non può ricavare dal testo generato da WhatsApp le impostazioni da cui si costruisce un nuovo template; in questo caso ottieni 422 E15024 WhatsAppTemplateContentNotDuplicable. Crea invece un nuovo template con la propria raccomandazione di sicurezza e la propria scadenza del codice.

Passaggi successivi

Template WhatsApp: consultazione del catalogo e contratto comune per l'invio tramite template
Template di utilità: aggiornamenti sugli ordini, promemoria degli appuntamenti e avvisi sull'account
Verifica dell'azienda su WhatsApp: come funziona la verifica e cos'altro sblocca

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

Prova l'esercitazione e ottieni un brief di implementazione

Risorse correlate