WhatsApp — Proveedor Gupshup

Canal padre: WhatsApp.
Tipo de canal: Texto.
Complejidad de integración: Requiere contratación comercial y cumplimiento de prerrequisitos de numeración con Meta.

Requisitos previos

Número telefónico que se desea activar.
Display Name: nombre con el cual se identificará el cliente en el bróker.
Facebook Business Manager ID (15 dígitos que identifican al cliente en Meta).
Razón social (como aparece en el FBM).
Página de Facebook de la empresa (ej. https://www.facebook.com/ejemplo).
Dirección física del cliente.
Número telefónico activo, con capacidad de recibir llamadas o SMS en un dispositivo móvil.
Número telefónico en un dispositivo sin la aplicación de WhatsApp instalada (si está instalada, debe eliminarse correctamente).
En caso de migración desde otro proveedor, el 2FA del proveedor anterior debe estar desactivado.

Activar nuevo aplicativo para un número nuevo

Activa un número telefónico nuevo para WhatsApp desde Gupshup, siguiendo los prerrequisitos y los pasos indicados por Gupshup en su guía "How to Create a Gupshup App and Go Live with a WhatsApp Business Account for a fresh phone number".

Migrar un número telefónico WhatsApp desde otro BSP a Gupshup

Aplica cuando el cliente desea conservar el mismo número telefónico, pero cambiar su BSP a Gupshup. Prerrequisito fundamental: desactivar el 2FA del proveedor anterior antes de iniciar la migración (proceso descrito por Gupshup: "Migration from other BSP to Gupshup via Embedded Signup Flow").

Configurar número adicional en Gupshup

Permite tener más de un número de WhatsApp (por ejemplo, uno para "Ventas", otro para "Post-Venta" y otro para "Testing"), repitiendo el proceso de "Activar nuevo aplicativo para un número nuevo".

Configurar el canal de WhatsApp en Lynn

Crear un nuevo canal de WhatsApp desde el diseñador de flujos, clic derecho → "Configurar canal".
Seleccionar el canal WhatsApp y luego Gupshup Whatsapp.
Completar los parámetros del canal en Lynn.

Parámetros del canal en Lynn

Parámetro	Descripción
`GS_WHATSAPP_API_NUMBER`	Número telefónico de WhatsApp configurado en la interfaz de Gupshup.
`GS_WHATSAPP_URL`	URL de la API de Gupshup para el envío de mensajes de WhatsApp.
`GS_WHATSAPP_TEMPLATE_URL`	URL de la API de Gupshup para el envío de mensajes de plantillas HSM. Se obtiene agregando el parámetro `template` a la URL anterior: de `http://api.gupshup.io/wa/api/v1/msg` a `http://api.gupshup.io/wa/api/v1/template/msg`.
`GS_WHATSAPP_API_KEY`	Clave de la API de Gupshup para WhatsApp.
`GS_WHATSAPP_APP_NAME`	Nombre de la aplicación creada en Gupshup.
`WHATSAPP_TIMEOUT_SECOUNDS`	Tiempo de espera para detectar inactividad y cerrar la interacción (máximo 7200 seg / 2 horas).
`WHATSAPP_MENU_PRESENTATION`	Formato de presentación del menú: Texto, Botón o Lista.
`WHATSAPP_MENU_PRESENTATION_LANGUAGE`	Idioma para presentar los elementos predeterminados del menú interactivo.

Carruseles de WhatsApp (plantillas tipo Carousel)

Prerrequisitos y restricciones de la plantilla

Restricción	Detalle
Infraestructura Cloud API (CAPI)	La aplicación de Gupshup configurada debe operar obligatoriamente sobre la Cloud API de Meta; las cuentas con infraestructura antigua (On-Premises) no soportan carruseles nativos.
Diseño del template	La plantilla debe crearse directamente en el panel de Gupshup seleccionando el tipo Carousel.
Cantidad de tarjetas	El número de elementos configurados en el panel (ej. exactamente 3 tarjetas) debe coincidir de forma idéntica con el número de elementos enviados por código en el arreglo `cards`. Máximo 10.
Botones estáticos	Los botones de interacción (llamadas a la acción o enlaces web) quedan fijos al momento de aprobar la plantilla en Meta; no es posible modificarlos dinámicamente mediante la llamada a la API.

1. Configuración en Gupshup

Crear una plantilla ingresando un nombre válido. Este tipo de plantilla solo está disponible en Gupshup.
Seleccionar el tipo Carrusel.
Personalizar los campos y el diseño del carrusel, incorporando tantas cartas como sean necesarias, hasta un límite de 10.
El cuerpo de la plantilla puede contener variables, al igual que cada carta. Las imágenes de las cartas también pueden ser variables; sin embargo, la composición de botones y CTA de las tarjetas no puede ser dinámica.
Enviar a revisión la plantilla carrusel. Este proceso puede tardar hasta 24 h en estado "pendiente".

2. Estructura de la solicitud en Lynn

Se sigue la estrategia de gestión de campañas salientes asociando una plantilla a una campaña, donde la plantilla debe tener coherencia con la plantilla previamente configurada en Gupshup. Se deben configurar los datos base teniendo especial cuidado en que el orden de las variables dinámicas corresponda con el orden de los numerales de variables del body y de las cartas asociadas.

En la referencia de plantilla de Lynn, los campos dinámicos deben contener variables de columna definidas en la base, o expresiones string definidas entre apóstrofes (').

Referencia de plantilla en Lynn

Ejemplo de estructura del input header a configurar en la plantilla de envíos de Lynn:

{
  "type": "carousel",
  "cardHeaderType": "IMAGE",
  "cards": [
    {
      "link": "https://url-imagen-tarjeta-1.jpg"
    },
    {
      "link": "https://url-imagen-tarjeta-2.jpg"
    }
  ]
}

Note

Es muy importante que los enlaces de imágenes sean alcanzables por Gupshup y Meta en una URL pública; de lo contrario, Meta no podrá mostrar dichos contenidos.

Una vez creada la plantilla, se puede descargar la base de referencia para incorporar la información de contactos y realizar el envío como campaña saliente (ver Campañas > Definiciones de Campaña).

3. Consideraciones de ejecución y errores comunes

Sintaxis de parámetros (params): las variables dinámicas del texto principal o de las tarjetas deben ir agrupadas en un único arreglo JSON plano (ej. ["Var1", "Var2"]), evitando separar los corchetes en múltiples arreglos independientes.
Accesibilidad de multimedia: los enlaces definidos en el campo link (por ejemplo, contenedores en la nube o servidores propios) deben ser públicamente accesibles mediante peticiones GET estándar, para que el servidor de Meta pueda descargar y renderizar las imágenes correctamente.
Entornos de pruebas (Sandbox): si la línea emisora se encuentra en modo de pruebas, el número de destino debe estar explícitamente agregado en la lista blanca del panel de Gupshup; de lo contrario, la API arrojará una respuesta de éxito simulado, pero el mensaje nunca será entregado al dispositivo final.

Referencias externas

WhatsApp Flows (formularios interactivos)

Un WhatsApp Flow es un formulario interactivo que aparece dentro del chat de WhatsApp, sin que el usuario tenga que salir a una página web (pedir datos, agendar citas, encuestas, etc.). El usuario no abandona WhatsApp, la información llega ordenada y sin errores de formato, y se visualiza igual en cualquier celular.

Important

Actualmente estos formularios solo pueden ser estáticos: todas las opciones (ej. las de una lista desplegable) deben quedar definidas de antemano. No es posible que el formulario consulte un sistema externo en tiempo real mientras el usuario lo está completando (ej. mostrar sucursales según la ciudad elegida).

El proceso tiene tres etapas: 1) diseñar el formulario en Meta (WhatsApp Manager), 2) conectar el webhook que trae las respuestas en Gupshup, y 3) activar el formulario dentro de una conversación en Lynn.

