Sign inGet Started
Começar
Guias
Referência de API
SDKs
CLI
Base de conhecimento
Changelog

Introdução

A Bird API é uma REST API unificada para tudo o que a plataforma faz. Esta referência documenta todos os endpoints públicos, gerada a partir da mesma especificação OpenAPI que alimenta os SDKs oficiais, de modo que os formatos de requisição e resposta aqui são exatamente o que trafega na rede.
A barra lateral da referência agrupa os recursos mais usados por produto: Email, SMS, Voice, Realtime, Verify e as ferramentas para desenvolvedores (Webhooks e Documentation, a API de busca na documentação). Outros endpoints públicos, incluindo domínios de envio, e-mail de entrada, contatos e audiências, e WhatsApp, podem ser encontrados pela busca e pelos links diretos nos respectivos guias. A seção Voice inclui chamadas, logs de pernas de chamada, troncos, números, identificadores de chamada, destinos e credenciais de sessão SIP. As estatísticas de voz continuam disponíveis pelo painel e por CLI. Configurações do espaço de trabalho, chaves API e IPs dedicados são gerenciados no painel, não na API pública.
As páginas de recurso possuem links diretos a partir dos guias: quando um guia menciona um endpoint, o link leva à entrada correspondente nesta referência.

Convenções

Todo endpoint segue as mesmas convenções. Elas são declaradas uma vez aqui, em vez de repetidas em cada página.
  • Caminho base: todos os endpoints residem em /v1 em um host regional como https://us1.platform.bird.com. Veja URLs base e regiões.
  • Autenticação: as requisições levam uma chave API como bearer token: Authorization: Bearer bk_us1_.... Veja Autenticação.
  • JSON, snake_case: os corpos de requisição e resposta são JSON com nomes de campo em snake_case (created_at, workspace_id), e as requisições devem definir Content-Type: application/json.
  • Timestamps: todos os timestamps são strings RFC 3339 em UTC, em campos com sufixo _at (created_at, delivered_at). Timestamps de recurso como created_at são atribuídos pelo servidor e somente leitura; alguns campos de requisição, como scheduled_at, são timestamps fornecidos por você.
  • IDs de recurso tipados: todo ID carrega um prefixo de tipo: em_ para mensagens de e-mail, dom_ para domínios de envio, whk_ para endpoints de webhook, sup_ para supressões, e assim por diante. O prefixo torna o ID autodescritivo nos logs e impede que o ID de um recurso seja passado no lugar de outro.
  • Atualizações parciais usam PATCH: uma requisição PATCH altera apenas os campos que você incluir; campos omitidos permanecem inalterados. Alguns sub-recursos endereçados pelo nome na URL são escritos com PUT, que substitui esse sub-recurso por completo.
  • Parâmetros de query são estritos: uma requisição que carrega um parâmetro de query não documentado pelo endpoint é rejeitada com 422 (E01029), em vez de ignorada. Verifique a grafia na lista de parâmetros do endpoint.
  • Erros: toda resposta de erro carrega a mesma resposta de erro, com um type para ramificação geral, um code estável, uma message legível por humanos e o request_id para citar ao contatar o suporte. Veja Respostas de erro.
  • Paginação: endpoints de listagem usam paginação baseada em cursor com um conjunto compartilhado de parâmetros. Veja Paginação.
  • Idempotência: endpoints de mutação aceitam um header Idempotency-Key para que novas tentativas sejam seguras. Veja Header Idempotency-Key.
  • Depreciações: um campo renomeado continua funcionando com o nome antigo, e a resposta indica isso com um header Deprecation. Veja Depreciações.

Clientes recomendados

Você pode chamar a API com qualquer cliente HTTP, mas os clientes oficiais cuidam de autenticação, seleção de região, novas tentativas e paginação para você:
  • Os SDKs oficiais para TypeScript, Go e Python: métodos tipados sobre a superfície pública curada
  • A Bird CLI: a API a partir do seu terminal, também adequada para scripts e agentes

Execute no Postman

A API completa também é uma coleção do Postman, convertida a partir desta mesma especificação, com um exemplo de requisição e resposta em cada endpoint. Importe o ambiente para a sua região, defina apiKey com uma chave API do espaço de trabalho e envie qualquer requisição.
Run in Postman
Você também pode baixar a coleção e um ambiente para us1 ou eu1 diretamente.

Leia a seguir

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Entenda o conceitoShould I use a Bird SDK or call the API directly?Siga o percurso de aprendizagemBuild your first integrationGuia de implementaçãoSend your first email
Obtenha um resumo de implementação