Trigger de respuesta rápida de WhatsApp

Usa whatsapp_template_quick_reply para iniciar una automatización cuando un cliente presiona un botón de respuesta rápida de una plantilla enviada por Insurance Boosters. El flujo es:

Elige una plantilla aprobada y copia su templateId.
Configura si quieres aceptar cualquier respuesta rápida o solo algunas.
Publica y activa la automatización.
Envía la plantilla. Cuando el cliente presione un botón configurado, se encolará una ejecución.

Antes de empezar

Necesitas:

El identificador de la línea de WhatsApp.
Una plantilla aprobada que incluya al menos un botón QUICK_REPLY.
Una API key con acceso a plantillas y automatizaciones.

Usa el id que devuelve GET /whatsapp/{phoneNumberId}/templates. No uses el nombre de la plantilla ni el ID que aparece en otras secciones internas de Insurance Boosters.

Obtener el `templateId`

Lista las plantillas de la línea:

curl "https://api.insuranceboosters.com/api/v1/whatsapp/<phone-number-id>/templates" \
  -H "x-ib-api-key: TU_API_KEY"

Busca la plantilla por name y language. Usa su id como templateId:

{
  "data": [
    {
      "id": "1234567890123456",
      "name": "recordatorio_pago",
      "language": "es",
      "status": "APPROVED",
      "components": [
        {
          "type": "BUTTONS",
          "buttons": [
            { "type": "QUICK_REPLY", "text": "Ya pagué" },
            { "type": "URL", "text": "Ver detalles" },
            { "type": "QUICK_REPLY", "text": "Necesito ayuda" }
          ]
        }
      ]
    }
  ]
}

En este ejemplo, usa "templateId": "1234567890123456".

Activar con cualquier respuesta rápida

Usa mode: "any" cuando todos los botones QUICK_REPLY deban iniciar la automatización:

{
  "type": "whatsapp_template_quick_reply",
  "templateId": "1234567890123456",
  "quickReply": {
    "mode": "any"
  }
}

Los botones URL, teléfono y Flow no disparan este trigger.

Activar solo con algunos botones

Usa mode: "selected" y buttonIndexes cuando solo ciertas respuestas deban iniciar la automatización:

{
  "type": "whatsapp_template_quick_reply",
  "templateId": "1234567890123456",
  "quickReply": {
    "mode": "selected",
    "buttonIndexes": [0, 2]
  }
}

Los índices empiezan en cero y cuentan todos los botones del componente BUTTONS, no solo los QUICK_REPLY:

Índice	Tipo	Texto	¿Dispara con `[0, 2]`?
`0`	`QUICK_REPLY`	Ya pagué	Sí
`1`	`URL`	Ver detalles	No
`2`	`QUICK_REPLY`	Necesito ayuda	Sí

Lee los índices directamente de template.components[].buttons al construir el workflow. No calcules la posición a partir de una lista filtrada de quick replies.

Crear la automatización

Este ejemplo recibe las respuestas de los índices 0 y 2 y las envía a un endpoint propio:

curl -X POST "https://api.insuranceboosters.com/api/v1/workflows" \
  -H "Content-Type: application/json" \
  -H "x-ib-api-key: TU_API_KEY" \
  -d '{
    "name": "Procesar respuesta de pago",
    "status": "disabled",
    "trigger": {
      "type": "whatsapp_template_quick_reply",
      "templateId": "1234567890123456",
      "quickReply": {
        "mode": "selected",
        "buttonIndexes": [0, 2]
      }
    },
    "steps": [
      {
        "name": "Notificar respuesta",
        "actionKey": "http.request",
        "input": {
          "method": "POST",
          "url": "https://ejemplo.com/hooks/whatsapp",
          "headers": {
            "Content-Type": "application/json"
          },
          "body": {
            "contactId": "{{trigger.body.contactId}}",
            "from": "{{trigger.body.from}}",
            "buttonIndex": "{{trigger.body.button.index}}",
            "buttonText": "{{trigger.body.button.text}}",
            "templateId": "{{trigger.body.template.id}}"
          }
        }
      }
    ]
  }'

