Obsolescencias
Bird marca como obsoletas tres cosas distintas, y cada una se comporta de forma diferente. Un campo de solicitud se renombra, y el nombre anterior sigue funcionando junto con el nuevo. Un parámetro de consulta se reemplaza por un filtro mejor, y sigue funcionando sin cambios. Una forma del cuerpo de solicitud se reemplaza por una forma nueva, y la forma anterior se sigue aceptando. En todos los casos, una solicitud que use cualquiera de ellos recibe de vuelta un encabezado de respuesta Deprecation que te lo indica.
El encabezado
Una respuesta a una solicitud que incluyó un campo, parámetro o forma de cuerpo obsoletos contiene:
| Encabezado | Valor |
|---|---|
| Deprecation | La fecha en que se anunció la obsolescencia, por ejemplo @1786579200 |
| Link | <https://bird.com/docs/api/deprecations>; rel="deprecation" |
El valor de Deprecation registra cuándo el nombre anterior pasó a ser obsoleto, conforme a RFC 9745. No anuncia una fecha de eliminación.
Las respuestas a solicitudes que solo usan nombres vigentes no incluyen ninguno de los dos encabezados, así que su presencia es la señal: si nunca lo ves, nada de lo que envías es obsoleto.
Sin fecha de eliminación
Bird no envía un encabezado Sunset porque aún no hay una fecha de eliminación disponible. Un nombre reemplazado se elimina solo cuando su uso se ha detenido. Bird contacta a los clientes afectados antes de la eliminación.
Trata el encabezado Deprecation como una invitación a migrar a tu propio ritmo. No inicia una cuenta regresiva de eliminación.
Un campo de solicitud renombrado
Un nombre de campo reemplazado se comporta exactamente como antes:
- Sigue siendo aceptado en las solicitudes y sigue escribiendo el mismo valor.
- Sigue apareciendo en las respuestas, junto con el nombre que lo reemplazó.
- El nombre vigente prevalece si envías ambos, así que puedes migrar un punto de llamada a la vez sin que el nombre anterior sobrescriba el nuevo.
Los nombres de campo renombrados se omiten en esta referencia, y los SDK oficiales solo exponen los nombres vigentes. Actualizar tu SDK mueve tus solicitudes al nombre de campo vigente.
Un parámetro de consulta obsoleto
Un parámetro de consulta se marca como obsoleto cuando un filtro mejor lo reemplaza. Se comporta de forma diferente a un campo renombrado en tres aspectos que conviene conocer:
- Sigue publicado en todas partes. Eliminarlo de la referencia y los SDK rompería a quienes ya lo envían, así que conserva su fila en esta referencia, su campo en cada SDK, su marca en el CLI y su entrada en el esquema de herramientas MCP. Actualizar tu SDK no te migra.
- No tiene contrapartida en la respuesta. Un parámetro de consulta solo aparece en la solicitud, así que nada cambia en el cuerpo de la respuesta y no hay un nombre nuevo que leer de vuelta.
- El reemplazo puede no ser un solo parámetro. A veces un filtro se reemplaza por un par, así que la propia descripción del parámetro indica qué usar en su lugar en vez de señalar un único sucesor.
Como actualizar no te migra, el encabezado Deprecation es la única señal que recibirás. Consulta la descripción del parámetro en esta referencia: uno obsoleto comienza con Deprecated: e indica su reemplazo.
Una forma de cuerpo de solicitud reemplazada
Los endpoints de envío por lotes, POST /v1/sms/batches y POST /v1/email/batches, antes recibían el lote como un array JSON de nivel superior. Ahora reciben un objeto cuyo array messages contiene los mismos elementos, que es la forma documentada en esta referencia. Una solicitud cuyo cuerpo siga siendo el array simple funciona exactamente como antes y recibe de vuelta el encabezado Deprecation. Los SDK oficiales envían el objeto messages, así que actualizar tu SDK mueve tus solicitudes a la forma vigente.
Migración
- Busca el encabezado Deprecation en tus respuestas.
- Encuentra la solicitud que lo produjo y consulta esta referencia para la operación correspondiente a fin de ver los nombres y la forma de solicitud vigentes.
- Pasa al nombre o forma vigente. Una vez hecho, envía solo la forma actual.
Obsolescencias vigentes
| Operación | Obsoleto | Usar en su lugar |
|---|---|---|
| WhatsApp: listar mensajes | parámetro de consulta phone_number | to o from |
| SMS y email: crear un lote de mensajes | cuerpo de solicitud como array simple | un objeto con messages |
Ningún renombramiento de campo está obsoleto. El número de teléfono de un contacto es phone_number y la dirección de correo electrónico de un destinatario de verificación es email dentro de to; cualquier otra forma de escribirlos se rechaza como error de validación en toda operación que los acepte.
to y from en la lista de mensajes de WhatsApp coinciden cada uno con un extremo del mensaje, y cada uno acepta un número de teléfono o un ID de usuario con alcance de negocio. phone_number coincidía con el contacto en cualquier dirección, así que una búsqueda que no distinga dirección necesita ambos filtros, una solicitud para cada uno.
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Comprender el conceptoShould I use a Bird SDK or call the API directly?Seguir la ruta de aprendizajeBuild your first integrationGuía de implementaciónSend your first email
Obtener un resumen de implementación