Sign inGet Started

Invia il tuo primo messaggio WhatsApp

Invia un messaggio WhatsApp al tuo telefono con Bird WhatsApp, poi rileggi il messaggio per confermarne la consegna. Gli invii avviati dall'azienda usano un template pre-approvato. Questa guida rapida invia dal catalogo di template gestiti di Bird (come bird_delivery_update o bird_otp), che usa un mittente WhatsApp condiviso gestito da Bird. Non devi prima collegare un WhatsApp Business Account né registrare un numero.

Prima di iniziare, assicurati che il wallet della tua organizzazione abbia fondi. Gli invii di template WhatsApp vengono addebitati sul wallet e Bird rifiuta con 402 WalletInsufficientBalance un invio che il saldo non può coprire. Metodi di pagamento e wallet spiega come ricaricarlo.

1. Crea una chiave API

Nella dashboard, vai a Platform tools > API keys e crea una chiave con lo scope whatsapp:write, che consente di inviare e leggere messaggi. Le chiavi sono legate a una regione e hanno la forma bk_us1_... o bk_eu1_.... La regione nel prefisso indica quale host API chiamare: https://us1.platform.bird.com o https://eu1.platform.bird.com.

La pagina API Keys nella dashboard di Bird, con l'elenco delle chiavi, il prefisso mascherato, gli scope e l'ora dell'ultimo utilizzo

La chiave completa viene mostrata una sola volta, al momento della creazione. Copiala in un posto sicuro, poi esportala per gli esempi cURL:

Esempio di codice
export BIRD_API_KEY="bk_us1_..."

2. Invia un messaggio con template

Invia al tuo telefono il template bird_delivery_update pre-approvato dal catalogo gestito di Bird, oppure usa bird_otp per inviare un codice di verifica monouso. I template gestiti iniziano con bird_ e vengono inviati da un numero Bird condiviso, quindi ometti from. Installa l'Bird SDK per il tuo linguaggio seguendo la relativa guida rapida SDK. Se usi la scheda Bird CLI, prima installala (curl -fsSL https://cli.bird.com/install.sh | sh) e autenticati con accesso in scrittura (bird auth login --scope whatsapp:write).

Nelle schede SDK, sostituisci la chiave API di esempio e sostituisci +15551234567 con il tuo numero di cellulare in formato E.164. La CLI usa il tuo login, mentre la scheda cURL usa BIRD_API_KEY.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_delivery_update",
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", name: "ref", text: "A1B2C3D4" },
          { type: "text", name: "date", text: "10 Jul 2026" },
        ],
      },
    ],
  },
});

console.log(msg.id, msg.status);

Se la tua chiave inizia con bk_eu1_, chiama invece https://eu1.platform.bird.com.

L'API risponde con 202 Accepted e il messaggio creato. Il suo id inizia con wam_ e il suo status è accepted: Bird ha accettato il messaggio e lo consegna in modo asincrono. Conserva l'id per il passaggio successivo.

3. Controlla lo stato di consegna

Recupera il messaggio tramite il suo ID wam_. Sostituisci WHATSAPP_MESSAGE_ID con l'id del passaggio 2 e, nelle schede SDK, sostituisci la chiave API di esempio con la tua:

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.get("WHATSAPP_MESSAGE_ID");

console.log(msg.id, msg.status);

Il campo status indica a che punto si trova il messaggio:

  • accepted: Bird ha preso in carico il messaggio e si prepara a consegnarlo a WhatsApp.
  • sent: WhatsApp ha accettato il messaggio e sent_at registra quando.
  • delivered: WhatsApp ha confermato la consegna al dispositivo del destinatario e delivered_at registra quando. Quando il destinatario legge il messaggio, viene impostato read_at, mentre status resta delivered.
  • failed o rejected: il messaggio non ha raggiunto il telefono. last_error indica il motivo e Eventi di stato dei messaggi elenca i codici di errore.

Interroga periodicamente il messaggio finché lo stato non è più accepted né sent, oppure iscriviti ai webhook WhatsApp per ricevere ogni cambio di stato di consegna e di lettura (whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed). I numeri condivisi gestiti da Bird sono solo in uscita e non inoltrano le risposte in entrata al tuo spazio di lavoro; per ricevere le risposte, collega un tuo numero. Ogni messaggio compare anche nella pagina Messages con la cronologia dei suoi eventi.

Risolvi un invio non riuscito

  • 402 WalletInsufficientBalance: il saldo del wallet non copre il messaggio. Ricarica il wallet, poi invia di nuovo.
  • 403 InsufficientScope: la chiave API non ha lo scope whatsapp. Modifica gli scope della chiave o crea una chiave con whatsapp:write.
  • 422 WhatsAppInvalidRecipient: il numero in to non è un numero di telefono E.164 valido. Controlla il + iniziale, il prefisso internazionale e le cifre dell'abbonato.

Passaggi successivi