Migrar SMS desde Plivo
Esta página mapea la Message API, los Powerpacks y los callbacks de entrega de Plivo a Bird. Sigue la guía principal de migración en orden y usa estos mapeos para los pasos 3, 4 y 5.
El envío es la parte fácil. Ambos aceptan JSON con nombres de campo en minúsculas, y ambos mantienen el registro 10DLC junto al envío en lugar de en un host separado. Dos cosas cambian. La POST https://api.plivo.com/v1/Account/{auth_id}/Message/ de Plivo se autentica con un Auth ID y un Auth Token sobre HTTP Basic; POST /v1/sms/messages usa una clave bearer API contra tu host regional, sin segmento de cuenta en la ruta. Y un Powerpack de Plivo agrupa un pool de números, comportamiento de remitente fijo y estado de exclusión en un solo objeto; Bird los separa en remitentes, supresiones y reglas de palabras clave, así que no hay nada que recrear como Powerpack.
Pasa esto a tu agente
Usa este brief 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 Plivo 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/plivo.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 Plivo 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 | Plivo | Bird |
|---|---|---|
| Destinatario | dst | to (uno por solicitud) |
| Remitente | src o powerpack_uuid | from |
| Cuerpo | text | text |
| Selector de canal | type: sms, mms, whatsapp | el propio endpoint; /v1/sms/messages es SMS |
| Intención | (ninguno) | category, obligatorio en texto libre |
| Reportes de entrega | url + method, por mensaje | un webhook del espacio de trabajo; solo JSON POST, ver abajo |
| Contexto de ida y vuelta | tu propio almacén, indexado por UUID | metadata: JSON arbitrario, devuelto en cada evento |
| Etiquetas filtrables | (ninguno) | tags: pares {name, value} |
| Reintentos seguros | (sin documentar) | cabecera Idempotency-Key |
| Multimedia | media_urls | sin equivalente: media_urls se rechaza |
Notas de portabilidad:
- Un UUID de Powerpack se convierte en un valor de remitente simple. Plivo resuelve el pool de números, el remitente fijo y la presencia local detrás del UUID. 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.
- type no tiene equivalente porque el endpoint ya lo determina. Plivo selecciona el canal por solicitud; los canales SMS, WhatsApp y otros de Bird son endpoints separados. Un código que cambia type en tiempo de ejecución se divide en llamadas a diferentes endpoints.
- Nada en la Message API 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 Plivo no documenta ninguna clave de idempotencia ni mecanismo de deduplicación, así que un timeout te deja adivinando. Envía la cabecera Idempotency-Key desde la primera portabilidad para reducir el riesgo de solicitudes duplicadas dentro de la ventana de repetición de tres horas; no es una garantía de entrega exactamente una vez.
Trasladar las exclusiones
El servicio DND de Plivo bloquea mensajes salientes de un número Plivo a un destino una vez que ese destino responde con una palabra clave de exclusión. Un envío bloqueado regresa marcado con el código de error 200 de Plivo, que es uno de sus códigos de error de mensajes y no un estado HTTP, por mucho que lo parezca. Ese emparejamiento es también cómo funciona una supresión de Bird: un remitente y un suscriptor, así que el alcance importado debe cubrir cada remitente y programa incluido en la solicitud de la persona.
Una cosa se expande, y es la razón para contar antes de importar. Dentro de una campaña US 10DLC, Plivo trata una exclusión de cualquier número como una exclusión de todos los números vinculados a esa campaña. Bird almacena pares, así que un suscriptor que se excluyó de una campaña de cuatro números se convierte en cuatro supresiones en lugar de una. Calcula cuántos pares genera tu lista antes de empezar, porque eso decide si la importación es un bucle de decenas o de miles.
Extraer la lista es una exportación desde la consola, no una llamada API: filtra los números en la consola de Plivo, selecciónalos y usa Export CSV desde el menú Choose Action. Importa el resultado a través del bucle de supresión. 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.
Bird gestiona las palabras clave de parada compatibles a través de su catálogo por país. Un envío a un par suprimido se rechaza en la admisión con E12077 SMSRecipientSuppressed. Una exclusión reportada por el operador es un resultado de entrega recipient_opted_out separado. Reemplaza el manejo del código de error 200 de Plivo con las rutas de admisión y entrega correspondientes, y recrea cualquier respuesta personalizada como reglas de palabras clave.
Eso importa de nuevo más adelante, cuando el tráfico esté fluyendo. Las razones se apilan en lugar de fusionarse: 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. Así que reactivar un suscriptor que una vez importaste significa eliminar ambos, y una reactivación que borra solo el registro de palabra clave parece exitosa pero no cambia nada.
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 faltante permanece como desconocida. Conserva el estado y código crudos del proveedor junto a tu resultado normalizado.
| Resultado | Plivo message_state | Bird |
|---|---|---|
| API aceptó el mensaje | queued | sms.accepted |
| Entregado al operador | sent | sms.sent |
| El operador confirmó la entrega | delivered | sms.delivered |
| El operador reportó no entrega | undelivered | sms.undelivered |
| Fallo permanente | failed | sms.failed |
| Rechazado antes de enviar | rejected | sms.rejected |
| Ventana de validez expirada | (ninguno) | sms.expired |
Dos mecánicas cambian junto con los nombres:
- Los endpoints reemplazan las URLs de callback por mensaje. Plivo recibe un url en cada envío, así que el destino lo elige quien escribe la llamada. Bird entrega a endpoints que tu espacio de trabajo registra, cada uno suscrito a los tipos de evento que desea, así que un nuevo consumidor es una nueva suscripción en lugar de un cambio en cada punto de llamada.
- Los posts firmados JSON reemplazan un callback GET, si eso es lo que elegiste. El method de Plivo selecciona GET o POST para el reporte de entrega; Bird hace POST de un evento JSON y no ofrece GET. Si configuraste method=GET, tu handler lee el resultado de los parámetros del query string, y ese handler es una reescritura, no un nuevo registro. Lo mismo aplica en la guía contigua, en la ruta de Connectivity Platform.
- Un esquema de firma reemplaza tres cabeceras. Plivo firma los callbacks con X-Plivo-Signature-V2, X-Plivo-Signature-Ma-V2 y X-Plivo-Signature-V2-Nonce. Bird envía JSON firmados según Standard Webhooks, así que el verificador se reemplaza en lugar de ajustarse: cámbialo por la receta en Webhooks y eventos.
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 un comodín que los represente a todos. Crear un endpoint tiene el comando y lo único que debes hacer bien en la primera llamada: almacenar el secreto de firma que la respuesta muestra una sola vez.
Los valores numéricos error_code de Plivo no tienen un mapeo 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. Mapea tus alertas a esos.
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 Plivo pertenecen al plan de corte.
Tu marca y campaña 10DLC están registradas en The Campaign Registry a través de Plivo y no se convierten automáticamente en registros Bird. Confirma el procedimiento de migración o registro aplicable antes de enviar trabajo de pago. La cadena es más corta aquí. Plivo registra primero un perfil y luego una marca contra él, bajo /v1/Account/{auth_id}/10dlc/; Bird no tiene objeto de perfil, así que los datos del negocio que Plivo almacena en el perfil se proporcionan directamente en la marca. Empieza desde 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 con cargo.
Los números que posees en Plivo necesitan una portabilidad que soporte gestiona, en su propio calendario, no en el tuyo. Iníciala pronto y se ejecuta en paralelo con el cambio de código.
Próximos pasos
-
Comparar Bird y Plivo para SMS: evaluación de producto y consideraciones de migración
-
Enviar SMS: el payload al que estás portando, completo
-
Exclusiones y palabras clave: cobertura de palabras clave por país y gestión de supresiones
-
Eventos SMS: el vocabulario de eventos al que se traslada tu handler de callbacks
-
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.