Erste SMS senden

Senden Sie mit Bird SMS eine Textnachricht an Ihr eigenes Telefon und lesen Sie die Nachricht anschließend aus, um zu prüfen, ob sie zugestellt wurde. Dieser Schnellstart verwendet eine integrierte Vorlage, die den Text, die Kategorie und einen gemeinsamen Absender liefert, den Bird für das Zielland auswählt. Sie benötigen dafür weder eine Absender-ID noch eine Absenderregistrierung.

Stellen Sie vor dem Start sicher, dass das Wallet Ihrer Organisation Guthaben hat. SMS-Sendungen belasten das Wallet, und Bird lehnt eine Sendung, die das Guthaben nicht decken kann, mit 402 WalletInsufficientBalance ab. Zahlungsmethoden und Wallet beschreibt das Aufladen.

1. API-Schlüssel erstellen

Gehen Sie im Dashboard zu Platform tools > API-Schlüssel und erstellen Sie einen Schlüssel mit dem Scope sms:write, der das Senden und Auslesen von Nachrichten abdeckt. Schlüssel sind auf eine Region beschränkt und sehen aus wie bk_us1_... oder bk_eu1_.... Die Region im Präfix gibt an, welchen API-Host Sie aufrufen: https://us1.platform.bird.com oder https://eu1.platform.bird.com.

Die API-Schlüsselseite im Bird-Dashboard mit maskiertem Präfix, Scopes und letzter Verwendung

Der vollständige Schlüssel wird einmalig bei der Erstellung angezeigt. Kopieren Sie ihn an einen sicheren Ort und exportieren Sie ihn dann für die cURL-Beispiele:

Codebeispiel

export BIRD_API_KEY="bk_us1_..."

2. Zielland aktivieren

Bird sendet SMS nur in die Länder, die für Ihren Workspace aktiviert sind. Ein Versand in ein anderes Land schlägt mit 422 SMSDestinationNotEnabled fehl. Aktivieren Sie das Land Ihrer Telefonnummer unter SMS > Destinations. Falls es bereits als aktiviert angezeigt wird, fahren Sie mit Schritt 3 fort.

Über ein Terminal nimmt die Bird CLI dieselbe Änderung vor. Übergeben Sie den zweibuchstabigen ISO-Code des Landes, zum Beispiel US für die Vereinigten Staaten. Falls Ihr CLI-Login keinen Zugriff auf SMS-Einstellungen hat, gibt der Befehl den bird auth login-Befehl aus, der den Zugriff hinzufügt:

Codebeispiel

bird sms destinations update --destination US=true

Agenten, die mit dem MCP-Server verbunden sind, verwenden das sms_destinations_update-Tool. Die öffentliche API bietet keine Operation für Zielländer. Eine Änderung kann bis zu einer Minute brauchen, bis sie auf Sendungen angewendet wird.

3. Nachricht senden

Senden Sie das integrierte bird_otp_verification-Template an Ihr Telefon. Es wird als "493021 is your verification code. Do not share it." mit dem von Ihnen übergebenen code-Wert gerendert. Installieren Sie das Bird SDK für Ihre Sprache, indem Sie dem SDK-Quickstart folgen.

Ersetzen Sie in den SDK-Tabs den Beispiel-API-Schlüssel und ersetzen Sie +14155550100 durch Ihre Mobilnummer im E.164-Format. Die CLI verwendet Ihr Login, und der cURL-Tab verwendet 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" }
    }
  }'

Wenn Ihr Schlüssel mit bk_eu1_ beginnt, rufen Sie stattdessen https://eu1.platform.bird.com auf.

Die API antwortet mit 202 Accepted und der Nachricht. Die id beginnt mit sms_, und der status ist accepted: Bird hat die Nachricht und stellt sie asynchron zu. Notieren Sie die id für den nächsten Schritt. Die Nachricht kommt vom gemeinsam genutzten Absender, den Bird für Ihr Land ausgewählt hat.

4. Zustellstatus prüfen

Rufen Sie die Nachricht anhand ihrer ID ab. Ein Lesevorgang direkt nach dem Senden kann 404 zurückgeben, bis die Nachricht auf dem Lese-Endpoint sichtbar wird – das geschieht kurz nach dem 202. Lesen Sie sie einen Moment später erneut. Ersetzen Sie SMS_MESSAGE_ID durch die id aus Schritt 3 und den Beispiel-API-Schlüssel in den SDK-Tabs durch Ihren eigenen. Das Go-SDK bietet keine typisierte Methode zum Lesen einer SMS-Nachricht, daher ruft der Go-Tab den API-Pfad über die client.Get-Request-Methode des SDK auf.

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"

Das Feld status gibt an, wo sich die Nachricht befindet:

accepted: Bird hat die Nachricht und hat sie noch nicht an einen Carrier übergeben.
sent: Der Carrier hat die Nachricht, und sent_at gibt an, wann Bird sie übergeben hat.
delivered: Der Carrier hat die Zustellung bestätigt, und delivered_at gibt den Zeitpunkt an.
undelivered, failed, rejected oder expired: Die Nachricht hat das Telefon nicht erreicht. last_error nennt den Grund, und Zustellungsfehler erläutert jeden einzelnen.

Fragen Sie den Status ab, bis er accepted und sent verlässt, oder abonnieren Sie die SMS-Events, um jede Änderung per Webhook zu erhalten. Jede Nachricht erscheint außerdem auf der Seite Messages mit ihrer Event-Timeline.

Fehlgeschlagenen Versand beheben

422 SMSDestinationNotEnabled: Das Land des Empfängers ist für Ihren Workspace nicht aktiviert. Aktivieren Sie es wie in Schritt 2, warten Sie bis zu einer Minute und senden Sie erneut.
402 WalletInsufficientBalance: Das Guthaben reicht nicht für die Nachricht. Laden Sie das Wallet auf und senden Sie erneut.
403 InsufficientScope: Dem API-Key fehlt der Scope sms. Bearbeiten Sie die Scopes des Keys oder erstellen Sie einen Key mit sms:write.

Nächste Schritte

SMS senden: Senden Sie eigenen Text mit einem Sender und einer Kategorie, in Batches und mit sicheren Wiederholungsversuchen.
SMS-Sender-IDs: Wählen Sie einen Sender pro Land und registrieren Sie ihn, wo das Land es verlangt.
SMS-Templates: Der Katalog der integrierten Templates und ihre Variablen.
SMS-Events: Die Event-Typen und der Webhook-Versand für jede Statusänderung.
SMS-API-Referenz: das vollständige Request- und Response-Schema.

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Implementierungs-Briefing erhalten