# Migra SMS desde Bird Connectivity Platform

Esta página mapea la API de Bird Connectivity Platform en `rest.messagebird.com`, la que quizá todavía conoces como MessageBird API, a Bird. Sigue la [guía principal de migración](/docs/guides/sms/migrate) en orden y usa estas correspondencias para los pasos 3, 4 y 5.

Ambas plataformas son de Bird, y la API es la parte que cambia. Tres diferencias afectan a cada llamada. Las peticiones van a tu host regional, `https://us1.platform.bird.com` o `https://eu1.platform.bird.com`, en lugar de un host global único. La autenticación es una clave bearer API (`Authorization: Bearer bk_us1_…`) en vez de `Authorization: AccessKey`. Y el envío es asíncrono: [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message) devuelve `202 Accepted` con el mensaje en cola, mientras que Connectivity Platform devolvía el objeto del mensaje con un estado por destinatario ya incluido.

## Pasa esto a tu agente

Usa este resumen en tu agente de código. Empieza con un descubrimiento y produce un plan de migración revisable antes de cualquier cambio en producción.

```text
Help me migrate my SMS integration from Bird Connectivity Platform 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/connectivity-platform.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 Connectivity Platform 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               | Connectivity Platform   | Bird                                                                         |
| ---------------------- | ----------------------- | ---------------------------------------------------------------------------- |
| Destinatario           | `recipients` (hasta 50) | `to`, uno por petición                                                       |
| Remitente              | `originator`            | `from`                                                                       |
| Cuerpo                 | `body`                  | `text`                                                                       |
| Intención              | (ninguno)               | `category`, obligatorio en texto libre                                       |
| Codificación           | `datacoding`            | detectada automáticamente                                                    |
| Transliteración        | (ninguno)               | `options.smart_encoding` (por defecto `false`)                               |
| Referencia del cliente | `reference`             | `metadata`, o `tags` cuando filtras por ella                                 |
| Informes de estado     | `reportUrl`             | un webhook del espacio de trabajo suscrito a los eventos de entrega de abajo |
| Reintentos seguros     | (ninguno)               | cabecera `Idempotency-Key`                                                   |
| Programación           | `scheduledDatetime`     | sin equivalente: `scheduled_at` se rechaza                                   |
| Validez                | `validity`              | sin equivalente: `validity_period` se rechaza                                |
| Selección de ruta      | `gateway`               | Bird selecciona la ruta                                                      |
| Clase de mensaje       | `mclass`                | sin equivalente                                                              |
| Binario y flash        | `type`, `typeDetails`   | solo texto                                                                   |

Ambos campos rechazados están [reservados](/docs/guides/sms/sending-sms#reserved-fields) y responden a `422 SMSUnsupportedFeature`.

Notas de portabilidad:

- **El array de destinatarios se convierte en una llamada por destinatario.** Una llamada de Connectivity Platform con 50 destinatarios se convierte en 50 envíos, o un [lote](/docs/guides/sms/sending-sms#batch-sending) de mensajes independientes. El lote no es un fan-out de un solo cuerpo: cada entrada lleva su propio destinatario, remitente y texto.
- **`datacoding` no tiene equivalente, y es intencional.** Bird detecta la codificación a partir del cuerpo e informa el recuento de segmentos en el mensaje. Si configuras `datacoding: auto` para mantener los mensajes dentro de GSM-7, el comportamiento más cercano es `options.smart_encoding`, que aplica la tabla de reemplazo documentada de Bird. No es un transliterador general; los caracteres no soportados pueden seguir requiriendo codificación Unicode.
- **`reference` se divide en dos campos.** Pon un identificador interno en `metadata`, que se refleja en cada evento de webhook, y usa `tags` para las etiquetas de baja cardinalidad por las que quieres filtrar y segmentar analíticas.
- **Los mensajes flash, los payloads binarios y la concatenación UDH no se portan.** Si dependes de `mclass` o `typeDetails` hoy, comunícalo a soporte antes de planificar la migración, no después.
- **¿También usas Verify API de Connectivity Platform?** La portabilidad es un trabajo aparte con su propia guía: consulta [Migrar Verify desde otro proveedor](/docs/guides/verify/migrate).

## Traslada las cancelaciones de suscripción

Connectivity Platform dejaba en tus manos la gestión de palabras clave de parada, ya fuera mediante Flows o en tu propia aplicación contra mensajes entrantes. Bird se encarga de eso: reconoce las palabras clave stop, start y help en tus números en los países admitidos, registra la supresión y la aplica en cada envío. Retira un handler antiguo solo después de confirmar que el catálogo de Bird cubre su comportamiento y que tu proceso de preferencias más amplio sigue funcionando.

Lo que no se retira es la lista. Exporta lo que mantengas hoy, como pares de número de suscriptor y el originador al que dejaron de responder, e impórtalo a través del [bucle de supresión](/docs/guides/sms/migrate#4-carry-over-your-opt-out-list) antes de tu primer envío en producción. Si solo mantenías una lista global de suscriptores que cancelaron la suscripción, importa cada suscriptor una vez por cada originador desde el que todavía envías.

## Traduce los informes de estado

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 petición API rechazada no crea ningún mensaje; un rechazo tras la aceptación puede producir `sms.rejected`, incluido un rechazo del operador. La ausencia de evidencia de entrega permanece como desconocida. Conserva el estado y código crudos del proveedor junto con tu resultado normalizado.

| Resultado                         | Connectivity Platform | Bird                              |
| --------------------------------- | --------------------- | --------------------------------- |
| Aceptado por la API               | (síncrono)            | `sms.accepted`                    |
| Entregado al operador             | `sent`, `buffered`    | `sms.sent`                        |
| El operador confirmó la entrega   | `delivered`           | `sms.delivered`                   |
| La entrega falló                  | `delivery_failed`     | `sms.failed`                      |
| La ventana de validez expiró      | `expired`             | `sms.expired`                     |
| Petición rechazada en la admisión | error de petición     | error HTTP; sin mensaje ni evento |
| En espera de envío                | `scheduled`           | sin equivalente aún               |

El mecanismo de entrega cambia más que el vocabulario:

- **Los posts firmados de JSON reemplazan los callbacks GET de `reportUrl`.** Los informes de estado llegaban como peticiones `GET` con el resultado en la query string (`status`, `statusReason`, `statusErrorCode`, `mccmnc`, `price[amount]`). Bird envía por `POST` un evento JSON a los endpoints que tu espacio de trabajo registra, firmado según [Standard Webhooks](https://www.standardwebhooks.com). El handler se reescribe, no es un simple cambio de URL.
- **La correlación ya no depende de `reference`.** Un informe de estado solo era útil si habías definido una referencia; un evento de Bird siempre incluye `sms_id`, ambos números, y tus `metadata` y `tags` reflejados.
- **La semántica de reintentos es diferente.** Connectivity Platform reintentaba un informe fallido hasta 10 veces. Las entregas de Bird son at-least-once y sin orden, así que deduplica con la cabecera `webhook-id` y ordena por el `timestamp` del payload.
- **Concilia el coste a través del mensaje y los responsables de facturación.** El informe de Connectivity Platform incluía `price[amount]` y `price[currency]`. Consulta el coste registrado del mensaje con [`GET /v1/sms/messages/{id}`](/docs/api/reference/get-sms-message) y concilia los cargos con facturación. La [Stats API](/docs/guides/sms/stats-api) es para métricas de entrega, no un total de facturación autoritativo.

Los mensajes entrantes funcionan igual: suscríbete a `sms.received` una vez para el espacio de trabajo en lugar de apuntar cada número a una URL.

## Migración final

Los [destinos](/docs/guides/sms/migrate#1-enable-your-destination-countries), [remitentes](/docs/guides/sms/migrate#2-set-up-a-sender) y la [rampa de tráfico](/docs/guides/sms/migrate#6-test-against-simulated-destinations) son independientes del proveedor y están cubiertos en la guía principal. Lo que conviene plantear pronto son tus originadores: los sender IDs alfanuméricos se recrean y, donde el país lo exija, se vuelven a registrar aquí, y los números que tienes en Connectivity Platform se trasladan mediante una portabilidad que soporte coordina, no un ajuste que tú activas.

## Próximos pasos

- [Explora Bird SMS](/products/sms): flujos de producto y rutas de implementación

- [Enviar SMS](/docs/guides/sms/sending-sms): el payload al que estás migrando, completo
- [Cancelaciones de suscripción y palabras clave](/docs/guides/sms/opt-outs-and-keywords): lo que Bird responde por ti y cómo gestionar las supresiones
- [Eventos de SMS](/docs/guides/sms/events): el vocabulario de eventos al que se traslada tu handler de estado
- [Webhooks y eventos](/docs/guides/webhooks): configuración de endpoints y verificación de Standard Webhooks

## Related resources

- [Choose a sender for your markets](/explained/sms/which-sms-sender-type-should-i-use) (answer)
- [Check your message segments](/tools/sms-segment-calculator) (tool)
- [Compare SMS providers](/products/sms/compare) (product)