Envoyer des SMS
Une seule API pour chaque texto que vous envoyez.
Envoyez des messages transactionnels et des notifications via Bird. Fournissez votre texte et votre expéditeur, ou utilisez un modèle ; inspectez l'encodage et le nombre de segments dans la réponse. Ajoutez une clé d'idempotence pour réessayer en toute sécurité et suivez la livraison via des webhooks signés.
Un message. Un résultat visible.
Exemple d'envoi
Explorez l'acceptation puis l'accusé de réception de l'opérateur. Cet exemple n'envoie pas de SMS ; la distribution ne prouve pas que le destinataire l'a lu.
Des équipes qui créent des logiciels de classe mondiale nous font confiance au quotidien
Découvrir plus de témoignages clientsTestez votre première intégration SMS.
Depuis le langage que vous utilisez déjà.
L'envoi est le cœur de l<hub>Bird SMS API</hub>. Lexemple ci-dessous montre la structure de la requête. Pour un test contrôlé, remplacez le destinataire par le numéro sandbox documenté +15005550006. Configurez un expéditeur US adapté et activez d'abord la destination, puis vérifiez les événements d'acceptation et de livraison avant d'envoyer à vos clients.
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 envoi SMS transmet le texte que vous fournissez. Pour la connexion et la vérification de compte, utilisez Bird Verify pour générer, expirer et vérifier des codes dans un flux de vérification.
Construisez sur un contrat d'envoi clair.
Préparez la requête et suivez le résultat.
- 01
Comptage des segments avant l'envoi.
Bird indique l'encodage calculé et le nombre de segments dans sa réponse. Utilisez le calculateur de segments pour inspecter un brouillon avant de le soumettre.
- 02
GSM-7 et Unicode, décidés à votre place.
Les caractères déterminent l'encodage. GSM-7 contient 160 unités dans un seul segment ; Unicode en contient 70. Les messages multiparts réservent de l'espace pour le réassemblage, et les emoji peuvent occuper plus d'une unité.
- 03
Le lot en un seul appel.
Soumettez jusqu'à 100 messages indépendants en un seul lot. La validation a lieu avant la mise en file d'attente ; chaque message accepté a ensuite son propre résultat.
- 04
Réessayez avec une clé d'idempotence.
Utilisez une clé d'idempotence par requête logique et réutilisez-la pour une tentative identique. La réponse API conservée peut être rejouée ; cela ne garantit pas une livraison unique par l'opérateur.
- 05
Événements de livraison pour votre application.
Abonnez-vous aux événements d'acceptation, d'envoi et de résultat terminal. Vérifiez les signatures, dédupliquez les tentatives de webhook et utilisez les accusés de lecture pour investiguer les observations manquantes ou retardées.
Faites avancer l'intégration avec un test contrôlé.
Faites correspondre vos champs de requête actuels, vos enregistrements d'expéditeur et votre gestion des événements avec Bird. Réconciliez les désinscriptions avant de migrer le trafic, puis comparez un test contrôlé avant de modifier le routage en production.
import twilio from "twilio";
const client = twilio(accountSid, authToken);
await client.messages.create({
from: "+14155550172",
to: "+15005550006",
body: "Your code is 123456.",
});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",
});Connaissez le nombre de segments avant la soumission.
GSM-7 contient 160 septets dans un seul segment ; UCS-2 en contient 70 unités de code. La capacité multipart est de 153 ou 67 respectivement. Les caractères étendus GSM-7 utilisent deux septets et les emoji peuvent utiliser deux unités de code. Bird renvoie l'encodage et les segments à l'acceptation ; le tarif applicable et les frais opérateur sont facturés séparément.
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 message ou une centaine, un seul appel.
Regroupez jusqu'à 100 messages indépendants, chacun avec son propre destinataire et texte. Une entrée invalide rejette la requête avant la mise en file d'attente. Après une réponse 202 réussie, le traitement et la livraison peuvent réussir ou échouer séparément pour chaque SMS. Réutilisez la requête et la clé d'idempotence pour réessayer dans la fenêtre de rétention documentée.
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`);Suivez l'acceptation jusqu'au résultat rapporté.
Une requête réussie renvoie 202 Accepted. La facturation et la soumission à l'opérateur ont lieu ensuite et peuvent encore échouer. Consommez les événements de livraison signés et inspectez l'enregistrement du message pour investiguer le résultat.
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 });
}Inspectez les échecs par leur motif rapporté. Les mots-clés STOP pris en charge et les désinscriptions opérateur créent des suppressions ; les autres échecs de livraison ne deviennent pas automatiquement une désinscription.
sms.acceptedAccepté par l'API et mis en file d'attente pour la transmission à l'opérateur.sms.sentSoumis au SMSC de l'opérateur de destination.sms.deliveredAccusé de réception reçu de l'opérateur (DLR).sms.failedUn échec terminal pour cette tentative SMS. Inspectez l'erreur rapportée et la chronologie du message.
Approfondissez dans la documentation.
Câblez des webhooks, rendez chaque envoi sûr à réessayer avec des clés d'idempotence, et lisez la référence des erreurs pour gérer chaque échec de la bonne façon.
Mettez-le en pratique.
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Questions avant de construire
Est-ce que je choisis l'expéditeur ?
Comment les réessais évitent-ils un texte en double ?
Accepté signifie-t-il livré ?
Un batch est-il la même chose qu'un broadcast ?
Le reste de la plateforme SMS
Une seule API, un seul jeu de clés. Explorez les autres capacités.
Construisez le flux de messagerie complet.
Connectez l'envoi SMS aux contrôles d'expéditeur, de destination et de livraison dont votre application a besoin. Préparez l'intégration avant d'envoyer à vos clients.