Migrar SMS desde Bandwidth
Esta página mapea la API Messages de Bandwidth, las Applications y los callbacks de mensajes a Bird. Sigue la guía principal de migración en orden y usa estos mapeos para los pasos 3, 4 y 5.
Dos diferencias definen toda la migración. Bandwidth divide el canal en dos hosts: el envío vive en el host de mensajería bajo la ruta de tu cuenta, autenticado con HTTP Basic, mientras que el registro 10DLC vive en el host principal de API. Bird pone envío, registro y eventos de entrega bajo una sola URL base y una sola clave bearer. Y el applicationId en cada envío de Bandwidth lleva la configuración de callbacks; Bird no tiene un objeto equivalente, porque los callbacks son una suscripción del espacio de trabajo en lugar de una propiedad del mensaje.
Pasa esto a tu agente
Usa este resumen en tu agente de código. Comienza con descubrimiento y produce un plan de migración revisable antes de cualquier cambio en producción.
Ejemplo de código
Help me migrate my SMS integration from Bandwidth to Bird.
1. Inspect this repository's sends, senders, callbacks, schedules, templates, opt-outs and tests. List the traffic and behavior that must survive the migration.
2. Read the Markdown guides at https://bird.com/docs/guides/sms/migrate/bandwidth.md and https://bird.com/docs/guides/sms/migrate.md. Use an existing authenticated Bird MCP or CLI connection. If neither is available, follow https://bird.com/docs/ai/set-up-your-agent.md. Discover the actual operations; do not invent commands or ask me to paste credentials into chat.
3. Prepare the code changes, sender/destination requirements, consent migration, webhook verification and rollout/rollback plan. Preserve the scope of each customer's preferences, including requests outside SMS replies. Separate API batches from audience broadcasts and preserve any behavior that has no direct endpoint equivalent.
4. Show me the exact affected resources, destinations, test volume and known costs before an action that sends messages, spends money, registers or changes a sender, or moves production traffic. Require explicit human authorization for each paid submission or production change. Name one-off 10DLC registration and resubmission fees before requesting approval. An existing explicit approval for that exact action is sufficient; broad migration approval is not. Simulated SMS destinations are billable and still require authorization.
5. If I am keeping Bandwidth numbers, prepare the human support port request and obtain authorization to send it. Read bird support-tickets create --help, then use the available CLI or MCP support operation with the reviewed number list and requirements. Return the ticket ID and follow the reply; support arranges the port on its own schedule, separately from the code cutover.
6. Run local and intercepted tests first. When authorized, perform the agreed bounded integration tests, inspect accepted and final outcomes separately, and report failures or uncertainty. Do not claim a delivery receipt proves reading or that request idempotency guarantees exactly-once delivery.
7. Keep production cutover and retiring the old provider as explicit steps in the approved rollout. Finish with the diff, evidence, unresolved requirements and the next action.Mapea la llamada de envío
| Qué hace | Bandwidth | Bird |
|---|---|---|
| Destinatario | to (array) | to (uno por solicitud) |
| Remitente | from | from |
| Cuerpo | text | text |
| Enrutamiento de callbacks | applicationId | un webhook de espacio de trabajo suscrito a los eventos de entrega de abajo |
| Intención | (ninguno) | category, obligatorio en texto libre |
| Etiqueta libre | tag (una cadena) | metadata; tags solo si puedes nombrarlo |
| Contexto de ida y vuelta | tu propio almacén, indexado por ID | metadata: JSON arbitrario, incluido en cada evento |
| Prioridad de entrega | priority | sin equivalente |
| Reintentos seguros | (ninguno en su especificación) | encabezado Idempotency-Key |
| Multimedia | media | sin equivalente: media_urls se rechaza |
Notas de migración:
- to pasa de un array a un solo destinatario. Bandwidth acepta una lista; Bird envía un mensaje por solicitud. Un bucle reemplaza el array, y cada llamada puede llevar su propio Idempotency-Key.
- El applicationId desaparece en lugar de trasladarse. Existe para indicar a Bandwidth dónde publicar los callbacks. En Bird eso es una suscripción del espacio de trabajo, así que nada en el envío lo nombra.
- tag y tags no son el mismo campo. El tag de Bandwidth es una cadena libre; los tags de Bird son pares {name, value} que se convierten en dimensiones de consulta. Una sola cadena opaca suele ir mejor en metadata.
- Nada en la API Messages corresponde a category. Decide por tipo de mensaje si es transactional, marketing, authentication o service.
Traslada los opt-outs
No hay lista que exportar, y eso es el hallazgo, no una laguna de esta guía.
Fuera de toll-free, Bandwidth no mantiene listas de opt-in ni opt-out por ti. Su propia documentación lo dice claramente: la responsabilidad de respetar los comandos y mantener las listas recae en el cliente. Toll-free es la excepción, donde STOP y sus variantes se aplican a nivel de red independientemente de tu configuración; los long codes y short codes no reciben ese tratamiento.
Así que en esta migración la lista autoritativa ya es tuya. Es una tabla, un flag en un registro de contacto o una verificación que tu flujo de envío ejecuta antes de llamar a la API, y la primera tarea es decidir cuál de esos es autoritativo en lugar de solicitar una exportación a nadie. Tu propio log de mensajes entrantes es el respaldo: algunos opt-outs comenzaron como mensajes entrantes, mientras que otros llegaron por soporte, formularios u otro canal de preferencias.
Luego importa a través del bucle de supresión. Una supresión de Bird es un par remitente-suscriptor, así que un suscriptor al que bloqueaste en tres remitentes equivale a tres registros. Lectura y gestión de supresiones contiene el comando y la razón por la que una supresión manual bloquea todas las categorías, incluida la transaccional.
Decide quién es dueño de la lista después del corte, porque aquí ganas algo y puedes perderle la pista. Bird responde a palabras clave de parada desde su propio catálogo por país, así que una vez que envías aquí, la plataforma mantiene las supresiones por ti: un suscriptor que envía STOP produce un registro con razón keyword_stop sin que tu aplicación haga nada. Si tu código mantiene su propia lista y la sigue aplicando, las dos divergen, y el síntoma habitual es un suscriptor que reanudó en un lado y no en el otro. Mantén explícito al dueño de las preferencias de audiencia y sincroniza los cambios relevantes deliberadamente. Las supresiones de remitente por sí solas no cubren preferencias a nivel de espacio de trabajo ni solicitudes fuera del catálogo de palabras clave. Las razones se apilan en lugar de fusionarse, así que un par que importaste como manual y que luego envía STOP tiene dos registros, y los mensajes permanecen detenidos hasta que ambos hayan terminado.
Traduce los estados de entrega
Usa esta tabla para comparar conceptos del ciclo de vida, no para renombrar eventos mecánicamente. Bird elige un evento de fallo a partir del estado y la razón reportados. Una solicitud API rechazada no crea mensaje; un rechazo tras la aceptación puede producir sms.rejected, incluido un rechazo del operador. La falta de evidencia de entrega queda como desconocida. Conserva el estado y código crudos del proveedor junto a tu resultado normalizado.
| Resultado | Tipo de callback de Bandwidth | Bird |
|---|---|---|
| API aceptó el mensaje | la respuesta 202, sin evento | sms.accepted |
| Entregado al operador | message-sent | sms.sent |
| El operador confirmó la entrega | message-delivered | sms.delivered |
| Nunca llegó al operador | message-failed | sms.rejected |
| El operador lo rechazó | message-failed | sms.failed |
| El operador reportó no entrega | message-failed | sms.undelivered |
| El operador desistió | message-failed | sms.expired |
| Solicitud rechazada en admisión | error de solicitud | error HTTP; sin mensaje ni evento |
Dos cosas de esa tabla merecen acción en lugar de pasarse por alto.
Reconstruye el manejo de estado terminal en torno al registro de mensaje y las marcas de tiempo de evento de Bird. Las entregas de webhooks pueden repetirse o llegar desordenadas; tu consumidor no debe asumir una sola entrega de un callback final. Un estado de rechazo y un estado de fallo de entrega pueden seleccionar eventos Bird distintos aunque ambos se hayan originado aguas abajo.
message-sending no tiene fila porque es exclusivo de MMS, y message-read es exclusivo de RBM; ninguno se dispara para SMS.
Dos mecánicas cambian junto con los nombres:
- Las suscripciones reemplazan la Application. Bandwidth enruta callbacks según el applicationId que el mensaje nombró. Bird entrega a endpoints que tu espacio de trabajo registra, cada uno suscrito a los tipos de evento que quiere, así que un nuevo consumidor es una nueva suscripción en lugar de una nueva Application y un redespliegue.
- Standard Webhooks reemplaza su autenticación de callbacks. Bird envía JSON firmados según Standard Webhooks; cambia la verificación por la receta en Webhooks & events.
Registra el endpoint una vez, nombrando los tipos de evento que tu handler necesita: los eventos sms.* de arriba son la lista a la que suscribirse, y no hay comodín que los represente. Crear un endpoint tiene el comando y lo único que debes hacer bien en la primera llamada, que es almacenar el secreto de firma que la respuesta muestra exactamente una vez.
Corte
Destinos, remitentes y la rampa de tráfico son independientes del proveedor y están cubiertos en la guía principal. Dos elementos específicos de Bandwidth pertenecen al plan de corte: tu marca y campaña 10DLC están registradas en The Campaign Registry a través de Bandwidth y no se convierten automáticamente en registros de Bird. Confirma el procedimiento de migración o registro aplicable antes de enviar trabajo de pago. Los números que posees en Bandwidth necesitan una portabilidad que soporte coordina, en su propio calendario y no en el tuyo.
Para los requisitos del lado de Bird, comienza por Registrarse para 10DLC: cubre qué significa cada campo, los tipos de entidad que el registro reconoce y la llamada de requisitos que te indica qué aportar antes de crear la marca, que es el paso con cargo.
Próximos pasos
-
Comparar Bird y Bandwidth para SMS: evaluación de producto y consideraciones de migración
-
Enviar SMS: el payload al que estás migrando, completo
-
Opt-outs y palabras clave: cobertura de palabras clave por país y gestión de supresiones
-
Eventos de SMS: el vocabulario de eventos al que tu handler de callbacks migra
-
Webhooks & events: configuración de endpoints y verificación con Standard Webhooks
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.