Migrar SMS desde Twilio
Esta página asocia la API Programmable Messaging de Twilio, los Messaging Services y los callbacks de estado con Bird. Sigue la guía principal de migración en orden y usa estas correspondencias para los pasos 3, 4 y 5.
Dos diferencias definen toda la migración. La POST /2010-04-01/Accounts/{AccountSid}/Messages.json de Twilio recibe parámetros PascalCase codificados como formulario, autenticados con tu Account SID y Auth Token; POST /v1/sms/messages recibe JSON autenticado con una clave bearer API contra tu host regional. Además, un Messaging Service de Twilio puede agrupar selección de remitente, gestión de exclusiones y configuración de callbacks. Asocia cada comportamiento por separado al propietario de Bird; renombrar su SID a un valor de remitente no preserva el servicio completo.
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 Twilio 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 https://bird.com/docs/guides/sms/migrate/twilio.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 Twilio 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.Asociar la llamada de envío
| Qué hace | Twilio | Bird |
|---|---|---|
| Destinatario | To | to (uno por solicitud) |
| Remitente | From o MessagingServiceSid | from |
| Cuerpo | Body | text |
| Plantilla de contenido | ContentSid + ContentVariables | revisa el contenido por separado; las plantillas de sistema de Bird no son una importación de Twilio Content |
| Intención | (ninguno) | category, obligatorio en texto libre |
| Etiquetas filtrables | (ninguno) | pares tags: {name, value} |
| Contexto de ida y vuelta | tu propio almacén, indexado por SID | metadata: JSON arbitrario, reflejado en cada evento |
| Informes de entrega | StatusCallback | un webhook del espacio de trabajo suscrito a los eventos de entrega descritos abajo |
| Transliteración | SmartEncoded | options.smart_encoding (por defecto false) |
| Reintentos seguros | (ninguno en Messages) | encabezado Idempotency-Key |
| Programación | ScheduleType + SendAt | sin equivalente: scheduled_at se rechaza |
| Multimedia | MediaUrl | sin equivalente: media_urls se rechaza |
| Validez | ValidityPeriod | sin equivalente: validity_period se rechaza |
| Acortamiento de enlaces | ShortenUrls | sin equivalente |
Los tres campos rechazados están reservados y responden a 422 SMSUnsupportedFeature. Mantén la programación y la gestión de multimedia donde están por ahora.
Notas de migración:
- Resuelve los comportamientos del Messaging Service por separado. Twilio resuelve el pool de remitentes, el remitente fijo (sticky sender) y la coincidencia geográfica (geomatch) detrás del SID. Bird recibe el remitente directamente en from, así que elige el remitente por envío, o usa un envío con plantilla, que selecciona un remitente válido para el destino y rechaza from.
- Un límite de caracteres se convierte en un límite de segmentos. Las longitudes resultan similares para texto GSM-7, pero el comportamiento ante el fallo no: Bird nunca trunca, así que un cuerpo que exceda la longitud se rechaza con un 422 en lugar de recortarse.
- Nada en la API de Messages corresponde a category. Decide por tipo de mensaje si es transactional, marketing, authentication o service. El tráfico de autenticación en particular debe etiquetarse como tal en lugar de dejarse en un valor por defecto de marketing.
- Las credenciales de prueba de Twilio se corresponden con destinos simulados. Los números mágicos con los que ya pruebas, incluidos +15005550006 y +15005550001, producen resultados sintetizados aquí también, con dos diferencias: no hay una credencial de prueba separada, y los envíos se facturan. Los resultados se listan en la guía principal.
Trasladar las exclusiones
Twilio puede limitar una exclusión a un número o a un Messaging Service. Una solicitud a nivel de servicio puede abarcar varios remitentes. Conserva esa amplitud al importar en las supresiones de remitente-y-suscriptor de Bird, o usa la preferencia de espacio de trabajo correspondiente para una solicitud genuinamente global.
La documentación de Advanced Opt-Out de Twilio indica que los informes de números bloqueados no se exponen a través de su Console ni de REST API. Solicita una exportación a través del proceso de soporte disponible y concilia con tus propios registros de preferencias, logs de entrada y solicitudes de soporte. Un log de palabras clave por sí solo puede estar incompleto.
Importa el resultado revisado a través del flujo de supresiones. Una supresión manual bloquea todas las categorías para ese par, así que verifica el alcance previsto en lugar de restringirlo o ampliarlo silenciosamente.
El 21610 de Twilio señala un destinatario que se ha excluido. En Bird, un par suprimido se rechaza en la admisión con E12077 SMSRecipientSuppressed, antes de que exista un mensaje. El error de entrega recipient_opted_out en cambio reporta una exclusión posterior. Revisa la cobertura de palabras clave de Bird antes de retirar cualquier handler existente, y conserva los mecanismos de exclusión fuera del catálogo integrado.
Traducir 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 del proveedor sin procesar junto con tu resultado normalizado.
| Resultado | Twilio MessageStatus | Bird |
|---|---|---|
| API aceptó el mensaje | queued, accepted | sms.accepted |
| Entregado al operador | sending, sent | sms.sent |
| El operador confirmó la entrega | delivered | sms.delivered |
| El operador reportó no entrega | undelivered | sms.undelivered |
| Fallo permanente | failed | sms.failed |
| Solicitud rechazada en admisión | error de solicitud | error HTTP; sin mensaje ni evento |
| Ventana de validez expirada | (ninguno) | sms.expired |
| Programado o cancelado | scheduled, canceled | sin equivalente aún |
Tres mecanismos cambian junto con los nombres:
- Los endpoints reemplazan las URL de callback. Twilio envía al StatusCallback del mensaje o del Messaging Service. Bird entrega a endpoints que tu espacio de trabajo registra, cada uno suscrito a los tipos de evento que necesita, así que un nuevo consumidor es una nueva suscripción en lugar de un redespliegue.
- JSON firmado reemplaza los posts codificados como formulario. Twilio envía application/x-www-form-urlencoded con un encabezado X-Twilio-Signature; Bird envía JSON firmado según Standard Webhooks. Sustituye la verificación por la receta en Webhooks & events.
- Los mensajes entrantes llegan como eventos. El webhook "A message comes in" por número de Twilio espera una respuesta TwiML que tu app puede usar para responder automáticamente. Bird emite sms.received al mismo endpoint suscrito que todo lo demás, y no hay un cuerpo de respuesta que envíe una réplica: responde llamando al endpoint de envío, o deja que las reglas de palabras clave respondan por ti.
Registra el endpoint una vez, indicando los tipos de evento que tu handler necesita: los eventos sms.* en la tabla anterior son la lista a la que suscribirte, y no hay un comodín que los represente. Crear un endpoint tiene el comando, por qué el catálogo debe enumerarse, y lo único que debes hacer bien en la primera llamada, que es guardar el secreto de firma que la respuesta muestra una sola vez.
Los códigos de error numéricos de Twilio no tienen correspondencia uno a uno. 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. Asocia tus alertas a esos en lugar de a los códigos del rango 30000.
Corte de tráfico
Los destinos, los 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 Twilio pertenecen al plan de corte: tu marca y campaña 10DLC están registradas en The Campaign Registry a través de Twilio y no se convierten automáticamente en registros de Bird. Confirma el procedimiento de migración o registro aplicable antes de enviar trabajo facturable. Los números que posees en Twilio necesitan una portabilidad que soporte gestiona, con su propio calendario y no 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 dice qué proporcionar antes de crear la marca, que es el paso facturable.
Siguientes pasos
-
Comparar Bird y Twilio para SMS: evaluación de producto y consideraciones de migración
-
Enviar SMS: el payload al que estás migrando, completo
-
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 se traslada tu handler de estados
-
Webhooks & events: 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.