[Alpha] Cómo configurar el reenvío automático por SMS mediante la API (Fallback SMS) – Blip | Blip Help

Contexto

El reenvío automático por SMS (también llamado fallback SMS) es una funcionalidad que actúa como canal secundario de entrega para tus mensajes activos. Si el mensaje no se entrega en el canal original (WhatsApp o RCS) dentro de un periodo configurado, el sistema envía automáticamente el contenido por SMS al mismo contacto, lo que aumenta las posibilidades de entrega.

Esta guía muestra cómo configurar y operar esta funcionalidad directamente mediante la API de Campañas (Active Campaign), con el mismo comportamiento descrito en el artículo [Alpha] Cómo configurar el reenvío automático por SMS en Blip Marketing, pero para quienes se integran directamente con la API en lugar de usar Blip Marketing.

Antes de comenzar

Versión: Funcionalidad en fase Alpha. Para usarla, comunícate con tu equipo de atención y solicita que la habiliten.
Canal secundario: Debes tener el canal SMS contratado y configurado en tu cuenta de Blip.
Permisos de acceso: Acceso a la pestaña Blip Marketing en Contacto Inteligente.

La documentación a continuación se refiere al uso mediante la API. Si quieres usar la funcionalidad mediante el panel, consulta esta documentación.

Cómo funciona

Configuración del reenvío: al crear la campaña, incluyes el objeto fallback con el canal SMS y el texto que se enviará en este reintento.
Definición del mensaje SMS: el texto del reenvío lo escribes manualmente, de forma independiente del mensaje del canal principal, respetando los límites de caracteres del SMS.
Monitoreo de entrega: después del envío, el sistema verifica si el mensaje se entregó en el canal principal (WhatsApp o RCS) durante el periodo de monitoreo.
Activación del reenvío: una vez transcurrido este periodo sin confirmación de entrega en el canal principal, el sistema crea y envía automáticamente una campaña SMS solo a los destinatarios que tuvieron una falla.
Cobro: cada SMS reenviado se cobra de acuerdo con los costos contratados en tu cuenta para el canal SMS. Solo pagas por los SMS que se envían efectivamente.

No necesitas llamar a ningún endpoint para activar el reenvío: ocurre de forma automática y asíncrona después del envío de la campaña principal. Si ningún destinatario tiene una falla, no se envía ningún SMS de reenvío y no hay ningún cobro adicional.

Requisitos previos y limitaciones

El reenvío solo se puede configurar en campañas cuyo canal principal sea RCS (Google RCS) o WhatsApp. No es posible configurar el reenvío para una campaña que ya sea SMS.
Actualmente, el único canal de reenvío compatible es SMS.
Solo es posible configurar un reenvío por campaña (no hay reenvío en cadena ni varios canales de reenvío en paralelo).
No hay un nuevo reintento si falla el envío del SMS de reenvío.
El reenvío ocurre solo una vez por destinatario.
Después de crear una campaña con el reenvío configurado, no es posible editar esta configuración posteriormente mediante la API; la definición se realiza únicamente durante la creación.
El texto (message) del reenvío es obligatorio siempre que definas el canal de reenvío. Enviar el canal sin el mensaje genera un error de validación.

Configurar el reenvío automático por SMS mediante la API

Paso 1: Definir el reenvío al crear la campaña

El reenvío se configura dentro del propio payload de creación de la campaña (flujo paso a paso SET /campaigns o flujo combinado SET /campaign/full / SET /campaign/full/v2), mediante el campo fallback. Solo tienes que completar el objeto fallback para activarlo; no existe una bandera independiente para “activar/desactivar”.

Paso 2: Escribir el mensaje SMS

El mensaje enviado en el reenvío (fallback.message.messageContent) es independiente del mensaje del canal principal. Escribe un texto adaptado al contexto del SMS, manteniéndolo conciso y dentro del límite de caracteres (consulta Limitaciones y reglas del SMS).

Ejemplo: campaña RCS con reenvío automático por SMS configurado

{
  "campaign": {
    "id": "campaign-rcs-001",
    "name": "Campanha RCS - Aviso de vencimento",
    "campaignType": "BATCH",
    "channelType": "GoogleRCS",
    "fallback": {
      "channelType": "SMS",
      "message": {
        "channelType": "SMS",
        "messageContent": "Ola {{0}}, seu boleto de {{1}} vence amanha. Evite juros, pague em dia."
      }
    }
  },
  "audiences": [
    {
      "recipient": "+5511999990000",
      "recipientType": "PHONENUMBER",
      "channelType": "GoogleRCS",
      "messageParams": { "nome": "Maria", "valor": "R$ 150,00" }
    }
  ],
  "message": {
    "channelType": "GoogleRCS",
    "messageContent": "Ola {{nome}}, seu boleto de {{valor}} vence amanha."
  },
  "dispatch": true
}

Campos del objeto fallback

