Wyślij swoją pierwszą wiadomość SMS

Wyślij wiadomość tekstową na własny telefon za pomocą Bird SMS, a następnie odczytaj ją, żeby sprawdzić, czy została doręczona. Ten przewodnik szybkiego startu używa wbudowanego szablonu, który dostarcza tekst, kategorię i współdzielonego nadawcę, którego Bird wybiera dla miejsca docelowego. Nie potrzebujesz do tego identyfikatora nadawcy ani rejestracji nadawcy.

Zanim zaczniesz, upewnij się, że portfel Twojej organizacji ma środki. Wysyłki SMS pobierają środki z portfela, a Bird odrzuca wysyłkę, której saldo nie jest w stanie pokryć, zwracając 402 WalletInsufficientBalance. Metody płatności i portfel opisuje doładowanie.

1. Utwórz klucz API

W panelu przejdź do Platform tools > Klucze API i utwórz klucz z zakresem sms:write, który obejmuje wysyłanie i odczytywanie wiadomości. Klucze są przypisane do regionu i wyglądają jak bk_us1_... lub bk_eu1_.... Region w prefiksie wskazuje, który host API wywołać: https://us1.platform.bird.com lub https://eu1.platform.bird.com.

Strona kluczy API w panelu Bird, z listą kluczy wraz z zamaskowanym prefiksem, zakresami i czasem ostatniego użycia

Pełny klucz jest wyświetlany raz, w momencie utworzenia. Skopiuj go w bezpieczne miejsce, a następnie wyeksportuj do przykładów cURL:

Przykład kodu

export BIRD_API_KEY="bk_us1_..."

2. Włącz kraj docelowy

Bird wysyła SMS tylko do krajów włączonych dla Twojego obszaru roboczego. Wysyłka do innego kraju kończy się błędem 422 SMSDestinationNotEnabled. Włącz kraj swojego numeru telefonu w sekcji SMS > Destinations. Jeśli kraj jest już włączony, przejdź do kroku 3.

Z terminala Bird CLI wprowadza tę samą zmianę. Podaj dwuliterowy kod ISO kraju, na przykład US dla Stanów Zjednoczonych. Jeśli Twój login CLI nie ma dostępu do ustawień SMS, polecenie wyświetli komendę bird auth login, która go doda:

Przykład kodu

bird sms destinations update --destination US=true

Agenci połączeni z serwerem MCP używają narzędzia sms_destinations_update. Publiczne API nie ma operacji dla destynacji. Zastosowanie zmiany do wysyłek może zająć do minuty.

3. Wyślij wiadomość

Wyślij wbudowany szablon bird_otp_verification na swój telefon. Renderuje się jako "493021 is your verification code. Do not share it." z wartością code, którą przekażesz. Zainstaluj Bird SDK dla swojego języka, korzystając z jego quickstartu SDK.

W kartach SDK zastąp przykładowy klucz API i zastąp +14155550100 swoim numerem telefonu komórkowego w formacie E.164. Karta CLI używa Twojego loginu, a karta cURL używa 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" }
    }
  }'

Jeśli Twój klucz zaczyna się od bk_eu1_, wywołaj zamiast tego https://eu1.platform.bird.com.

API odpowiada kodem 202 Accepted i wiadomością. Jej id zaczyna się od sms_, a status ma wartość accepted: Bird przyjął wiadomość i dostarczy ją asynchronicznie. Zachowaj id na następny krok. Wiadomość przychodzi od współdzielonego nadawcy, którego Bird wybrał dla Twojego kraju.

4. Sprawdź status dostarczenia

Pobierz wiadomość po jej ID. Odczyt zaraz po wysłaniu może zwrócić 404, dopóki wiadomość nie stanie się widoczna na endpoincie odczytu, co następuje krótko po 202. Odczytaj ją ponownie chwilę później. Zastąp SMS_MESSAGE_ID wartością id z kroku 3, a przykładowy klucz API w zakładkach SDK swoim własnym. SDK Go nie ma typowanej metody do odczytu wiadomości SMS, więc zakładka Go wywołuje ścieżkę API przez metodę żądania client.Get obiektu 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"

Pole status informuje, gdzie znajduje się wiadomość:

accepted: Bird ma wiadomość i nie przekazał jej jeszcze do operatora.
sent: operator ma wiadomość, a sent_at rejestruje, kiedy Bird ją przekazał.
delivered: operator potwierdził dostarczenie, a delivered_at zapisuje, kiedy to nastąpiło.
undelivered, failed, rejected lub expired: wiadomość nie dotarła na telefon. last_error podaje przyczynę, a Błędy dostarczenia wyjaśnia każdy z nich.

Odpytuj, aż status opuści accepted i sent, lub zasubskrybuj zdarzenia SMS, aby otrzymywać każdą zmianę przez webhook. Każda wiadomość pojawia się też na stronie Messages z osią czasu zdarzeń.

Napraw nieudane wysłanie

422 SMSDestinationNotEnabled: kraj odbiorcy nie jest włączony dla Twojego obszaru roboczego. Włącz go zgodnie z krokiem 2, poczekaj do minuty i wyślij ponownie.
402 WalletInsufficientBalance: portfel nie pokrywa kosztu wiadomości. Doładuj portfel, a następnie wyślij ponownie.
403 InsufficientScope: klucz API nie ma zakresu sms. Zmień zakresy klucza lub utwórz klucz z sms:write.

Następne kroki

Wysyłanie SMS: wyślij własny tekst z nadawcą i kategorią, w partiach i z bezpiecznym ponawianiem.
Identyfikatory nadawcy SMS: wybierz nadawcę dla każdego kraju i zarejestruj go tam, gdzie kraj tego wymaga.
Szablony SMS: katalog wbudowanych szablonów i ich zmienne.
Zdarzenia SMS: typy zdarzeń i dostarczanie webhooków przy każdej zmianie statusu.
Dokumentacja SMS API: pełny schemat żądania i odpowiedzi.

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.

Uzyskaj brief wdrożeniowy