---
title: "Invia il tuo primo SMS"
description: "Crea una chiave Bird API, abilita un paese di destinazione, invia un template predefinito SMS al tuo telefono e verifica lo stato di consegna."
canonical: "https://bird.com/it-it/documentazione/get-started/send-your-first-sms"
---

# Invia il tuo primo SMS

Invia un messaggio di testo al tuo telefono con Bird SMS, poi rileggi il messaggio per verificare se è stato consegnato. Questa guida rapida usa un template predefinito, che fornisce il testo, la categoria e un mittente condiviso che Bird seleziona per la destinazione. Non servono un sender ID né una registrazione del mittente.

Prima di iniziare, assicurati che il wallet della tua organizzazione abbia fondi. Gli invii SMS prelevano dal wallet, e Bird rifiuta un invio non coperto dal saldo con `402` `WalletInsufficientBalance`. [Metodi di pagamento e wallet](/docs/knowledge-base/billing/payment-methods-wallet) spiega come ricaricare.

## 1. Crea una chiave API

Nella dashboard, vai su **Platform tools** > [**Chiavi API**](https://bird.com/dashboard/w/api-keys) e crea una chiave con lo scope `sms:write`, che copre l'invio e la lettura dei messaggi. Le chiavi sono limitate a una regione e hanno il formato `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 Chiavi API nella dashboard Bird, con l'elenco delle chiavi, il prefisso mascherato, gli scope e l'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. Abilita il paese di destinazione

Bird invia SMS solo verso i paesi abilitati per il tuo spazio di lavoro. Un invio verso qualsiasi altro paese fallisce con `422` `SMSDestinationNotEnabled`. Abilita il paese del tuo numero di telefono in [**SMS** > **Destinations**](https://bird.com/dashboard/w/sms/destinations). Se risulta già abilitato, passa al passaggio 3.

Da un terminale, la [Bird CLI](/docs/cli) esegue la stessa modifica. Passa il codice ISO a due lettere del paese, ad esempio `US` per gli Stati Uniti. Se il tuo login CLI non ha accesso alle impostazioni SMS, il comando stampa il comando `bird auth login` per aggiungerlo:

```bash
bird sms destinations update --destination US=true
```

Gli agenti connessi al [server MCP](/docs/ai/mcp-server) usano il tool `sms_destinations_update`. L'API pubblica non ha un'operazione per le destinazioni. Una modifica può impiegare fino a un minuto per applicarsi agli invii.

## 3. Invia il messaggio

Invia il template `bird_otp_verification` predefinito al tuo telefono. Viene visualizzato come **"493021 is your verification code. Do not share it."** con il valore `code` che passi. Installa l'SDK di Bird per il tuo linguaggio seguendo il suo [quickstart SDK](/docs/get-started/quickstarts).

Nelle tab SDK, sostituisci la chiave API di esempio e sostituisci `+14155550100` con il tuo numero di cellulare in formato [E.164](https://en.wikipedia.org/wiki/E.164). La tab CLI usa il tuo login, e la tab cURL usa `BIRD_API_KEY`.

**TypeScript**

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

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

const msg = await bird.sms.send({
  to: "+14155550100",
  template: { slug: "bird_otp_verification", parameters: { code: "493021" } },
});

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

Examples: [TypeScript](/it-it/documentazione/get-started/send-your-first-sms.ts.md) · [Python](/it-it/documentazione/get-started/send-your-first-sms.py.md) · [Go](/it-it/documentazione/get-started/send-your-first-sms.go.md) · [PHP](/it-it/documentazione/get-started/send-your-first-sms.php.md) · [CLI](/it-it/documentazione/get-started/send-your-first-sms.cli.md) · [MCP](/it-it/documentazione/get-started/send-your-first-sms.mcp.md) · [cURL](/it-it/documentazione/get-started/send-your-first-sms.curl.md)

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

API risponde con `202 Accepted` e il messaggio. Il suo `id` inizia con `sms_` e il suo `status` è `accepted`: Bird ha il messaggio e lo consegna in modo asincrono. Conserva l'`id` per il passaggio successivo. Il messaggio arriva dal mittente condiviso che Bird ha selezionato per il tuo paese.

## 4. Controlla lo stato di consegna

Recupera il messaggio tramite il suo ID. Una lettura subito dopo l'invio può restituire `404` finché il messaggio non diventa visibile sull'endpoint di lettura, cosa che avviene poco dopo il `202`. Riprova dopo qualche istante. Sostituisci `SMS_MESSAGE_ID` con il `id` del passaggio 3 e la chiave API di esempio nelle schede SDK con la tua. L'SDK Go non ha un metodo tipizzato per leggere un messaggio SMS, quindi la scheda Go chiama il percorso API attraverso il metodo di richiesta `client.Get` del SDK.

**TypeScript**

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

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

const msg = await bird.sms.get("SMS_MESSAGE_ID");

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

Examples: [TypeScript](/it-it/documentazione/get-started/send-your-first-sms.ts.md) · [Python](/it-it/documentazione/get-started/send-your-first-sms.py.md) · [Go](/it-it/documentazione/get-started/send-your-first-sms.go.md) · [PHP](/it-it/documentazione/get-started/send-your-first-sms.php.md) · [CLI](/it-it/documentazione/get-started/send-your-first-sms.cli.md) · [cURL](/it-it/documentazione/get-started/send-your-first-sms.curl.md)

Il campo `status` indica dove si trova il messaggio:

- `accepted`: Bird ha il messaggio e non lo ha ancora consegnato a un operatore.
- `sent`: l'operatore ha il messaggio, e `sent_at` registra quando Bird lo ha consegnato.
- `delivered`: l'operatore ha confermato la consegna e `delivered_at` registra quando.
- `undelivered`, `failed`, `rejected` o `expired`: il messaggio non ha raggiunto il telefono. `last_error` indica il motivo e [Delivery errors](/docs/guides/sms/delivery-errors) spiega ciascuno di essi.

Esegui il polling finché lo stato non esce da `accepted` e `sent`, oppure iscriviti agli [eventi SMS](/docs/guides/sms/events) per ricevere ogni cambiamento tramite webhook. Ogni messaggio appare anche nella pagina [**Messages**](https://bird.com/dashboard/w/sms/messages) con la sua cronologia degli eventi.

## Risolvere un invio non riuscito

- **`422` `SMSDestinationNotEnabled`**: il paese del destinatario non è abilitato per il tuo spazio di lavoro. Abilitalo come nel [passaggio 2](#2-abilita-il-paese-di-destinazione), attendi fino a un minuto e invia di nuovo.
- **`402` `WalletInsufficientBalance`**: il wallet non può coprire il messaggio. Ricarica il wallet e invia di nuovo.
- **`403` `InsufficientScope`**: la chiave API non ha lo scope `sms`. Modifica gli scope della chiave o crea una chiave con `sms:write`.

## Passaggi successivi

- [Invio di SMS](/docs/guides/sms/sending-sms): invia il tuo testo con un mittente e una categoria, in batch e con ripetizioni sicure.
- [Sender ID SMS](/docs/guides/sms/senders): scegli un mittente per ogni paese e registralo dove il paese lo richiede.
- [Template SMS](/docs/guides/sms/templates): il catalogo dei template integrati e le relative variabili.
- [Eventi SMS](/docs/guides/sms/events): i tipi di evento e la consegna tramite webhook per ogni cambio di stato.
- [Riferimento SMS API](/docs/api/reference/create-sms-message): lo schema completo di richiesta e risposta.

## Related resources

- [Sending your first SMS](/learn/sms/sending-your-first-sms) (video)
- [One-way and two-way SMS](/explained/sms/what-is-the-difference-between-one-way-and-two-way-sms) (answer)
- [Two-way SMS](/sms-api/features/two-way) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=sms-replies)