Requisitos previos

Acceso de administrador a Meta Business Suite.
Una cuenta de WhatsApp Business (WABA) ya verificada.
Acceso al WhatsApp Manager de Meta.
El canal de WhatsApp en Lynn debe estar configurado con Gupshup como proveedor.

Parte 1 — Crear el formulario en Meta

Meta ofrece dos herramientas para crear el formulario:

Herramienta	Para quién es	Cómo funciona
Editor visual (Flows Builder)	Personas sin conocimientos técnicos	Arrastra y ordena los elementos en pantalla; incluye vista previa en tiempo real, gestión visual de pantallas (screens) e inspector de propiedades.
Editor de código (Flow JSON)	Personas con conocimientos técnicos	Se escribe directamente el schema JSON que define el formulario (`screens`, `layout`, `children`, acciones `INIT`/`NAVIGATE`/`COMPLETE`); permite control de versiones (Git) y Meta valida la sintaxis contra la versión del schema (ej. `v7.3`).

Pasos para crear el formulario:

Entrar a Meta Business Suite → Configuración del negocio → Cuentas de WhatsApp → elegir la cuenta → Administrador de WhatsApp.
En el menú lateral, ir a Herramientas de la cuenta → Flujos (Flows) → Crear flujo.
Completar nombre del flujo, categoría (ej. atención al cliente, encuestas, registro) y plantilla base (lienzo en blanco o plantilla existente).
Diseñar las pantallas del formulario agregando los campos necesarios (ver tabla de elementos abajo).
Importante: la última pantalla, donde el usuario envía el formulario, debe estar marcada como pantalla final ("terminal": true en el JSON; en el editor visual esto se configura solo al definir el botón de envío).
Revisar la vista previa (modo Preview) y publicar el flujo.

