Envie seu primeiro SMS

Envie uma mensagem de texto para seu próprio celular com Bird SMS e depois consulte a mensagem para verificar se ela foi entregue. Este quickstart usa um template integrado, que fornece o texto, a categoria e um remetente compartilhado que Bird seleciona para o destino. Você não precisa de um sender ID nem de um registro de remetente para isso.

Antes de começar, confirme que a carteira da sua organização tem saldo. Envios SMS consomem a carteira, e Bird recusa um envio que o saldo não cobre com 402 WalletInsufficientBalance. Métodos de pagamento e carteira explica como adicionar saldo.

1. Crie uma chave API

No dashboard, vá em Platform tools > Chaves API e crie uma chave com o escopo sms:write, que cobre envio e leitura de mensagens. As chaves são associadas a uma região e têm o formato bk_us1_... ou bk_eu1_.... A região no prefixo indica qual host API chamar: https://us1.platform.bird.com ou https://eu1.platform.bird.com.

A chave completa é exibida uma única vez, no momento da criação. Copie-a em um lugar seguro e depois exporte-a para os exemplos cURL:

export BIRD_API_KEY="bk_us1_..."

2. Habilite o país de destino

Bird envia SMS apenas para os países habilitados no seu espaço de trabalho. Um envio para qualquer outro país falha com 422 SMSDestinationNotEnabled. Habilite o país do seu número de telefone em SMS > Destinations. Se ele já aparecer como habilitado, prossiga para o passo 3.

A partir de um terminal, o Bird CLI faz a mesma alteração. Passe o código ISO de duas letras do país, por exemplo US para os Estados Unidos. Se o seu login CLI não tiver acesso às configurações de SMS, o comando imprime o comando bird auth login que adiciona esse acesso:

bird sms destinations update --destination US=true

Agentes conectados ao servidor MCP usam a ferramenta sms_destinations_update. A API pública não tem operação para destinos. Uma alteração pode levar até um minuto para ser aplicada aos envios.

3. Envie a mensagem

Envie o template integrado bird_otp_verification para o seu telefone. Ele é renderizado como "493021 is your verification code. Do not share it." com o valor code que você passar. Instale o Bird SDK para a sua linguagem seguindo o quickstart SDK.

Nas abas SDK, substitua a chave API de exemplo e substitua +14155550100 pelo seu número de celular no formato E.164. A aba CLI usa o seu login, e a aba cURL usa 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" }
    }
  }'

Se a sua chave começa com bk_eu1_, chame https://eu1.platform.bird.com em vez disso.

A API responde com 202 Accepted e a mensagem. O id começa com sms_, e o status é accepted: Bird recebeu a mensagem e a entrega de forma assíncrona. Guarde o id para o próximo passo. A mensagem chega do remetente compartilhado que Bird selecionou para o seu país.

4. Verifique o status de entrega

Busque a mensagem pelo ID. Uma leitura logo após o envio pode retornar 404 até a mensagem ficar visível no endpoint de leitura, o que acontece pouco depois do 202. Leia novamente um momento depois. Substitua SMS_MESSAGE_ID pelo id do passo 3 e a chave API de exemplo nas abas SDK pela sua. O SDK de Go não tem um método tipado para ler uma mensagem SMS, então a aba Go chama o caminho API pelo método de solicitação client.Get do 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"

O campo status indica onde a mensagem está:

• accepted: Bird tem a mensagem e ainda não a entregou a uma operadora.
• sent: a operadora tem a mensagem, e sent_at registra quando Bird a entregou.
• delivered: a operadora confirmou a entrega, e delivered_at registra quando.
• undelivered, failed, rejected ou expired: a mensagem não chegou ao telefone. last_error informa o motivo, e Erros de entrega explica cada um.

Consulte até que o status saia de accepted e sent, ou assine os eventos de SMS para receber cada mudança por webhook. Cada mensagem também aparece na página Messages com sua linha do tempo de eventos.

Corrigir um envio com falha

• 422 SMSDestinationNotEnabled: o país do destinatário não está habilitado para o seu espaço de trabalho. Habilite-o como no passo 2, aguarde até um minuto e envie novamente.
• 402 WalletInsufficientBalance: o saldo da carteira não cobre a mensagem. Recarregue a carteira e envie novamente.
• 403 InsufficientScope: a chave API não possui o escopo sms. Edite os escopos da chave ou crie uma chave com sms:write.

Próximos passos

• Enviando SMS: envie seu próprio texto com um remetente e categoria, em lotes e com retentativas seguras.
• IDs de remetente SMS: escolha um remetente para cada país e registre-o onde o país exigir.
• Templates SMS: o catálogo de templates integrados e suas variáveis.
• Eventos SMS: os tipos de evento e a entrega por webhook para cada mudança de status.
• Referência da SMS API: o esquema completo de solicitação e resposta.