Campo	Obligatorio	Descripción
channelType	Sí, para habilitar el reenvío	Canal utilizado en el reintento. Actualmente, solo se admite SMS.
message	Sí, cuando se informa channelType	Objeto de mensaje (con el mismo formato usado en /messages) con el texto que se enviará en el reenvío.

Si envías fallback.channelType sin fallback.message, la creación de la campaña se rechaza con un error de validación y la campaña no llega a crearse.

Si no quieres configurar el reenvío, simplemente omite el campo fallback (o envía null).

Usar variables en el mensaje SMS

El mensaje de reenvío también admite variables para personalizar el contenido de acuerdo con los datos de cada destinatario.

Integración directa mediante la API (esta guía): usa {{0}} en messageContent, con los valores enviados en messageParams de cada elemento de la audiencia, siguiendo el mismo formato utilizado en los mensajes SMS comunes (consulta Cómo enviar mensajes SMS mediante la plataforma Blip).
Campañas creadas por Blip Marketing (portal): la sintaxis de la variable sigue el formato del canal principal configurado en el envío, como se describe en el artículo de Blip Help. RCS usa ${contact.extras.nome} y WhatsApp usa la posición numérica de la plantilla ({{0}}, {{1}}, ...). Usar el formato incorrecto hace que el texto literal de la variable aparezca en el mensaje enviado al contacto, sin sustitución.

El contador de caracteres considera la variable en sí (el texto del marcador) como parte del texto, no el valor final que se sustituirá para cada contacto. Deja un margen de seguridad al crear el mensaje, ya que los valores más largos (por ejemplo, nombres compuestos) pueden superar el límite aunque el texto del marcador esté dentro de él.

Limitaciones y reglas del SMS

Límite de caracteres

160 caracteres para texto simple (sin acentos, emojis ni símbolos especiales).
70 caracteres para texto con caracteres acentuados, emojis o símbolos especiales.

Este límite se aplica al mensaje final, ya con las variables sustituidas por el valor real de cada destinatario, no al texto sin procesar de messageContent antes de la sustitución.

Costo y facturación

El reenvío automático es opcional y está sujeto a costos adicionales. Cada SMS reenviado se cobra de acuerdo con tu contratación de SMS, las tarifas de los operadores y la cantidad de mensajes reenviados.

Periodo de monitoreo

El reenvío se activa automáticamente después del periodo de monitoreo configurado, sin confirmación de entrega en el canal principal.
Si el mensaje se entrega antes de ese periodo, el SMS de reenvío no se envía.
El reenvío ocurre solo una vez por destinatario.

Compatibilidad de contactos

Actualmente, el fallback de WhatsApp a SMS funciona exclusivamente para contactos identificados mediante números de teléfono. Los envíos que utilizan la identificación mediante BSUID no activarán el disparador de reenvío automático por SMS.

Enviar la campaña

No es necesario realizar ningún cambio en el envío: usa SET /dispatch (o dispatch: true en el flujo combinado) exactamente como en una campaña sin reenvío configurado. Consulta la guía Cómo enviar mensajes SMS mediante la plataforma Blip para conocer el formato del envío, que es el mismo independientemente del canal principal.

Después de que el envío se realiza correctamente, el monitoreo del reenvío comienza automáticamente; no necesitas hacer nada más.

Ver resultados

El reporte CSV de la campaña original incluye dos columnas adicionales cuando el reenvío está configurado:

Fell into fallback (Yes/No): indica si ese destinatario pasó al reenvío (es decir, si tuvo una falla en el canal original y se incluyó en la campaña SMS creada automáticamente).
Fallback status: estado de entrega del mensaje de reenvío para ese destinatario (los mismos valores utilizados en el estado normal de entrega), o - cuando no aplica.

GET /campaigns/{campaignId}/reports/csv

Este es el mismo endpoint de reporte que ya se utiliza para cualquier campaña; no se necesita ninguna llamada adicional para obtener los datos del reenvío:

Si la campaña no tiene reenvío configurado, el reporte se genera exactamente como antes, sin las columnas adicionales.
Si la campaña tiene el reenvío configurado, pero todavía no se ha creado ninguna campaña de reenvío (por ejemplo, porque aún está dentro del periodo de monitoreo o porque nadie tuvo una falla), todos los destinatarios aparecen con No y -.
Si la campaña de reenvío ya se creó, los destinatarios que pasaron a ella aparecen con Yes y el estado de entrega actual del SMS.

Cancelar el reenvío

No existe un endpoint específico para “cancelar solo el reenvío”. Al eliminar la campaña original (DELETE /campaigns/{campaignId}), el sistema automáticamente:

Cancela el monitoreo programado, si todavía no ha concluido.
Elimina la plantilla de mensaje de reenvío asociada a la campaña.

Si la campaña de reenvío ya se creó y se envió antes de eliminar la campaña original, no se ve afectada; la eliminación solo impide que se creen nuevos reenvíos a partir de ese momento.

Preguntas frecuentes (FAQ)