Elementos disponibles en el formulario:

Tipo	Elemento	Para qué sirve
Texto	Título, subtítulo, párrafo, nota	Mostrar información o instrucciones
Entrada de texto	Campo de texto simple	Nombre, correo, teléfono, etc.
Entrada de texto	Campo de texto largo	Comentarios o descripciones
Selección única	Botones de opción	El usuario elige una sola opción visible
Selección única	Lista desplegable	El usuario elige una opción de una lista
Selección múltiple	Casillas de verificación	El usuario puede elegir varias opciones
Fecha	Selector de fecha	Elegir un día de un calendario
Acción	Botón	Para pasar a otra pantalla o para enviar el formulario

Como el formulario es estático, todas las opciones de las listas deben quedar escritas de antemano en el diseño.

Parte 2 — Conectar Gupshup para recibir las respuestas

Una vez publicado el formulario en Meta, hay que configurar en Gupshup un webhook para que reciba las respuestas y se las pase a Lynn (sin este paso, la respuesta del formulario no llega a Lynn y la conversación no puede continuar automáticamente).

Entrar a la consola de Gupshup.
Ir al panel de aplicaciones y seleccionar la app de WhatsApp conectada al número y a Lynn.
Dentro de la configuración de la app, ir a la sección Webhooks.
Hacer clic en Agregar webhook. Completar el formulario con estos datos exactos:

Campo	Qué poner
Nombre del webhook	`flows`
Callback URL	La misma URL ya configurada para los mensajes normales en Lynn (no se crea una nueva)
Formato del webhook	`Meta format (v3)`
Eventos a seleccionar	`Flow`, `Read` y `Failed`

Guardar con Agregar webhook y verificar que el interruptor de este nuevo webhook quede activado (ON).

Flujo de la información: Usuario completa el formulario en WhatsApp → Meta envía la respuesta → Gupshup la recibe por el webhook flows → Gupshup se la reenvía a Lynn → Lynn continúa la conversación o deriva el caso a un agente.

Parte 3 — Activar el formulario desde Lynn

Paso previo — vincular la cuenta: en la consola de administración de Lynn, ir a Canales → WhatsApp y asociar la cuenta con el ID Partner de Gupshup correspondiente al número de WhatsApp.

Formas de activar el formulario, según el momento:

Envío como mensaje de plantilla (fuera o dentro de la ventana de 24 horas) — para enviar el formulario de forma proactiva (ej. en una campaña o notificación). Se configura con el módulo Request HSM Template (RequestFlowMeta) en el diseñador de flujos; requiere tener previamente una plantilla de WhatsApp aprobada por Meta que incluya el botón del formulario.
Envío durante una conversación activa (dentro de las 24 horas desde el último mensaje del usuario) — para que el formulario aparezca en medio de una conversación en curso. Se configura con el módulo WhatsappFlowDynamic, indicando el ID del formulario, el título, el texto explicativo y el texto del botón que abre el formulario.

Si se va a enviar el formulario primero (ej. una campaña), usar la opción 1 (RequestFlowMeta). Si el formulario se dispara como parte de la conversación que ya está teniendo el bot con el usuario, usar la opción 2 (WhatsappFlowDynamic).

