Un'unica API per ogni
messaggio che invii.

Invia messaggi transazionali e notifiche tramite Bird. Fornisci il testo e il mittente oppure usa un template; controlla la codifica e il conteggio dei segmenti nella risposta. Aggiungi una chiave di idempotenza per riprovare in sicurezza e segui la consegna attraverso webhook firmati.

Inizia Contatta il team commerciale

FNote operative

Il tuo ordine #4821 è pronto per il ritiro.

Stato202 Accepted

CodificaGSM-7

Segmenti1

Esplora l'accettazione e la successiva ricevuta dall'operatore. Questo esempio non invia un SMS; la consegna non implica che qualcuno lo abbia letto.

Testa la tua prima integrazione SMS.

Dal linguaggio che già usi.

L'invio è il nucleo dell<hub>Bird SMS API</hub>. Lesempio qui sotto mostra la struttura della richiesta. Per un test controllato, sostituisci il destinatario con il numero sandbox documentato +15005550006. Configura un mittente US adatto e abilita la destinazione, poi verifica gli eventi di accettazione e consegna prima di inviare ai clienti.

const msg = await bird.sms.send({
  from: "+15557654321",
  to: "+14155550100",
  text: "Your verification code is 123456.",
  category: "authentication",
});
console.log(msg.id, msg.status);

Un invio SMS consegna il testo che fornisci. Per login e verifica dell'account, usa Bird Verify per generare, far scadere e controllare i codici come parte di un flusso di verifica.

Costruisci su un contratto di invio chiaro.

Prepara la richiesta e segui il risultato.

01
Conteggio dei segmenti prima dell'invio.
Bird restituisce la codifica calcolata e il conteggio dei segmenti nella risposta. Usa il calcolatore di segmenti per ispezionare una bozza prima di inviarla.
02
GSM-7 e Unicode, decisi per te.
I caratteri determinano la codifica. GSM-7 contiene 160 unità in un singolo segmento; Unicode ne contiene 70. I messaggi multipart riservano spazio per il riassemblaggio e gli emoji possono occupare più di un'unità.
03
Batch in un'unica chiamata.
Invia fino a 100 messaggi indipendenti in un unico batch. La validazione avviene prima dell'accodamento; ogni messaggio accettato ha poi un esito proprio.
04
Riprova con una chiave di idempotenza.
Usa una chiave di idempotenza per ogni richiesta logica e riutilizzala per un retry identico. La risposta API conservata può essere riprodotta; questo non garantisce la consegna esattamente una volta da parte del carrier.
05
Eventi di consegna per la tua applicazione.
Sottoscrivi gli eventi di accettazione, invio ed esito terminale. Verifica le firme, deduplica i retry dei webhook e usa le conferme di lettura per indagare su osservazioni mancanti o ritardate.

Procedi con l'integrazione tramite un test controllato.

Mappa i campi della richiesta attuale, le registrazioni del mittente e la gestione degli eventi su Bird. Riconcilia gli opt-out prima di spostare il traffico, poi confronta un test controllato prima di cambiare il routing di produzione.

twilio.ts

Twilio

import twilio from "twilio";

const client = twilio(accountSid, authToken);

await client.messages.create({
  from: "+14155550172",
  to:   "+15005550006",
  body: "Your code is 123456.",
});

bird.ts

Bird

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

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

await bird.sms.send({
  from:     "+14155550172",
  to:       "+15005550006",
  text:     "Your code is 123456.",
  category: "authentication",
});

Conosci il conteggio dei segmenti prima dell'invio.

GSM-7 contiene 160 septets in un singolo segmento; UCS-2 ne contiene 70 code units. La capacità multipart è rispettivamente 153 o 67. I caratteri estesi GSM-7 usano due septets e gli emoji possono usare due code units. Bird restituisce codifica e segmenti all'accettazione; la tariffa applicabile e qualsiasi costo del carrier vengono addebitati separatamente.

segments.ts

202 · 1 segment

const { data, error } = await bird.sms.send({
  from:     "Bird",
  to:       "+31612345678",
  text:     "Your code is 123456.",
  category: "authentication",
}).safe();
if (error) throw error;

console.log(data.segments);
// → { characters: 20, count: 1, encoding: "GSM_7BIT" }

Un messaggio o un centinaio, un'unica chiamata.

Raggruppa fino a 100 messaggi indipendenti in un batch, ciascuno con destinatario e testo propri. Un input non valido rifiuta la richiesta prima dell'accodamento. Dopo una risposta 202 riuscita, l'elaborazione e la consegna possono avere esito positivo o negativo separatamente per ogni SMS. Riutilizza la richiesta e la chiave di idempotenza quando riprovi entro la finestra di conservazione documentata.

