Saltar al contenido principal

[Alpha] Cómo configurar la API de fallback de WhatsApp para Google RCS

  • Actualización
  1. Resumen
  2. Contrato de datos común
  3. Pasos para la integración
  4. Consejos y validaciones

 

Resumen

La funcionalidad de fallback permite recuperar la entrega de mensajes en campañas activas. El proceso evalúa los intentos de envío del canal principal y copia automáticamente a los destinatarios elegibles cuyas entregas fallaron a una campaña secundaria en el canal de destino. Esta guía está restringida a la integración en la que el canal principal es WhatsApp y el canal de fallback es GoogleRCS.

Antes de comenzar

  • Canal principal: WHATSAPP.

  • Canal de fallback: GoogleRCS.

  • Endpoint de comandos LIME: POST https://<owner-domain>/commands

  • Identidad del servicio Active Campaign: postmaster@activecampaign.msging.net

  • Autenticación: Header Authorization: Key <auth-key>

  • Identificador único: Todo comando enviado debe contener un parámetro id exclusivo.

  • Correspondencia de tipos: El atributo type del recurso en el sobre de la solicitud debe corresponder exactamente al tipo de recurso enviado.

  • Evaluación secuencial: El fallback se evalúa después del lanzamiento de la campaña principal; no se ejecuta como una segunda campaña paralela.

 

Contrato de datos común

Fallback de la campaña

La estructura de fallback se declara dentro del objeto campaign:

{
  "fallback": {
    "channelType": "GoogleRCS",
    "message": {
      "channelType": "GoogleRCS",
      "messageContent": "Hola ${contact.extras.name}, tu mensaje de WhatsApp no se entregó.",
      "messageParams": ["name"]
    }
  }
}

  • El objeto fallback.message es obligatorio siempre que el objeto fallback esté presente en la solicitud.

  • El mensaje de fallback debe utilizar el mismo canal configurado en fallback.channelType.

  • Mientras que el mensaje principal de una campaña de WhatsApp utiliza una plantilla aprobada, el mensaje de fallback es independiente y debe crearse específicamente para el canal Google RCS.

Detalle de los campos:

  • fallback.channelType (Obligatorio): Debe completarse como "GoogleRCS".

  • fallback.message.channelType (Obligatorio): Debe ser exactamente igual a fallback.channelType ("GoogleRCS").

  • fallback.message.messageContent (Obligatorio): Texto o cuerpo del mensaje que se enviará en el canal RCS.

  • fallback.message.messageParams (Opcional): Lista con los nombres de los parámetros dinámicos referenciados en messageContent.

Parámetros dinámicos

Siempre que el texto en messageContent contenga variables con el formato ${contact.extras.<name>}, declara los nombres correspondientes en la lista messageParams:

{
  "messageContent": "Hola ${contact.extras.name}. Consulta la información en ${contact.extras.url}.",
  "messageParams": ["name", "url"]
}

  • El registro de la audiencia proporcionará los valores para completar los parámetros declarados en messageParams.

Sobre de comando LIME

Todas las llamadas utilizan la siguiente estructura del sobre LIME:

{
  "id": "<unique-command-id>",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "<resource-uri>",
  "type": "<resource-media-type>",
  "resource": {}
}

  • method: Usa "set" para crear, actualizar y lanzar recursos. Usa "get" para leer recursos y "delete" para eliminarlos.

 

Pasos para la integración

Puedes realizar la integración mediante dos flujos operativos: Flujo incremental (paso a paso) o Flujo completo (operación única).

Flujo incremental

Paso 1: Crear la campaña en /campaigns

Usa este procedimiento para registrar la campaña y almacenar la configuración de fallback. Este paso no crea los mensajes ni la audiencia.

  • URI: /campaigns

  • Type: application/vnd.iris.activecampaign.campaign+json

