--- title: "Invia il tuo primo messaggio WhatsApp" description: "Crea una chiave Bird API, invia al tuo telefono un messaggio con un template WhatsApp pre-approvato senza collegare un numero e controllane lo stato di consegna." canonical: "https://bird.com/it-it/documentazione/get-started/send-your-first-whatsapp" --- # 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](/docs/knowledge-base/billing/payment-methods-wallet) spiega come ricaricarlo. ## 1. Crea una chiave API Nella dashboard, vai a **Platform tools** > [**API keys**](https://bird.com/dashboard/w/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](/images/docs/dashboard-api-keys.png) La chiave completa viene mostrata **una sola volta**, al momento della creazione. Copiala in un posto sicuro, poi esportala per gli esempi cURL: ```bash 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](/docs/get-started/quickstarts). Se usi la scheda [Bird CLI](/docs/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](https://en.wikipedia.org/wiki/E.164). La CLI usa il tuo login, mentre la scheda cURL usa `BIRD_API_KEY`. **TypeScript** ```typescript 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); ``` Examples: [TypeScript](/it-it/documentazione/get-started/send-your-first-whatsapp.ts.md) · [Python](/it-it/documentazione/get-started/send-your-first-whatsapp.py.md) · [Go](/it-it/documentazione/get-started/send-your-first-whatsapp.go.md) · [PHP](/it-it/documentazione/get-started/send-your-first-whatsapp.php.md) · [CLI](/it-it/documentazione/get-started/send-your-first-whatsapp.cli.md) · [MCP](/it-it/documentazione/get-started/send-your-first-whatsapp.mcp.md) · [cURL](/it-it/documentazione/get-started/send-your-first-whatsapp.curl.md) 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: **TypeScript** ```typescript 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); ``` Examples: [TypeScript](/it-it/documentazione/get-started/send-your-first-whatsapp.ts.md) · [Python](/it-it/documentazione/get-started/send-your-first-whatsapp.py.md) · [Go](/it-it/documentazione/get-started/send-your-first-whatsapp.go.md) · [PHP](/it-it/documentazione/get-started/send-your-first-whatsapp.php.md) · [CLI](/it-it/documentazione/get-started/send-your-first-whatsapp.cli.md) · [cURL](/it-it/documentazione/get-started/send-your-first-whatsapp.curl.md) 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](/docs/guides/whatsapp/events/message-status) elenca i codici di errore. Interroga periodicamente il messaggio finché lo stato non è più `accepted` né `sent`, oppure iscriviti ai [webhook WhatsApp](/docs/guides/whatsapp/webhooks) 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](/docs/guides/whatsapp/numbers/connect). Ogni messaggio compare anche nella pagina [**Messages**](https://bird.com/dashboard/w/whatsapp/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 - [Inviare messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp): invia template e messaggi di servizio in formato libero entro la finestra di assistenza clienti di 24 ore. - [Template WhatsApp](/docs/guides/whatsapp/templates): sfoglia il catalogo gestito (`bird_otp`, `bird_delivery_update` e altri) oppure [crea i tuoi template](/docs/guides/whatsapp/authoring-templates). - [Collegare un numero di telefono](/docs/guides/whatsapp/numbers/connect): 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](/docs/guides/whatsapp/webhooks): ricevi le conferme di consegna e di lettura (oltre ai messaggi in entrata, se usi un tuo numero collegato). - [Riferimento WhatsApp API](/docs/api/reference/create-whatsapp-message): lo schema completo di richiesta e risposta. ## Related resources - [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video) - [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer) - [WhatsApp message builder](/tools/whatsapp-message-builder) (tool) - [Connect WhatsApp](/whatsapp-api) (product) [Get an implementation brief](/learn/workspace?topic=whatsapp-connect)