Envoyer votre premier SMS

Envoyez un message texte vers votre propre téléphone avec Bird SMS, puis relisez le message pour vérifier s'il a été livré. Ce guide de démarrage rapide utilise un modèle intégré, qui fournit le texte, la catégorie et un expéditeur partagé que Bird sélectionne en fonction de la destination. Vous n'avez pas besoin d'un identifiant d'expéditeur ni d'un enregistrement d'expéditeur pour cela.

Avant de commencer, vérifiez que le portefeuille de votre organisation dispose de fonds. Les envois SMS puisent dans le portefeuille, et Bird refuse un envoi que le solde ne peut pas couvrir avec 402 WalletInsufficientBalance. Méthodes de paiement et portefeuille explique comment l'alimenter.

1. Créer une clé API

Dans le tableau de bord, accédez à Platform tools > Clés API et créez une clé avec le scope sms:write, qui couvre l'envoi et la lecture des messages. Les clés sont liées à une région et ressemblent à bk_us1_... ou bk_eu1_.... La région dans le préfixe vous indique quel hôte API appeler : https://us1.platform.bird.com ou https://eu1.platform.bird.com.

La page des clés API dans le tableau de bord Bird, listant les clés avec leur préfixe masqué, leurs scopes et leur dernière utilisation

La clé complète est affichée une seule fois, au moment de la création. Copiez-la dans un endroit sûr, puis exportez-la pour les exemples cURL :

Exemple de code

export BIRD_API_KEY="bk_us1_..."

2. Activer le pays de destination

Bird n'envoie de SMS qu'aux pays activés pour votre espace de travail. Un envoi vers tout autre pays échoue avec 422 SMSDestinationNotEnabled. Activez le pays de votre numéro de téléphone sous SMS > Destinations. S'il apparaît déjà comme activé, passez à l'étape 3.

Depuis un terminal, la commande Bird CLI effectue la même modification. Transmettez le code ISO à deux lettres du pays, par exemple US pour les États-Unis. Si votre identifiant CLI n'a pas accès aux paramètres SMS, la commande affiche la commande bird auth login qui l'ajoute :

Exemple de code

bird sms destinations update --destination US=true

Les agents connectés au serveur MCP utilisent l'outil sms_destinations_update. L'API publique ne propose pas d'opération pour les destinations. Un changement peut prendre jusqu'à une minute avant de s'appliquer aux envois.

3. Envoyer le message

Envoyez le modèle intégré bird_otp_verification à votre téléphone. Il s'affiche sous la forme "493021 is your verification code. Do not share it." avec la valeur code que vous transmettez. Installez le Bird SDK pour votre langage en suivant son quickstart SDK.

Dans les onglets SDK, remplacez la clé API d'exemple, et remplacez +14155550100 par votre numéro de mobile au format E.164. L'onglet CLI utilise votre identifiant de connexion, et l'onglet cURL utilise 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" }
    }
  }'

Si votre clé commence par bk_eu1_, appelez https://eu1.platform.bird.com à la place.

L'API répond avec 202 Accepted et le message. Son id commence par sms_, et son status est accepted : Bird a le message et le livre de manière asynchrone. Conservez le id pour l'étape suivante. Le message arrive depuis l'expéditeur partagé que Bird a sélectionné pour votre pays.

4. Vérifier le statut de livraison

Récupérez le message par son ID. Une lecture juste après l'envoi peut renvoyer 404 tant que le message n'est pas visible sur le point de lecture, ce qui se produit peu après le 202. Relisez-le un instant plus tard. Remplacez SMS_MESSAGE_ID par le id de l'étape 3, et la clé API d'exemple dans les onglets SDK par la vôtre. Le SDK Go n'a pas de méthode typée pour lire un message SMS ; l'onglet Go appelle donc le chemin API via la méthode de requête client.Get du 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"

Le champ status indique où en est le message :

accepted : Bird a le message et ne l'a pas encore transmis à un opérateur.
sent : l'opérateur a le message, et sent_at indique quand Bird l'a transmis.
delivered : l'opérateur a confirmé la livraison, et delivered_at indique à quel moment.
undelivered, failed, rejected ou expired : le message n'a pas atteint le téléphone. last_error donne la raison, et Erreurs de livraison explique chacune d'entre elles.

Interrogez jusqu'à ce que le statut quitte accepted et sent, ou abonnez-vous aux événements SMS pour recevoir chaque changement par webhook. Chaque message apparaît aussi sur la page Messages avec sa chronologie d'événements.

Corriger un envoi échoué

422 SMSDestinationNotEnabled : le pays du destinataire n'est pas activé pour votre espace de travail. Activez-le comme à l'étape 2, attendez jusqu'à une minute, puis renvoyez le message.
402 WalletInsufficientBalance : le portefeuille ne peut pas couvrir le message. Rechargez le portefeuille, puis renvoyez le message.
403 InsufficientScope : la clé API ne possède pas le scope sms. Modifiez les scopes de la clé ou créez une clé avec sms:write.

Étapes suivantes

Envoyer des SMS : envoyez votre propre texte avec un expéditeur et une catégorie, par lots, et avec des nouvelles tentatives sûres.
Identifiants d'expéditeur SMS : choisissez un expéditeur pour chaque pays et enregistrez-le là où le pays l'exige.
Modèles SMS : le catalogue de modèles intégrés et ses variables.
Événements SMS : les types d'événements et la livraison par webhook pour chaque changement de statut.
Référence SMS API : le schéma complet de requête et de réponse.

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Obtenir un guide d'implémentation