Solicitud:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c401",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaigns",
    "type": "application/vnd.iris.activecampaign.campaign+json",
    "resource": {
      "name": "Campaña de WhatsApp con fallback de RCS",
      "channelType": "WHATSAPP",
      "campaignType": "INDIVIDUAL",
      "fallback": {
        "channelType": "GoogleRCS",
        "message": {
          "channelType": "GoogleRCS",
          "messageContent": "Hola ${contact.extras.name}, tu mensaje de WhatsApp no se entregó.",
          "messageParams": ["name"]
        }
      }
    }
  }'

  • Importante: Guarda el id de la campaña que se devuelve en la respuesta de la solicitud. Se utilizará en los siguientes pasos (/messages, /audiences y /dispatch).

Paso 2: Configurar el mensaje principal en /messages

Agrega la plantilla de mensaje que utilizará el canal principal (WhatsApp).

  • URI: /messages/<campaign-id>

  • Type: application/vnd.iris.activecampaign.message+json

Solicitud:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c402",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/messages/<campaign-id>",
    "type": "application/vnd.iris.activecampaign.message+json",
    "resource": {
      "channelType": "WHATSAPP",
      "messageTemplate": "pedido_entregue",
      "messageTemplateLanguage": "pt_BR"
    }
  }'

  • Atención: No envíes el mensaje de fallback en esta llamada; el mensaje del canal RCS ya se almacenó en el registro de la campaña (Paso 1).

  • Consultas: Para consultar los mensajes registrados en una campaña, envía un comando get a la URI /messages/{campaignId} o /messages/{campaignId}/{channelType}.

Paso 3: Agregar destinatarios en /audiences

Registra la audiencia de la campaña principal. El canal informado en los registros de audiencia debe corresponder al canal principal (WHATSAPP).

  • URI: /audiences/<campaign-id>

Opción A: Destinatario único

  • Type: application/vnd.iris.activecampaign.audience+json

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c403",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/audiences/<campaign-id>",
    "type": "application/vnd.iris.activecampaign.audience+json",
    "resource": {
      "recipient": "+5511999999999",
      "recipientType": "PhoneNumber",
      "channelType": "WHATSAPP",
      "messageParams": {
        "name": "María"
      }
    }
  }'
Opción B: Varios destinatarios (Colección LIME)

  • Type: application/vnd.lime.collection+json

{
  "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c404",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/audiences/<campaign-id>",
  "type": "application/vnd.lime.collection+json",
  "resource": {
    "itemType": "application/vnd.iris.activecampaign.audience+json",
    "items": [
      {
        "recipient": "+5511999999999",
        "recipientType": "PhoneNumber",
        "channelType": "WHATSAPP",
        "messageParams": {
          "name": "María"
        }
      },
      {
        "recipient": "+5511888888888",
        "recipientType": "PhoneNumber",
        "channelType": "WHATSAPP",
        "messageParams": {
          "name": "João"
        }
      }
    ]
  }
}

  • Regla de audiencia: El mecanismo de fallback reasigna automáticamente la audiencia elegible al canal Google RCS. No crees manualmente una segunda audiencia de fallback.

Paso 4: Ejecutar el lanzamiento en /dispatch

Inicia el envío de la campaña. Cuando el fallback está configurado, la ejecución del lanzamiento programa la verificación automática de fallas.

  • URI: /dispatch (o /dispatch/v2 para campañas dinámicas)

  • Type: application/vnd.iris.activecampaign.campaign+json

Solicitud:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c405",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/dispatch",
    "type": "application/vnd.iris.activecampaign.campaign+json",
    "resource": {
      "id": "<campaign-id>"
    }
  }'

  • Opciones adicionales: Puedes incluir las propiedades isToUseLiteApi, canSendWithOpenTicket y usersFilter dentro de resource si tu operación lo requiere.

Flujo completo (creación y lanzamiento en una sola solicitud)

Operación mediante /campaign/full

