Configuración de Carruseles de WhatsApp (Gupshup + Lynn)
Prerrequisitos y configuración de plantilla en Gupshup
Antes de ejecutar las solicitudes de código, la infraestructura de Meta y Gupshup exige cumplir con restricciones estrictas de diseño:
| 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. Configuraciones
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.
- Tener en cuenta que 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:
Seguimos la estrategia de gestión de campañas salientes asociando una plantilla a una campaña, donde la plantilla tendrá 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 (').
Estos valores establecen un 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 "Envío de campañas proactivas" para más información.
La plantilla esperada tendrá una apariencia similar a la planteada en la vista previa del editor de plantillas de Gupshup.
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.