Migrar SMS desde Telnyx
Esta página mapea la API Messages de Telnyx, los messaging profiles y los webhooks de entrega a Bird. Sigue la guía principal de migración en orden y usa estas correspondencias para los pasos 3, 4 y 5.
La llamada de envío es la más parecida a la de Bird entre todos los proveedores aquí: JSON, una clave bearer y los mismos nombres de campo. POST https://api.telnyx.com/v2/messages recibe from, to y text, y POST /v1/sms/messages también. Lo que no se traslada es el messaging profile. Telnyx lo convierte en la unidad de casi todo: pool de remitentes, URL de webhook, alcance de opt-out y configuración de palabras clave. Bird distribuye eso entre remitentes, suscripciones de webhook y supresiones. La mayor parte del trabajo en esta migración es descomponer ese objeto.
Pasa esto a tu agente
Usa este resumen en tu agente de código. Empieza 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 Telnyx 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/telnyx.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 Telnyx 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 | Telnyx | Bird |
|---|---|---|
| Destinatario | to | to (uno por solicitud) |
| Remitente | from o messaging_profile_id | from |
| Cuerpo | text | text |
| Intención | (ninguno) | category, obligatorio en texto libre |
| Reportes de entrega | la URL de webhook del perfil | un webhook del espacio de trabajo suscrito a los eventos de entrega de abajo |
| Contexto de ida y vuelta | tu propio almacén, indexado por ID | metadata: JSON arbitrario, devuelto en cada evento |
| Etiquetas filtrables | (ninguno) | tags: pares {name, value} |
| Reintentos seguros | (no documentado) | encabezado Idempotency-Key |
| Medios | media_urls | sin equivalente: media_urls se rechaza |
Notas de portabilidad:
- Un messaging profile ID se convierte en un valor de remitente simple. Telnyx resuelve el pool de números y sus reglas de envío detrás del perfil. Bird toma el remitente directamente en from, así que elígelo por envío, o usa un envío con plantilla, que selecciona un remitente válido para el destino y rechaza from.
- Nada en la API 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 predeterminado de marketing.
- Revisa la semántica de reintentos por separado. La referencia de envío de Telnyx no documenta clave de idempotencia, así que un timeout ahí te deja adivinando. Envía el encabezado Idempotency-Key desde el primer port.
Trasladar los opt-outs
Este es el paso que sorprende a la gente, y el número que debes calcular primero es en cuántas supresiones se convierte tu lista.
Telnyx limita un opt-out a todo el messaging profile: un suscriptor que envía STOP a cualquier número de un perfil queda bloqueado en todos los números de ese perfil, y un envío hacia él responde con el error 40300, "Blocked due to STOP message". Mantener listas de opt-out separadas para programas separados se logra manteniendo perfiles separados.
Bird limita una supresión a un par remitente-suscriptor. Así, un opt-out de Telnyx contra un perfil con doce números se convierte en doce supresiones Bird, y un perfil con cien números se convierte en cien. Cuenta antes de importar: el multiplicador es la cantidad de remitentes que trasladas desde ese perfil, y determina si la importación es un bucle de cientos o de decenas de miles.
Conserva la revocación a nivel de perfil en todos los remitentes relevantes. El almacenamiento a nivel de remitente no es permiso para reanudar un programa bajo otro número. Verifica si una preferencia a nivel de todo el espacio de trabajo es la representación adecuada de la solicitud real de la persona.
Importa a través del bucle de supresión. 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.
Recrea las palabras clave personalizadas y las respuestas automáticas configuradas en autoresp_configs como reglas de palabras clave de Bird. Un envío a un par suprimido se rechaza en la admisión con E12077 SMSRecipientSuppressed; un opt-out posterior es un resultado de entrega recipient_opted_out separado. Maneja ambas rutas al reemplazar el error 40300 de Telnyx.
Las razones se apilan en lugar de fusionarse, lo que importa una vez que el tráfico fluye: un par que importaste como manual y que luego envía STOP obtiene un segundo registro con razón keyword_stop, y los mensajes siguen detenidos hasta que cada registro de ese par haya terminado. Reanudar un suscriptor que una vez importaste significa eliminar ambos.
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 mensaje; un rechazo después de la aceptación puede producir sms.rejected, incluido un rechazo del operador. La evidencia de entrega faltante queda como desconocida. Conserva el estado y código crudos del proveedor junto con tu resultado normalizado.
| Resultado | Telnyx | Bird |
|---|---|---|
| API aceptó el mensaje | queued | sms.accepted |
| Entregado al operador | sent, en message.sent | sms.sent |
| El operador confirmó la entrega | delivered, en message.finalized | sms.delivered |
| Entrega fallida | delivery_failed | sms.undelivered |
| Fallo permanente | sending_failed | sms.failed |
| Solicitud rechazada en la admisión | error de solicitud | error HTTP; sin mensaje ni evento |
| Ventana de validez agotada | (ninguno) | sms.expired |
La forma del evento cambia, no solo las palabras. Telnyx envía un webhook message.finalized con el estado terminal en un campo status, así que tu handler ramifica según un valor dentro de un solo tipo de evento. Bird emite tipos de evento distintos, y te suscribes a los que quieras, así que la ramificación sale de tu código y pasa a la suscripción. Por eso la columna izquierda de arriba nombra un evento y un estado juntos, y la columna derecha nombra solo un evento.
Dos mecánicas más cambian junto con los nombres:
- Las suscripciones reemplazan la URL de webhook del perfil. Telnyx envía las actualizaciones de entrega a la URL del messaging profile, así que el destino es una propiedad del perfil por el que se envió cada mensaje. Bird entrega a endpoints que tu espacio de trabajo registra, cada uno suscrito a los tipos de evento que necesita, así que un segundo consumidor es una segunda suscripción en lugar de un cambio a un objeto compartido.
- Standard Webhooks reemplaza el esquema de firma de Telnyx. Bird envía JSON firmados según Standard Webhooks; sustituye la verificación por la receta en Webhooks & events.
Registra el endpoint una sola 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 un comodín que los sustituya. Crear un endpoint tiene el comando y lo único que debes acertar en la primera llamada: 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. Mapea tus alertas a esos códigos.
Corte de tráfico
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 Telnyx pertenecen al plan de corte: tu marca y campaña 10DLC están registradas en The Campaign Registry a través de Telnyx y no se convierten automáticamente en registros Bird. Confirma el procedimiento de migración o registro aplicable antes de enviar trabajo facturable. Los números que posees en Telnyx requieren una portabilidad que soporte gestiona, en su propio calendario y no en el tuyo.
Para los requisitos del lado de Bird, empieza por Registrarse para 10DLC: cubre qué significa cada campo, los tipos de entidad que reconoce el registro y la llamada de requisitos que te indica qué proporcionar antes de crear la marca, que es el paso facturable.
Próximos pasos
-
Comparar Bird y Telnyx para SMS: evaluación de producto y consideraciones de migración
-
Enviar SMS: el payload al que estás portando, 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 se traslada tu handler de webhook
-
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.