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 spiega come ricaricare.

1. Crea una chiave API

Nella dashboard, vai su Platform tools > Chiavi API 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

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. 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. Se risulta già abilitato, passa al passaggio 3.

Da un terminale, la Bird 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:

Esempio di codice

bird sms destinations update --destination US=true

Gli agenti connessi al server MCP 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.

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

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);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.sms.send(
            to="+14155550100",
            template="bird_otp_verification",
            parameters={"code": "493021"},
        )
        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.Sms.Send(context.Background(), bird.SmsSendParams{
		To:         "+14155550100",
		Template:   "bird_otp_verification",
		Parameters: map[string]any{"code": "493021"},
	})
	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->sms->send(
    to: '+14155550100',
    template: 'bird_otp_verification',
    parameters: ['code' => '493021'],
);

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird sms send \
  --parameters '{"code":"493021"}' \
  --template bird_otp_verification \
  --to +14155550100

curl -X POST https://us1.platform.bird.com/v1/sms/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "template": {
      "slug": "bird_otp_verification",
      "parameters": { "code": "493021" }
    }
  }'

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.

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);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.sms.get("SMS_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)
	}

	var msg bird.SMSMessage
	if err := client.Get(context.Background(), "/v1/sms/messages/SMS_MESSAGE_ID", &msg); 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->sms->get('SMS_MESSAGE_ID');

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird sms get SMS_MESSAGE_ID

curl https://us1.platform.bird.com/v1/sms/messages/SMS_MESSAGE_ID \
  -H "Authorization: Bearer $BIRD_API_KEY"

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 spiega ciascuno di essi.

Esegui il polling finché lo stato non esce da accepted e sent, oppure iscriviti agli eventi SMS per ricevere ogni cambiamento tramite webhook. Ogni messaggio appare anche nella pagina 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, 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: invia il tuo testo con un mittente e una categoria, in batch e con ripetizioni sicure.
Sender ID SMS: scegli un mittente per ogni paese e registralo dove il paese lo richiede.
Template SMS: il catalogo dei template integrati e le relative variabili.
Eventi SMS: i tipi di evento e la consegna tramite webhook per ogni cambio di stato.
Riferimento SMS API: lo schema completo di richiesta e risposta.

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

Ottieni un brief di implementazione