Este endpoint crea la campaña, define el mensaje principal, registra la audiencia y puede realizar el lanzamiento de forma simultánea. Admite los tipos de campaña INDIVIDUAL, GROUP, BATCH, USERSFILTER y FROMCAMPAIGN.

  • URI: /campaign/full

  • Type: application/vnd.iris.activecampaign.full-campaign+json

Solicitud:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c406",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaign/full",
    "type": "application/vnd.iris.activecampaign.full-campaign+json",
    "resource": {
      "campaign": {
        "name": "Fallback de WhatsApp para RCS",
        "channelType": "WHATSAPP",
        "campaignType": "INDIVIDUAL",
        "fallback": {
          "channelType": "GoogleRCS",
          "message": {
            "channelType": "GoogleRCS",
            "messageContent": "Hola ${contact.extras.name}, estamos enviando tu mensaje por RCS.",
            "messageParams": ["name"]
          }
        }
      },
      "message": {
        "channelType": "WHATSAPP",
        "messageTemplate": "pedido_entregue",
        "messageTemplateLanguage": "pt_BR"
      },
      "audiences": [
        {
          "recipient": "+5511999999999",
          "recipientType": "PhoneNumber",
          "channelType": "WHATSAPP",
          "messageParams": {
            "name": "María"
          }
        }
      ],
      "dispatch": true
    }
  }'

  • Define "dispatch": false si deseas crear la estructura completa sin realizar el lanzamiento inmediato.

Operación mediante /campaign/full/v2

Se utiliza para el flujo dinámico de campañas por lotes (BATCH) o por filtro de usuarios (USERSFILTER).

  • URI: /campaign/full/v2

  • Type: application/vnd.iris.activecampaign.full-campaign+json

Ejemplo con envío BATCH:

{
  "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c407",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/full/v2",
  "type": "application/vnd.iris.activecampaign.full-campaign+json",
  "resource": {
    "campaign": {
      "name": "Lote de WhatsApp con fallback de RCS",
      "channelType": "WHATSAPP",
      "campaignType": "BATCH",
      "fileUrl": "https://<media-host>/audience.csv",
      "fallback": {
        "channelType": "GoogleRCS",
        "message": {
          "channelType": "GoogleRCS",
          "messageContent": "Hola ${contact.extras.name}, tu mensaje se está reenviando por RCS.",
          "messageParams": ["name"]
        }
      }
    },
    "message": {
      "channelType": "WHATSAPP",
      "messageTemplate": "pedido_entregue",
      "messageTemplateLanguage": "pt_BR"
    },
    "dispatch": true
  }
}

  • En campañas de tipo BATCH, la lista de contactos se proporciona mediante el campo fileUrl.

 

Consejos y validaciones

Errores comunes y reglas de validación

La API rechazará la solicitud si se infringe cualquiera de las siguientes reglas:

  1. Presencia del objeto fallback sin la propiedad fallback.message.

  2. Diferencia entre fallback.message.channelType y fallback.channelType.

  3. Definición del canal de fallback idéntico al canal principal de la campaña.

  4. Valor de fallback.channelType diferente de GoogleRCS.

  5. Canal principal de la campaña (campaign.channelType) diferente de WHATSAPP.

  6. Canal del mensaje principal diferente de campaign.channelType.

  7. Registros en audiences configurados con un canal diferente del canal principal.

  8. Configuración de más de un canal de fallback en la misma solicitud.

Importante: Configura obligatoriamente el fallback antes del lanzamiento. No se admite el envío de datos de fallback después de que comienza el procesamiento de la campaña principal, ya que puede generar inconsistencias.

Seguimiento de la ejecución

  • El servicio genera y lanza automáticamente la campaña de fallback después de que termina el periodo de tolerancia de las fallas detectadas en el canal principal.

  • Usa las operaciones de consulta (get) en los endpoints de campañas y audiencias para monitorear tanto la ejecución de la campaña principal como la de la campaña de fallback creada por el sistema.

  • No crees ni administres manualmente la campaña secundaria de fallback.
     

 

¿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 😃

Artículos relacionados