Migrar SMS desde otro proveedor

1. Habilita tus países de destino
2. Configura un remitente
3. Adapta la llamada de envío a POST /v1/sms/messages
4. Traslada tu lista de exclusiones voluntarias
5. Redirige los informes de entrega a webhooks
6. Prueba contra destinos simulados antes del corte

1. Habilita tus países de destino

2. Configura un remitente

• Los sender ID alfanuméricos los creas tú bajo SMS > Senders. Si el país de destino requiere que el sender ID esté registrado, envía el registro allí y espera la aprobación antes de dirigir tráfico hacia él.
• El tráfico comercial en EE. UU. a través de códigos largos locales necesita la marca y campaña 10DLC correspondientes, configuradas en SMS > 10DLC, mientras que los números gratuitos y los códigos cortos dedicados tienen sus propios programas de verificación o solicitud. EE. UU. no acepta sender ID alfanuméricos en absoluto, por lo que un sender ID europeo que funciona en todas partes no tiene equivalente en EE. UU.
• Los números se obtienen a través del flujo de Numbers, con disponibilidad y aprovisionamiento gestionado que dependen del tipo y el destino. Consulta números de SMS para la ruta correcta; añadir un remitente alfanumérico no adquiere un número.
• Conservar tus números actuales no es autoservicio: Bird no tiene un flujo de portabilidad que puedas ejecutar desde el panel. Si tus suscriptores responden a números que posees hoy, inicia la portabilidad con soporte antes de programar una fecha de corte, y planifica que la portabilidad y el cambio de código sean eventos separados.

3. Adapta la llamada de envío

• Un destinatario por solicitud. Bird no tiene un array de destinatarios. Si tu proveedor actual distribuye una llamada a muchos números, eso se convierte en una llamada por destinatario, o un lote de mensajes independientes en una sola solicitud.
• category es obligatorio en texto libre, y es transactional, marketing, authentication o service. La mayoría de proveedores infieren la intención de la campaña o el remitente; aquí lo declaras por mensaje, y cuando el país de destino requiere que el remitente esté registrado, ese registro se aprueba para una categoría y un envío fuera de ella se rechaza con 422 SenderCategoryNotPermitted. El estado active del remitente no puede indicarte esto de antemano, porque se reporta sin referencia a ninguna categoría; consulta los requisitos por país en su lugar. Configúralo correctamente en la portabilidad en vez de asignar todo a un solo valor.
• El cuerpo está limitado en segmentos, y Bird no trunca. Un cuerpo más largo se rechaza con un 422. Los caracteres fuera de GSM-7 reducen a menos de la mitad lo que cabe en un segmento, así que si tu proveedor actual transliteraba silenciosamente comillas tipográficas y guiones, activa options.smart_encoding para mantener los conteos de segmentos a los que estás acostumbrado. Está desactivado por defecto porque altera el cuerpo que compusiste.
• Usa tags para dimensiones de filtrado y metadata para contexto. Los tags son pares {name, value} por los que puedes filtrar y segmentar analíticas; los metadatos son JSON arbitrarios que Bird almacena, devuelve en lecturas y repite en cada evento de webhook. Un campo de referencia de cliente único en tu proveedor anterior normalmente se mapea a metadata.
• La programación de envíos individuales y MMS saliente necesitan un plan aparte. scheduled_at, media_urls, validity_period y personalization por destinatario son campos reservados, rechazados con 422 SMSUnsupportedFeature. Esas partes de tu integración no se mueven con el resto: mantén los envíos programados en tu propia cola y llama al endpoint de envío en el momento de envío previsto. Para campañas de audiencia, evalúa Broadcasts por separado; un broadcast no es un renombramiento de campo del endpoint.
• Usa Idempotency-Key para reintentos acotados. Envía una clave única por mensaje lógico y reutilízala para reintentos de la solicitud idéntica dentro de la ventana de repetición de tres horas. Las repeticiones reducen solicitudes duplicadas, pero no son una garantía de entrega exactamente una vez. Consulta Idempotency.

4. Traslada tu lista de exclusiones voluntarias

while IFS=, read -r destination originator; do
  curl -s -X POST https://us1.platform.bird.com/v1/sms/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destination\": \"$destination\", \"originator\": \"$originator\"}"
done < opt-outs.csv

• Ambos extremos son obligatorios para supresiones específicas por remitente. Una exclusión voluntaria a nivel del espacio de trabajo pertenece al preference owner separado. La llamada es idempotente: 201 registra una nueva supresión, 200 devuelve la manual ya existente, así que volver a ejecutar una importación parcial es seguro.
• Los pares importados reciben reason: manual, que bloquea todas las categorías incluida la transaccional. Eso es más estricto que una supresión que Bird registra por sí mismo a partir de una palabra clave de parada. Si un suscriptor solo rechazó marketing, decide deliberadamente si importar ese par.

5. Redirige los informes de entrega a webhooks

• Las entregas se firman según Standard Webhooks, usando los headers webhook-id, webhook-timestamp y webhook-signature con un HMAC-SHA256 sobre {id}.{timestamp}.{raw body}. Los proveedores que firman con su propio esquema necesitan que se reemplace la verificación; la receta está en Webhooks & events.
• La entrega es al menos una vez y sin orden. Deduplica por webhook-id y ordena por el timestamp del payload, nunca por orden de llegada.

6. Prueba contra destinos simulados

• Son números de EE. UU., así que Estados Unidos debe estar habilitado en Destinations, y from debe ser un remitente válido para EE. UU. Un sender ID alfanumérico se rechaza allí.
• Un envío simulado se factura a la tarifa normal del destino. Nada llega a un dispositivo, pero el cargo en la billetera es real, así que dimensiona tu prueba de humo en consecuencia.
• El resultado depende solo del destino. No hay una credencial de prueba separada ni un modo de prueba que desactivar.

Migrar desde un proveedor específico

• Twilio: PascalCase form-encoded a JSON, Messaging Services a remitentes, StatusCallback a webhooks suscritos
• Plivo: src y dst a from y to, Powerpacks a remitentes, pares DND a supresiones
• Telnyx: el envío más parecido al de Bird, perfiles de mensajería separados en remitentes y suscripciones, exclusiones voluntarias a nivel de perfil a pares
• Bandwidth: dos hosts a uno, callbacks applicationId a webhooks del espacio de trabajo, y una lista de exclusiones voluntarias que tu propia aplicación ya mantiene
• Sinch: lotes a envíos individuales, body a text, membresía de grupo reconstruida como supresiones
• Infobip: un payload de tres niveles aplanado, una URL base por cuenta a un host regional, una Blocklist expandida a pares
• Bird Connectivity Platform: el rest.messagebird.com API, originator y recipients a from y to, callbacks GET reportUrl a webhooks firmados

Próximos pasos

• Comparar proveedores de SMS: evalúa el flujo de producto y las consideraciones de migración
• Enviar SMS: el payload de envío completo, remitentes, segmentos y el modelo asíncrono 202
• Exclusiones voluntarias y palabras clave: lo que Bird responde por ti y cómo gestionar supresiones
• Eventos de SMS: el vocabulario de eventos y los payloads por evento
• Webhooks & events: configuración de endpoints, verificación de firma, reintentos y repetición