reminders.ts

202 · batch

const { data: batch, error } = await bird.sms
  .sendBatch(
    users.map((u) => ({
      from: "Bird",
      to:   u.phone,
      text: `Hi ${u.name}, your appointment is tomorrow at ${u.time}.`,
    })),
    { idempotencyKey: `reminders-${runId}` },
  )
  .safe();

if (error) throw error;
console.log(`queued ${batch.data.length} messages`);

Segui l'accettazione fino all'esito riportato.

Una richiesta riuscita restituisce 202 Accepted. L'addebito e l'invio al carrier avvengono dopo e possono ancora fallire. Consuma gli eventi di consegna firmati e ispeziona il record del messaggio quando indaghi sull'esito.

app/api/webhooks/bird/route.ts

signed

import { bird } from "@/lib/bird";

export async function POST(req: Request) {
  const event = bird.webhooks.unwrap(
    await req.text(),
    Object.fromEntries(req.headers),
  );

  switch (event.type) {
    case "sms.delivered":
      await markDelivered(event.data.sms_id);
      break;
    case "sms.failed":
      await flag(event.data.to, event.data.error?.description);
      break;
  }

  return new Response(null, { status: 204 });
}

Ispeziona i fallimenti in base alla causa riportata. Le keyword STOP supportate e gli opt-out del carrier creano soppressioni; altri fallimenti di consegna non diventano automaticamente un opt-out.

sms.acceptedAccettato dall'API e messo in coda per la consegna al carrier.
sms.sentSottoposto all'SMSC del carrier di destinazione.
sms.deliveredRicevuta di consegna ricevuta dal carrier (DLR).
sms.failedUn fallimento terminale per questo tentativo SMS. Ispeziona l'errore riportato e la timeline del messaggio.

Approfondisci nella documentazione.

Configura i webhook, rendi ogni invio sicuro da ritentare con le idempotency key e leggi il riferimento agli errori così gestisci ogni fallimento nel modo giusto.

Domande prima di iniziare

Scelgo io il mittente?

Per un invio con testo libero, specifica un mittente che il tuo spazio di lavoro può usare nella destinazione e la categoria di messaggio appropriata. Un invio con template di sistema risolve categoria e mittente dal template.

Come evitano i tentativi ripetuti un messaggio duplicato?

Fornisci una chiave di idempotenza e riutilizzala per riprovare la stessa richiesta. Un invio senza quella chiave può essere trattato come un nuovo messaggio.

Accettato significa consegnato?

No. Una risposta 202 significa che l'API ha accettato la richiesta. Segui il record del messaggio e gli eventi firmati per l'esito riportato dall'operatore. Una ricevuta di consegna non stabilisce che il destinatario abbia letto il messaggio.

Un batch è la stessa cosa di un broadcast?

Un batch contiene fino a 100 messaggi indipendenti, ciascuno con il proprio destinatario e corpo. Un broadcast è una campagna per un pubblico con contenuto condiviso e un ciclo di invio gestito. Scegli il flusso di lavoro adatto alla tua esigenza.

Il resto della piattaforma SMS

Un'unica API, un unico set di chiavi. Esplora le altre funzionalità.

NumeriLong code, short code, toll-free e alpha sender ID.BidirezionaleSMS in entrata e risposte conversazionali come webhook firmati con HMAC.ConformitàRegistrazione A2P 10DLC, keyword di opt-out e regole per il sender ID.RoutingControlli di destinazione, consegna al carrier ed evidenza di recapito.AnalisiEsiti di consegna, cause di fallimento e latenza dalle ricevute del carrier.Panoramica dell'API SMSL'API SMS completa: invio, numeri, bidirezionale, conformità, routing e analisi.Libreria di risorse SMSTrova guide, risposte e strumenti per il tuo prossimo passo.

Scala senza
perdere il controllo.

Organizza i team in spazi di lavoro, controlla l'accesso alle API e traccia le modifiche tramite log di audit.

HarborOrganization

WorkspacesProductionSandbox

Delivery agent

API key · Customer operations team

Active

PermissionsAccess

EmailRead & write

SMSRead & write

ALAlex Lee AdminPermissions updated

Audit log

Production

Workspace: Production
Resource: Delivery agent
WhatsApp: ReadRead & write

Succeeded

Explore Enterprise

Inizia con SMS.
Costruisci su più canali con Bird.