---
title: "Envie seu primeiro SMS"
description: "Crie uma chave Bird API, habilite um país de destino, envie um template integrado SMS para seu celular e consulte o status de entrega."
canonical: "https://bird.com/pt-br/documentacao/get-started/send-your-first-sms"
---

# 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](/docs/knowledge-base/billing/payment-methods-wallet) explica como adicionar saldo.

## 1. Crie uma chave API

No dashboard, vá em **Platform tools** > [**Chaves API**](https://bird.com/dashboard/w/api-keys) 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`.

![Página de chaves API no dashboard Bird, listando chaves com prefixo mascarado, escopos e último uso](/images/docs/dashboard-api-keys.png)

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:

```bash
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**](https://bird.com/dashboard/w/sms/destinations). Se ele já aparecer como habilitado, prossiga para o passo 3.

A partir de um terminal, o [Bird CLI](/docs/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:

```bash
bird sms destinations update --destination US=true
```

Agentes conectados ao [servidor MCP](/docs/ai/mcp-server) 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](/docs/get-started/quickstarts).

Nas abas SDK, substitua a chave API de exemplo e substitua `+14155550100` pelo seu número de celular no formato [E.164](https://en.wikipedia.org/wiki/E.164). A aba CLI usa o seu login, e a aba cURL usa `BIRD_API_KEY`.

**TypeScript**

```typescript
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);
```

Examples: [TypeScript](/pt-br/documentacao/get-started/send-your-first-sms.ts.md) · [Python](/pt-br/documentacao/get-started/send-your-first-sms.py.md) · [Go](/pt-br/documentacao/get-started/send-your-first-sms.go.md) · [PHP](/pt-br/documentacao/get-started/send-your-first-sms.php.md) · [CLI](/pt-br/documentacao/get-started/send-your-first-sms.cli.md) · [MCP](/pt-br/documentacao/get-started/send-your-first-sms.mcp.md) · [cURL](/pt-br/documentacao/get-started/send-your-first-sms.curl.md)

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.

**TypeScript**

```typescript
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);
```

Examples: [TypeScript](/pt-br/documentacao/get-started/send-your-first-sms.ts.md) · [Python](/pt-br/documentacao/get-started/send-your-first-sms.py.md) · [Go](/pt-br/documentacao/get-started/send-your-first-sms.go.md) · [PHP](/pt-br/documentacao/get-started/send-your-first-sms.php.md) · [CLI](/pt-br/documentacao/get-started/send-your-first-sms.cli.md) · [cURL](/pt-br/documentacao/get-started/send-your-first-sms.curl.md)

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](/docs/guides/sms/delivery-errors) explica cada um.

Consulte até que o status saia de `accepted` e `sent`, ou assine os [eventos de SMS](/docs/guides/sms/events) para receber cada mudança por webhook. Cada mensagem também aparece na página [**Messages**](https://bird.com/dashboard/w/sms/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](#2-habilite-o-país-de-destino), 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](/docs/guides/sms/sending-sms): envie seu próprio texto com um remetente e categoria, em lotes e com retentativas seguras.
- [IDs de remetente SMS](/docs/guides/sms/senders): escolha um remetente para cada país e registre-o onde o país exigir.
- [Templates SMS](/docs/guides/sms/templates): o catálogo de templates integrados e suas variáveis.
- [Eventos SMS](/docs/guides/sms/events): os tipos de evento e a entrega por webhook para cada mudança de status.
- [Referência da SMS API](/docs/api/reference/create-sms-message): o esquema completo de solicitação e resposta.

## Related resources

- [Sending your first SMS](/learn/sms/sending-your-first-sms) (video)
- [One-way and two-way SMS](/explained/sms/what-is-the-difference-between-one-way-and-two-way-sms) (answer)
- [Two-way SMS](/sms-api/features/two-way) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=sms-replies)