Verstuur je eerste SMS

Verstuur een tekstbericht naar je eigen telefoon met Bird SMS en lees het bericht daarna terug om te zien of het bezorgd is. Deze quickstart gebruikt een ingebouwd sjabloon dat de tekst, de categorie en een gedeelde afzender levert die Bird selecteert voor de bestemming. Je hebt er geen afzender-ID of afzenderregistratie voor nodig.

Controleer voordat je begint of de wallet van je organisatie saldo heeft. SMS-verzendingen worden van de wallet afgeschreven, en Bird weigert een verzending die het saldo niet kan dekken met 402 WalletInsufficientBalance. Betaalmethoden en wallet beschrijft hoe je saldo opwaardeert.

1. Maak een API-sleutel aan

Ga in het dashboard naar Platform tools > API-sleutels en maak een sleutel aan met het sms:write-bereik, dat verzenden en lezen van berichten omvat. Sleutels zijn gekoppeld aan een regio en zien er uit als bk_us1_... of bk_eu1_.... De regio in het voorvoegsel geeft aan welke API-host je moet aanroepen: https://us1.platform.bird.com of https://eu1.platform.bird.com.

De API-sleutelpagina in het Bird-dashboard, met sleutels en hun gemaskeerde voorvoegsel, bereiken en laatste gebruikstijd

De volledige sleutel wordt eenmalig getoond, op het moment van aanmaken. Kopieer hem naar een veilige plek en exporteer hem voor de cURL-voorbeelden:

Codevoorbeeld

export BIRD_API_KEY="bk_us1_..."

2. Schakel het bestemmingsland in

Bird verzendt SMS alleen naar de landen die voor je werkruimte zijn ingeschakeld. Een verzending naar een ander land mislukt met 422 SMSDestinationNotEnabled. Schakel het land van je telefoonnummer in onder SMS > Destinations. Als het al als ingeschakeld wordt weergegeven, ga dan verder met stap 3.

Vanuit een terminal brengt de Bird CLI dezelfde wijziging aan. Geef de tweeletterige ISO-code van het land door, bijvoorbeeld US voor de Verenigde Staten. Als je CLI-login geen toegang heeft tot SMS-instellingen, toont het commando het bird auth login-commando dat deze toevoegt:

Codevoorbeeld

bird sms destinations update --destination US=true

Agents die verbonden zijn met de MCP-server gebruiken de sms_destinations_update-tool. De publieke API heeft geen operatie voor bestemmingen. Het kan tot een minuut duren voordat een wijziging van toepassing is op verzendingen.

3. Verstuur het bericht

Verstuur de ingebouwde bird_otp_verification-template naar je telefoon. Het wordt weergegeven als "493021 is your verification code. Do not share it." met de code-waarde die je meegeeft. Installeer de Bird SDK voor je taal door de SDK-quickstart te volgen.

Vervang in de SDK-tabs de voorbeeld-API-key en vervang +14155550100 door je mobiele nummer in E.164-formaat. De CLI gebruikt je login en het cURL-tab gebruikt 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" }
    }
  }'

Als je key begint met bk_eu1_, roep dan https://eu1.platform.bird.com aan.

De API antwoordt met 202 Accepted en het bericht. De id begint met sms_ en de status is accepted: Bird heeft het bericht en bezorgt het asynchroon. Bewaar de id voor de volgende stap. Het bericht komt binnen via de gedeelde afzender die Bird voor jouw land heeft geselecteerd.

4. Controleer de bezorgstatus

Haal het bericht op aan de hand van zijn ID. Een leesverzoek direct na het verzenden kan 404 teruggeven totdat het bericht zichtbaar wordt op het leesendpoint, wat kort na de 202 gebeurt. Probeer het even later opnieuw. Vervang SMS_MESSAGE_ID door de id uit stap 3, en de voorbeeld-API-sleutel in de SDK-tabs door je eigen sleutel. De Go-SDK heeft geen getypeerde methode om een SMS-bericht te lezen, dus het Go-tabblad roept het API-pad aan via de client.Get-requestmethode van de 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"

Het veld status geeft aan waar het bericht zich bevindt:

accepted: Bird heeft het bericht en heeft het nog niet aan een carrier overgedragen.
sent: de carrier heeft het bericht en sent_at registreert wanneer Bird het heeft overgedragen.
delivered: de carrier heeft de aflevering bevestigd, en delivered_at registreert wanneer.
undelivered, failed, rejected of expired: het bericht heeft de telefoon niet bereikt. last_error geeft de reden, en Afleverfouten licht elke fout toe.

Poll totdat de status accepted en sent verlaat, of abonneer je op de SMS-events om elke wijziging per webhook te ontvangen. Elk bericht verschijnt ook op de Messages-pagina met zijn eventtijdlijn.

Een mislukte verzending oplossen

422 SMSDestinationNotEnabled: het land van de ontvanger is niet ingeschakeld voor je werkruimte. Schakel het in zoals in stap 2, wacht maximaal een minuut en verstuur opnieuw.
402 WalletInsufficientBalance: de wallet kan het bericht niet dekken. Vul de wallet aan en verstuur opnieuw.
403 InsufficientScope: de API-key mist het sms-bereik. Bewerk de bereiken van de key of maak een key aan met sms:write.

Volgende stappen

SMS versturen: verstuur je eigen tekst met een afzender en categorie, in batches en met veilige herhaalpogingen.
SMS-afzender-ID's: kies een afzender per land en registreer deze waar het land dat vereist.
SMS-templates: de ingebouwde templatecatalogus en de bijbehorende variabelen.
SMS-events: de eventtypen en webhookaflevering voor elke statuswijziging.
SMS API-referentie: het volledige request- en responseschema.

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Ontvang een implementatieoverzicht