1. Si configuro el reenvío, ¿aumenta el costo de mi campaña?

Sí. Solo pagas por los SMS que se envían efectivamente. Si todos los contactos reciben el mensaje en WhatsApp/RCS dentro del periodo de monitoreo, no se envía ningún SMS ni hay ningún costo adicional.

2. ¿Puedo usar el mismo texto del mensaje principal para el SMS de reenvío?

No se recomienda. WhatsApp y RCS permiten mensajes más largos y con formato, mientras que el SMS está limitado a 160 caracteres (o 70 con acentos/especiales) y solo admite texto simple. Adapta fallback.message.messageContent al contexto del SMS.

3. ¿Cómo sé si el SMS de reenvío realmente se envió?

Consulta el reporte CSV de la campaña (GET /campaigns/{campaignId}/reports/csv): las columnas Fell into fallback y Fallback status muestran, por destinatario, si pasó al reenvío y cuál es el estado de entrega del SMS.

4. ¿El reenvío automático funciona para campañas individuales y masivas?

Sí. El campo fallback se admite en cualquier campaignType (INDIVIDUAL, BATCH, USERSFILTER, FROMCAMPAIGN), tanto en el flujo paso a paso como en /campaign/full y /campaign/full/v2.

5. ¿Puedo programar una campaña con el reenvío automático configurado?

Sí. Usa el campo scheduled normalmente al crear la campaña. El reenvío seguirá funcionando de acuerdo con la configuración, aplicando el periodo de monitoreo a partir del envío efectivo (inmediato o programado).

6. ¿Necesito llamar a algún endpoint para enviar el reenvío?

No. El envío del SMS de reenvío es automático, una vez transcurrido el periodo de monitoreo después del envío de la campaña principal.

7. ¿Puedo configurar el reenvío para una campaña que ya es SMS?

No. El reenvío está destinado a complementar campañas RCS o WhatsApp; la campaña de reenvío en sí ya es de tipo SMS.

8. ¿Qué sucede si varios destinatarios tienen una falla al mismo tiempo?

Todos se incluyen en la misma campaña de reenvío, creada una sola vez por campaña de origen (el sistema no crea una campaña de reenvío duplicada aunque la verificación se active más de una vez).

9. ¿Puedo saber el ID de la campaña de reenvío generada?

No se devuelve ningún ID de reenvío de forma síncrona (la creación es asíncrona). La forma de consultar el resultado es mediante el reporte CSV de la campaña original, que ya incluye el estado del reenvío por destinatario.

10. ¿Puedo cambiar el texto del reenvío después de crear la campaña?

No. La configuración del reenvío se define únicamente al crear la campaña y no se puede editar posteriormente mediante la API.

11. Si elimino la campaña antes del envío, ¿también se cancela el reenvío configurado?

Sí. Eliminar la campaña (DELETE /campaigns/{campaignId}) elimina la plantilla de reenvío y cancela cualquier monitoreo pendiente.

Buenas prácticas

Qué hacer:

Mantén el mensaje de reenvío breve y directo (entre 50 y 120 caracteres es una buena referencia).
Valida el tamaño de messageContent después de sustituir los valores de messageParams, no solo el texto con los marcadores.
Realiza pruebas con una audiencia pequeña antes de configurar el reenvío en campañas de gran volumen.
Monitorea las columnas Fell into fallback y Fallback status del reporte CSV para medir la efectividad del reenvío en tus campañas.

Qué evitar:

Usar acentos, emojis o símbolos especiales sin necesidad, ya que reducen el límite de caracteres de 160 a 70.
Enviar fallback.channelType sin fallback.message, ya que la creación de la campaña será rechazada.
Reutilizar sin adaptar el texto del mensaje principal (WhatsApp/RCS) como texto del SMS, sin considerar el límite de caracteres.

Solución de problemas

La creación de la campaña falla con un error de validación de fallback

Causa probable: se envió fallback.channelType sin fallback.message.
Solución: envía siempre el objeto message completo dentro de fallback al configurar el canal de reenvío.

El SMS de reenvío no se envió, incluso después del periodo de monitoreo

Causa probable: el destinatario no tiene un número de teléfono válido o no se registró ninguna falla en el canal principal para ese destinatario.
Solución: confirma que recipient de la audiencia sea un número válido y verifica el estado de entrega del canal principal en el reporte antes de esperar el reenvío.

Las columnas de reenvío no aparecen en el reporte CSV

Causa probable: la campaña no tiene fallback configurado o el periodo de monitoreo aún no ha terminado.
Solución: las columnas solo aparecen cuando fallback se definió al crear la campaña. Si todavía no ha transcurrido el periodo de monitoreo, los valores aparecerán como No/- hasta que se cree la campaña de reenvío.

¿Necesitas más ayuda? Explora nuestros contenidos en Blip Academy o Blip Community, mira tutoriales en nuestro canal de YouTube o resuelve tus dudas en nuestro canal de atención 😃