Migrar SMS desde Sinch
Esta página mapea SMS API, grupos e informes de entrega de Sinch a Bird. Sigue la guía principal de migración en orden y usa estas correspondencias para los pasos 3, 4 y 5.
Dos diferencias estructurales definen la migración, y ambas cuestan más que los renombramientos de campos. Sinch asocia el envío a un service plan en la ruta de la URL y envía un batch, así que un mensaje a una persona sigue siendo un array; el POST /v1/sms/messages de Bird acepta un destinatario en tu host regional con una clave bearer y sin segmento de plan. Además, el registro en EE. UU. que no puedes omitir está en un host distinto al del envío, detrás de una familia de credenciales diferente, así que un código que accede a Sinch para ambas cosas está accediendo a dos lugares.
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 Sinch 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/sinch.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 Sinch 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.Mapear la llamada de envío
| Qué hace | Sinch | Bird |
|---|---|---|
| Destinatario | to (array, o un ID de grupo) | to (uno por solicitud) |
| Remitente | from | from |
| Cuerpo | body | text |
| Enrutamiento de cuenta | service plan, en la ruta de la URL | la clave bearer; sin segmento de ruta |
| Intención | (ninguna) | category, obligatorio en texto libre |
| Informes de entrega | delivery_report + callback_url, por batch | un webhook del espacio de trabajo; sin control por envío |
| Correlación | client_reference | metadata, devuelto en cada evento |
| Etiquetas filtrables | (ninguna) | pares tags: {name, value} |
| Reintentos seguros | (no documentado) | encabezado Idempotency-Key |
| Flash | flash_message | sin equivalente |
Notas de migración:
- Elige deliberadamente entre envío individual, batch o broadcast. to es un array en Sinch y un número individual aquí, así que usa envíos individuales o el endpoint de batch para hasta 100 mensajes independientes. Una campaña a una audiencia pertenece al flujo de broadcast. Un batch que nombraba un grupo necesita que la membresía se resuelva primero; consulta la sección de exclusiones, porque es el mismo problema.
- body pasa a ser text. Es el único renombramiento que afecta a todos los puntos de llamada.
- client_reference no es una clave de idempotencia. Sinch lo define como un identificador añadido al informe de entrega del batch, así que correlaciona pero no deduplica. Si dependías de él para hacer seguro un reintento, no estabas cubierto; Idempotency-Key es lo que cumple esa función aquí.
- Nada corresponde a category. Decide por tipo de mensaje si es transactional, marketing, authentication o service.
Trasladar las exclusiones
Sinch registra quién está dentro, y Bird necesita saber quién está fuera. Esa inversión es el trabajo.
Sinch gestiona los destinatarios como grupos, y un grupo puede actualizarse automáticamente con disparadores de palabras clave, así que un suscriptor que envía STOP se elimina del grupo y un suscriptor que envía SUBSCRIBE se añade. La exclusión queda codificada como ausencia de una lista en lugar de presencia en una, y la ausencia no es exportable: un número que falta en un grupo puede haberse excluido, puede que nunca se haya unido, o puede haber sido eliminado por una importación hace seis meses.
Así que reconstruye en lugar de exportar. Tu propio registro de mensajes entrantes es la fuente fiable, porque algunas exclusiones comenzaron como mensajes entrantes, mientras que otras llegaron a través de soporte, formularios u otro canal de preferencias, y esos mensajes existen independientemente de lo que diga ahora la membresía del grupo. Donde mantuviste tu propia marca de baja junto al grupo, esa marca es mejor evidencia que la membresía. Lleva la lista reconstruida al bucle de supresión y muestra la lista a quien sea responsable de la cuenta antes de importarla: una entrada incorrecta aquí detiene silenciosamente mensajes que pretendías enviar.
Una supresión en Bird es un par de remitente y suscriptor, así que un suscriptor al que detienes en tres remitentes son tres registros. Leer y gestionar supresiones contiene el comando y la razón por la que una supresión manual bloquea todas las categorías, incluida la transaccional.
Una vez que estás aquí, Bird responde a las palabras clave de detención por sí mismo desde su propio catálogo por país, así que el comportamiento de actualización automática del grupo no tiene equivalente que reconstruir: un suscriptor que envía STOP genera una supresión sin que tu aplicación haga nada. Las razones se apilan en lugar de fusionarse, así que un par que importaste como manual y que después envía STOP tiene dos registros, y los mensajes permanecen detenidos hasta que ambos hayan terminado.
Traducir 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 ningún mensaje; un rechazo después de la aceptación puede producir sms.rejected, incluido un rechazo del operador. La evidencia de entrega ausente permanece como desconocida. Conserva el estado y el código sin procesar del proveedor junto a tu resultado normalizado.
La referencia de informes de entrega de Sinch incluye queued, dispatched, delivered y varios estados finales de fallo distintos. Conserva el código y el estado a nivel de destinatario al traducir tus informes.
| Concepto en Sinch | Decisión de integración con Bird |
|---|---|
| Queued / Dispatched | Registra la aceptación y el envío al operador por separado con sms.accepted y sms.sent. |
| Delivered | Registra el resultado de red mediante sms.delivered; no demuestra lectura. |
| Failed / Rejected / Deleted | Inspecciona la razón reportada. Los eventos de fallo de Bird no se seleccionan con una sustitución solo por nombre. |
| Aborted / Expired / Cancelled | Conserva la causa y la etapa. El API de envío individual de Bird no tiene temporizador de programación ni de validez para recrear estos controles. |
| Unknown | Mantén el resultado como incierto; no cuentes un acuse de recibo ausente o no interpretable como entrega. |
El sms.expired de Bird sigue un informe de expiración del operador. Revisa tu comportamiento actual de expiración y cancelación por separado de ese evento en lugar de mapear cada timeout a él.
Ten en cuenta también que los estados intermedios solo se reportan cuando el batch solicitó informes per_recipient, lo cual es parte de lo que cambia a continuación.
Pierdes el control por envío de los informes de entrega, y vale la pena decirlo claramente. Un batch de Sinch elige su propia granularidad de informes y puede sobrescribir la URL de callback del service plan para ese envío en particular. Bird no tiene ninguna de las dos cosas: los informes son una suscripción del espacio de trabajo, cada evento suscrito se entrega y no hay sobrescritura por mensaje. Si usabas delivery_report para silenciar campañas con mucho tráfico, ese filtrado pasa a tu handler. Si enrutabas los informes de una campaña a un endpoint diferente, eso se convierte en un endpoint más una bifurcación, o una segunda suscripción.
Registra el endpoint una vez, indicando los tipos de evento que tu handler necesita: los eventos sms.* de arriba son la lista a la que suscribirte, y no hay comodín que los sustituya. Bird envía JSON firmados según Standard Webhooks; Crear un endpoint contiene el comando y lo único que debes hacer bien en la primera llamada, que es almacenar el secreto de firma que la respuesta muestra una sola vez.
Bird reporta un fallo con un código error estandarizado como invalid_destination, content_rejected, provider_unavailable o recipient_opted_out; la lista completa está en la página de eventos.
Transición
Los destinos, los remitentes y la rampa de tráfico son independientes del proveedor y se cubren en la guía principal. Dos elementos específicos de Sinch pertenecen al plan de transición.
Tu marca y campaña 10DLC están registradas en The Campaign Registry a través de Sinch 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. Aquí es también donde la integración se simplifica. En Sinch, el API de registro está en un host separado del de envío y usa credenciales de proyecto en lugar del token del service plan, y la propia documentación de Sinch dice que HTTP Basic allí está pensado solo para pruebas y tiene una limitación de solicitudes estricta, así que una integración en producción construye un flujo de token OAuth para ello. En Bird, /v1/sms/10dlc/* está junto a /v1/sms/messages bajo una URL base y una clave, así que ese ciclo de vida de tokens se retira en lugar de migrarse. Comienza desde Registrarse para 10DLC, que explica qué significa cada campo y la llamada de requisitos que te indica qué proporcionar antes de crear la marca, que es el paso con cargo.
Los números que posees en Sinch necesitan una portabilidad que soporte gestiona, en su propio calendario y no en el tuyo.
Próximos pasos
-
Comparar Bird y Sinch para SMS: evaluación de producto y consideraciones de migración
-
Enviar SMS: el payload completo al que estás migrando
-
Exclusiones y palabras clave: cobertura de palabras clave por país y gestión de supresiones
-
Eventos de SMS: el vocabulario de eventos al que migra tu handler de informes
-
Webhooks y eventos: configuración de endpoints y verificación de Standard Webhooks
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.