Nota (actualizada 2026-09-23): ambos módulos ya cuentan con ficha propia — ver Request HSM Template y Whatsapp Flow Dynamic.

Ejemplo funcional de Flow JSON (schema v7.3, estático)

Incluye la propiedad obligatoria "terminal": true en la pantalla de cierre:

{
  "version": "7.3",
  "screens": [
    {
      "id": "SCREEN_DATOS_CONTACTO",
      "title": "Solicitud de Información",
      "terminal": true,
      "data": {},
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextHeading",
            "text": "Ingresa tus datos"
          },
          {
            "type": "TextBody",
            "text": "Por favor completa los siguientes campos para que un asesor te contacte."
          },
          {
            "type": "TextInput",
            "name": "nombre_completo",
            "label": "Nombre y Apellido",
            "required": true
          },
          {
            "type": "TextInput",
            "name": "correo_electronico",
            "label": "Correo Electrónico",
            "required": true,
            "input-type": "email"
          },
          {
            "type": "Dropdown",
            "name": "motivo_contacto",
            "label": "Motivo de consulta",
            "required": true,
            "data-source": [
              { "id": "soporte", "title": "Soporte Técnico" },
              { "id": "ventas", "title": "Cotizaciones y Ventas" },
              { "id": "reclamos", "title": "Gestión de Reclamos" }
            ]
          },
          {
            "type": "Footer",
            "label": "Enviar Solicitud",
            "on-click-action": {
              "name": "complete",
              "payload": {
                "nombre": "${form.nombre_completo}",
                "email": "${form.correo_electronico}",
                "motivo": "${form.motivo_contacto}"
              }
            }
          }
        ]
      }
    }
  ]
}

Lista de verificación final

[ ] El formulario (Flow) está creado y publicado en el WhatsApp Manager de Meta.
[ ] La pantalla final del formulario tiene marcada la opción de pantalla terminal, para que el botón de enviar funcione.
[ ] El formulario no depende de ninguna consulta externa en tiempo real (todo es estático).
[ ] En Gupshup existe un webhook llamado flows, en formato Meta format (v3), con los eventos Flow, Read y Failed activados.
[ ] La URL de este webhook es la misma que usa el webhook de mensajería normal.
[ ] El interruptor del webhook flows está en estado ON.
[ ] En Lynn, la cuenta de WhatsApp está vinculada con el ID Partner correcto de Gupshup.
[ ] Se eligió el módulo correcto en Lynn según el caso: RequestFlowMeta (plantilla) o WhatsappFlowDynamic (mensaje en sesión).

Preguntas frecuentes

¿Puedo hacer que el formulario muestre opciones distintas según lo que el usuario respondió antes? No por ahora. Todo el contenido del formulario debe quedar definido desde el diseño, ya que no hay conexión con sistemas externos mientras el usuario lo completa.

¿Dónde se diseña el formulario, en Meta o en Lynn? Siempre en Meta. Lynn no tiene una herramienta propia para diseñar formularios; solo se encarga de activarlos y de recibir las respuestas (a través de Gupshup).

¿Qué pasa si no configuro el webhook "flows" en Gupshup? El usuario podrá ver y completar el formulario, pero la respuesta no llegará a Lynn, por lo que la conversación no podrá continuar de forma automática.

Table of Contents

WhatsApp — Proveedor Gupshup

Requisitos previos

Activar nuevo aplicativo para un número nuevo

Migrar un número telefónico WhatsApp desde otro BSP a Gupshup

Configurar número adicional en Gupshup

Configurar el canal de WhatsApp en Lynn

Parámetros del canal en Lynn

Carruseles de WhatsApp (plantillas tipo Carousel)

Prerrequisitos y restricciones de la plantilla

1. Configuración en Gupshup

2. Estructura de la solicitud en Lynn

Note

3. Consideraciones de ejecución y errores comunes

Referencias externas

WhatsApp Flows (formularios interactivos)

Important

Requisitos previos

Parte 1 — Crear el formulario en Meta

Parte 2 — Conectar Gupshup para recibir las respuestas

Parte 3 — Activar el formulario desde Lynn

Ejemplo funcional de Flow JSON (schema v7.3, estático)

Lista de verificación final

Preguntas frecuentes