Crear el workflow no basta. Después debes publicarlo y activarlo.

Datos disponibles en los pasos

El evento queda disponible en {{trigger.body...}}:

{
  "source": "whatsapp_template_quick_reply",
  "eventId": "<message-id>",
  "phoneNumberId": "<phone-line-id>",
  "template": {
    "id": "1234567890123456",
    "name": "recordatorio_pago",
    "language": "es"
  },
  "button": {
    "index": "2",
    "text": "Necesito ayuda",
    "payload": "Necesito ayuda"
  },
  "from": "5215512345678",
  "contactId": "<contact-id>",
  "messageId": "<message-id>",
  "originalMessageId": "<outbound-message-id>",
  "occurredAt": 1720000000000
}

Variable	Descripción
`trigger.body.template.id`	El mismo `templateId` configurado en el trigger.
`trigger.body.template.name`	Nombre de la versión enviada.
`trigger.body.template.language`	Idioma de la versión enviada.
`trigger.body.button.index`	Posición base cero del botón, como string numérico.
`trigger.body.button.text`	Texto que vio el cliente.
`trigger.body.button.payload`	Payload recibido desde WhatsApp.
`trigger.body.from`	Teléfono del cliente en formato internacional.
`trigger.body.contactId`	ID del contacto, cuando existe.
`trigger.body.messageId`	ID del mensaje de respuesta. Úsalo para deduplicar en sistemas externos.
`trigger.body.originalMessageId`	ID del mensaje de plantilla al que respondió el cliente.
`trigger.body.occurredAt`	Momento de la respuesta en milisegundos desde epoch.

name, language y contactId pueden no venir. Diseña los pasos alrededor de template.id, button, from y los IDs de mensaje.

Qué pasa si cambia la plantilla

El trigger seleccionado representa posiciones de botón, no textos. Si corriges el texto de un botón sin cambiar su posición, las respuestas a mensajes ya enviados mantienen el mismo comportamiento. Si agregas, eliminas o reordenas botones, revisa buttonIndexes, actualiza la automatización, publícala de nuevo y envía la nueva versión de la plantilla.

Usa textos distintos para cada QUICK_REPLY. Si dos botones de la misma plantilla tienen el mismo texto, WhatsApp puede no aportar información suficiente para distinguir cuál presionó el cliente. mode: "any" seguirá aceptando la respuesta, pero mode: "selected" podría no activarse.

Probar el trigger

Crea el workflow con status: "disabled".
Publícalo.
Actívalo.
Envía la plantilla mediante Insurance Boosters.
Presiona un quick reply desde un número de prueba.
Confirma la ejecución en Listar ejecuciones.

Solo se correlacionan respuestas a plantillas enviadas después de que esta funcionalidad está disponible en tu cuenta. No uses mensajes enviados anteriormente como prueba.

Solución de problemas

Problema	Qué revisar
La API rechaza el `templateId`	Usa `data[].id` de `GET /whatsapp/{phoneNumberId}/templates`. Confirma que la plantilla pertenezca a la misma cuenta.
La API rechaza un índice	Verifica que la posición exista y corresponda a un botón `QUICK_REPLY`.
No aparece una ejecución	Confirma que el workflow esté publicado y activo, que la plantilla se haya enviado mediante Insurance Boosters y que el índice esté seleccionado.
Funciona con `any`, pero no con `selected`	Revisa los índices y confirma que los textos de los quick replies sean únicos.
Cambió el orden de botones	Actualiza `buttonIndexes` y vuelve a publicar el workflow.

​Antes de empezar

​Obtener el templateId

​Activar con cualquier respuesta rápida

​Activar solo con algunos botones

​Crear la automatización

​Datos disponibles en los pasos

​Qué pasa si cambia la plantilla

​Probar el trigger

​Solución de problemas

​Relacionado

Antes de empezar

Obtener el `templateId`

Activar con cualquier respuesta rápida

Activar solo con algunos botones

Crear la automatización

Datos disponibles en los pasos

Qué pasa si cambia la plantilla

Probar el trigger

Solución de problemas

Relacionado