Sign inGet Started

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 platform support 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é haceTwilioBird
DestinatarioToto (uno por solicitud)
RemitenteFrom o MessagingServiceSidfrom, o un remitente del perfil indicado en messaging_profile_id
CuerpoBodytext
Plantilla de contenidoContentSid + ContentVariablesrevisa 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 salvo que un perfil de mensajería defina un valor por defecto
Etiquetas filtrables(ninguno)pares tags: {name, value}
Contexto de ida y vueltatu propio almacén, indexado por SIDmetadata: JSON arbitrario, reflejado en cada evento
Informes de entregaStatusCallbackun webhook del espacio de trabajo suscrito a los eventos descritos abajo, o options.callback_url
TransliteraciónSmartEncodedoptions.smart_encoding (por defecto false)
Reintentos seguros(ninguno en Messages)encabezado Idempotency-Key
ProgramaciónScheduleType + SendAtsin equivalente: scheduled_at se rechaza
MultimediaMediaUrlmedia_urls; el asunto o el contenido multimedia selecciona MMS
ValidezValidityPeriodvalidity_period, en segundos (60-172.800)
Acortamiento de enlacesShortenUrlssin equivalente

La programación sigue reservada y responde con 422 SMSUnsupportedFeature. Mantén la programación en tu aplicación.

MMS requiere texto o contenido multimedia, un destinatario +1 y un número con capacidad MMS que pertenezca a tu espacio de trabajo. Consume una unidad de mensaje con tarifas MMS propias. Enviar SMS explica el requisito de URL pública para el contenido multimedia y los límites de tamaño de los operadores.

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 en cada envío. Un perfil de mensajería indicado en messaging_profile_id selecciona el remitente según el país de destino: contiene un remitente para cada país y uno por defecto, y no tiene pool ni asignación fija. Un envío con plantilla 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 haces pruebas, incluidos +15005550006 y +15005550001, también producen aquí resultados simulados, con dos diferencias: no hay una credencial de prueba independiente y los envíos se facturan. Los resultados figuran 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 su REST API. Solicita una exportación mediante el proceso de soporte disponible y concíliala con tus propios registros de preferencias, registros de mensajes entrantes y solicitudes de soporte. Un registro 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.

ResultadoTwilio MessageStatusBird
API aceptó el mensajequeued, acceptedsms.accepted
Entregado al operadorsending, sentsms.sent
El operador confirmó la entregadeliveredsms.delivered
El operador informó de que no hubo entregaundeliveredsms.undelivered
Fallo permanentefailedsms.failed
Solicitud rechazada en la admisiónerror de solicituderror HTTP; sin mensaje ni evento
Ventana de validez expirada(ninguno)sms.expired cuando el operador informa de la expiración; sms.rejected o sms.failed cuando validity_period se agota antes de la entrega al operador
Programado o canceladoscheduled, canceledsin equivalente aún

Tres mecanismos cambian junto con los nombres:

  • Los endpoints son el receptor por defecto. Twilio envía al StatusCallback del mensaje o del Messaging Service. Bird entrega a los endpoints que registra tu espacio de trabajo, 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. Un mensaje o perfil de mensajería que necesite su propio receptor puede definir una URL de callback, que recibe los eventos de ese mensaje en lugar de tus endpoints.
  • 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 sola vez e indica los tipos de evento que necesita tu handler. Los eventos sms.* de la tabla anterior son la lista a la que debes suscribirte, y ningún comodín los sustituye. Crear un endpoint incluye el comando y explica por qué hay que enumerar el catálogo. También describe lo único que debes hacer bien en la primera llamada: 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 no dependen del proveedor y se explican en la guía principal. Dos elementos específicos de Twilio deben figurar en el plan de corte. Tu marca y tu 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 tienes en Twilio necesitan una portabilidad que gestiona el equipo de soporte, según 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

Continúa con la documentación, guías y ejemplos de este tema.