Depreciações

Bird deprecia três coisas diferentes, e cada uma se comporta de forma distinta. Um campo de requisição é renomeado, e o nome antigo continua funcionando junto com o novo. Um parâmetro de consulta é substituído por um filtro melhor, e continua funcionando sem alteração. Um formato do corpo da requisição é substituído por um novo formato, e o formato antigo continua sendo aceito. Em todos os casos, uma requisição que usa qualquer um deles volta com um cabeçalho de resposta Deprecation informando isso.

O cabeçalho

Uma resposta a uma requisição que continha um campo, parâmetro ou formato de corpo depreciado inclui:

Cabeçalho	Valor
Deprecation	A data em que a depreciação foi anunciada, por exemplo @1786579200
Link	<https://bird.com/docs/api/deprecations>; rel="deprecation"

O valor de Deprecation registra quando o nome antigo foi depreciado, seguindo a RFC 9745. Ele não anuncia uma data de remoção.

Respostas a requisições que usam apenas nomes atuais não trazem nenhum dos cabeçalhos, então a presença do cabeçalho é o sinal: se você nunca o vê, nada do que você envia está depreciado.

Sem data de remoção

Bird não envia um cabeçalho Sunset porque nenhuma data de remoção está disponível ainda. Um nome substituído só é removido depois que o uso cessou. Bird contata os clientes afetados antes da remoção.

Trate o cabeçalho Deprecation como um aviso para migrar no seu próprio ritmo. Ele não inicia uma contagem regressiva de remoção.

Um campo de requisição renomeado

Um nome de campo substituído se comporta exatamente como antes:

Ele ainda é aceito nas requisições e ainda grava o mesmo valor.
Ele ainda é retornado nas respostas, junto com o nome que o substituiu.
O nome atual prevalece se você enviar ambos, então você pode migrar um ponto de chamada por vez sem que o nome antigo sobrescreva o novo.

Nomes de campo renomeados são omitidos desta referência, e os SDKs oficiais expõem apenas os nomes atuais. Atualizar seu SDK, portanto, move as requisições para o nome de campo atual.

Um parâmetro de consulta depreciado

Um parâmetro de consulta é depreciado quando um filtro melhor o substitui. Ele se comporta de forma diferente de um campo renomeado em três aspectos que vale conhecer:

Ele continua publicado em todos os lugares. Removê-lo da referência e dos SDKs quebraria chamadores que já o enviam, então ele mantém sua linha nesta referência, seu campo em cada SDK, sua flag no CLI e sua entrada no esquema de ferramentas do MCP. Atualizar seu SDK não faz a migração por você.
Não existe lado da resposta. Um parâmetro de consulta só aparece na requisição, então nada no corpo da resposta muda e não há nome novo para ler de volta.
A substituição pode não ser um único parâmetro. Um filtro às vezes é substituído por um par, então a própria descrição do parâmetro indica o que usar no lugar, em vez de apontar para um único sucessor.

Como a atualização não faz a migração por você, o cabeçalho Deprecation é o único sinal que você vai receber. Verifique a descrição do parâmetro nesta referência: um parâmetro depreciado começa com Deprecated: e indica sua substituição.

Um formato de corpo de requisição substituído

Os endpoints de envio em lote, POST /v1/sms/batches e POST /v1/email/batches, antes recebiam o lote como um array JSON de nível superior. Agora eles recebem um objeto cujo array messages contém os mesmos itens, que é o formato documentado nesta referência. Uma requisição cujo corpo ainda é o array simples continua funcionando exatamente como antes e volta com o cabeçalho Deprecation. Os SDKs oficiais enviam o objeto messages, então atualizar seu SDK move suas requisições para o formato atual.

Migrando

Fique atento ao cabeçalho Deprecation nas suas respostas.
Encontre a requisição que o produziu e consulte esta referência para a operação, a fim de ver os nomes atuais e o formato da requisição.
Migre para o nome ou formato atual. Envie apenas o formato atual depois de migrar.

Depreciações atuais

Operação	Depreciado	Use no lugar
WhatsApp: listar mensagens	parâmetro de consulta phone_number	to ou from
SMS e email: criar um lote de mensagens	corpo da requisição como array simples	um objeto com messages

Nenhuma renomeação de campo está depreciada. O número de telefone de um contato é phone_number e o endereço de e-mail de um destinatário de verificação é email dentro de to; qualquer outra grafia de um ou outro é rejeitada como erro de validação, em toda operação que os aceita.

to e from na lista de mensagens de WhatsApp correspondem cada um a uma ponta da mensagem, e cada um aceita um número de telefone ou um ID de usuário com escopo de negócio. phone_number correspondia ao contato em qualquer direção, então uma busca que não se importa com a direção precisa de ambos os filtros, uma requisição para cada.

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 integration Guia de implementaçãoSend your first email

Obtenha um resumo de implementação