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 chiave completa viene mostrata una sola volta, al momento della creazione. Copiala in un posto sicuro, poi esportala per gli esempi cURL:
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);from bird import APIError, Bird
with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
try:
message = client.whatsapp.send(
to="+15551234567",
template="bird_delivery_update",
components=[
{
"type": "body",
"parameters": [
{"type": "text", "name": "ref", "text": "A1B2C3D4"},
{"type": "text", "name": "date", "text": "10 Jul 2026"},
],
}
],
)
print(message.id, message.status)
except APIError as err:
print("send failed:", err)package main
import (
"context"
"fmt"
"log"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+15551234567",
Template: "bird_delivery_update",
Components: []bird.WhatsAppMessageTemplateComponent{{
Type: "body",
Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
{Type: "text", Name: bird.String("ref"), Text: bird.String("A1B2C3D4")},
{Type: "text", Name: bird.String("date"), Text: bird.String("10 Jul 2026")},
},
}},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}<?php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';
use MessageBird\Bird;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponent;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponentParameter;
$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');
$message = $bird->whatsapp->send(
to: '+15551234567',
template: 'bird_delivery_update',
components: [
(new WhatsAppMessageTemplateComponent())
->setType('body')
->setParameters([
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('date')->setText('10 Jul 2026'),
]),
],
);
echo $message->getId(), ' ', $message->getStatus(), "\n";bird whatsapp send \
--components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"date","text":"10 Jul 2026","type":"text"}],"type":"body"}]' \
--template bird_delivery_update \
--to +15551234567curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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" }
]
}
]
}
}'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);from bird import APIError, Bird
with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
try:
message = client.whatsapp.get("WHATSAPP_MESSAGE_ID")
print(message.id, message.status)
except APIError as err:
print("read failed:", err)package main
import (
"context"
"fmt"
"log"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Get(context.Background(), "WHATSAPP_MESSAGE_ID")
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}<?php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';
use MessageBird\Bird;
$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');
$message = $bird->whatsapp->get('WHATSAPP_MESSAGE_ID');
echo $message->getId(), ' ', $message->getStatus(), "\n";bird whatsapp get WHATSAPP_MESSAGE_IDcurl https://us1.platform.bird.com/v1/whatsapp/messages/WHATSAPP_MESSAGE_ID \
-H "Authorization: Bearer $BIRD_API_KEY"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 esent_atregistra quando.delivered: WhatsApp ha confermato la consegna al dispositivo del destinatario edelivered_atregistra quando. Quando il destinatario legge il messaggio, viene impostatoread_at, mentrestatusrestadelivered.failedorejected: il messaggio non ha raggiunto il telefono.last_errorindica 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
402WalletInsufficientBalance: il saldo del wallet non copre il messaggio. Ricarica il wallet, poi invia di nuovo.403InsufficientScope: la chiave API non ha lo scopewhatsapp. Modifica gli scope della chiave o crea una chiave conwhatsapp:write.422WhatsAppInvalidRecipient: il numero intonon è un numero di telefono E.164 valido. Controlla il+iniziale, il prefisso internazionale e le cifre dell'abbonato.
Passaggi successivi
- Inviare messaggi WhatsApp: invia template e messaggi di servizio in formato libero entro la finestra di assistenza clienti di 24 ore.
- Template WhatsApp: sfoglia il catalogo gestito (
bird_otp,bird_delivery_updatee altri) oppure crea i tuoi template. - Collegare un numero di telefono: usa il tuo account WhatsApp Business e il tuo numero mittente, così il tuo spazio di lavoro può ricevere anche le risposte in entrata.
- Webhook WhatsApp: ricevi le conferme di consegna e di lettura (oltre ai messaggi in entrata, se usi un tuo numero collegato).
- Riferimento WhatsApp API: lo schema completo di richiesta e risposta.
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.