API de Notificaciones de WhatsApp - Lovi AI Documentation

Introducción

Esta sección proporciona la documentación oficial para usar la API de Lovi con WhatsApp. Incluye instrucciones detalladas sobre cómo configurar y probar las solicitudes de API para la integración con WhatsApp. La autenticación se realiza mediante tokens que habilitan la autenticación básica para los servicios de la API. Para más detalles sobre cómo autenticarse, consulta la página de Autenticación. La API de Lovi admite notificaciones de WhatsApp con contenido multimedia, marcadores de posición dinámicos, entrega programada e integración de flujo de conversación.

Características Principales:

Notificaciones de WhatsApp con soporte multimedia
Personalización dinámica de contenido con marcadores de posición
Entrega de mensajes programada con soporte de zona horaria
Integración de flujo de conversación
Dos formatos de estructura de datos (anidado y plano)
Consulta del estado y resultados de una campaña

📣 Enviar Notificación de WhatsApp

Para enviar una notificación a través de la API de Lovi, realiza una solicitud POST al endpoint con los parámetros necesarios y la autenticación.

Método: POST Formato: JSON

Endpoint

POST https://cloud.lovi.ai/functions/v1/notify?access_key={TU_ACCESS_KEY}

Parámetros de Consulta

Parámetro	Requerido	Descripción
`access_key`	Sí	Tu clave de acceso única a la API.
`unflatten`	No	Si se establece en `true`, el cuerpo debe contener variables planas (sin objetos anidados). Si se establece en `false` u omite, el cuerpo puede contener objetos anidados.

URLs de Ejemplo:

POST https://cloud.lovi.ai/functions/v1/notify?access_key=tu-api-key
POST https://cloud.lovi.ai/functions/v1/notify?access_key=tu-api-key&unflatten=true

Encabezados

Clave	Valor	Requerido	Descripción
Content-Type	application/json	Sí	Indica que el cuerpo de la solicitud está en formato JSON.

📋 Parámetros de la Solicitud

Parámetros Requeridos

Parámetro	Tipo	Descripción	Ejemplo
`contact` O `contacts`	Objeto O Array	Numero de contacto único (objeto) O Numeros de contactos multiples (array, máx. 100)	Ver más abajo
`language_template`	String	Código de idioma para la plantilla	`"es_ES"`, `"en_US"`, `"es"`, `"es"`
`name_template`	String	Nombre de la plantilla aprobada	`"welcome_user"`
`recipient_id`	String	ID o número de teléfono del remitente	`"34666033135"`
`notification_type`	String	Tipo para analíticas	`"marketing"`, `"transactional"`, `"utility"`
`campaign_name`	String	Nombre identificador de la campaña	`"Black Friday 2024"`

Parámetros Opcionales

Parámetro	Tipo	Descripción	Cuándo usarlo	Ejemplo
`contact.name`	String	Nombre del contacto para personalización	Para mensajes personalizados	`"Juan Pérez"`
`contact.email`	String	Email del contacto	Para datos de contacto adicionales	`"juan@email.com"`
`name_event`	String	Evento para activar flujos de conversación	Cuando quieres iniciar un flujo específico	`"intent-general-push"`
`datetime_sending`	DateTime	Hora de entrega programada (ISO 8601)	Cuando quieres programar el mensaje para más tarde	`"2024-12-25T10:30:00"`
`timezone`	String	Zona horaria para la entrega programada	Al usar `datetime_sending`	`"Europe/Madrid"`

👥 Destinatario Único vs. Múltiples Destinatarios

Usando `contact` - Enviar a Una Persona

Usa contact cuando quieras enviar una notificación a un destinatario.

{
  "contact": {
    "number": "34666033135",
    "name": "Juan",
    "email": "juan@ejemplo.com"
  }
}

Usando `contacts` - Enviar a Múltiples Personas (Envío Masivo)

Usa contacts cuando quieras enviar la misma notificación a múltiples destinatarios a la vez.

{
  "contacts": [
    { "number": "34666033135", "name": "Juan" },
    { "number": "34777044246", "name": "María" },
    { "number": "34888055357", "name": "Carlos" }
  ]
}

Máximo: 100 contactos por solicitud
⚠️ No se puede usar unflatten=true con contacts
⚠️ No se puede usar tanto contact como contacts en la misma solicitud

🎨 Componentes y Multimedia

Reglas de Nomenclatura de Componentes

Multimedia de encabezado: header_image, header_video, header_document (SIN número de sufijo)
Variables de cuerpo: body_text_0, body_text_1, body_text_2, etc. (con número de índice para cada marcador)
Pie y Botones: Son ESTÁTICOS en la definición de la plantilla y NO se pueden enviar dinámicamente

Ejemplos de Componentes

Ejemplo 1: Plantilla con Encabezado de Imagen

{
  "components_push": {
    "header_image": "https://cdn.ejemplo.com/promo.jpg"
  }
}

Ejemplo 2: Plantilla con Variables de Cuerpo

{
  "components_push": {
    "body_text_0": "María",
    "body_text_1": "Curso Avanzado de JavaScript"
  }
}

📋 Ejemplos Completos

Ejemplo 1: Destinatario Único con Variables de Cuerpo

Plantilla: “Hola {1}, ¡gracias por tu interés en {2}!”

{
  "contact": {
    "number": "34666033135",
    "customer_name": "Sara"
  },
  "components_push": {
    "body_text_0": "{{customer_name}}",
    "body_text_1": "nuestra Membresía Premium"
  },
  "language_template": "es",
  "name_template": "interest_confirmation",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Campaña de Membresía 2024"
}

Respuesta:

{
  "message": "Registration successful",
  "inquiry_set_id": "d891b9b4-2f79-45a0-bc99-9a2922d4f713"
}

Ejemplo 2: Notificación con Encabezado de Imagen

{
  "contact": {
    "number": "34666033135",
    "customer_name": "Roberto"
  },
  "components_push": {
    "header_image": "https://cdn.ejemplo.com/promocion-navidad.jpg"
  },
  "language_template": "es",
  "name_template": "oferta_navidad",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Oferta Navidad 2024",
  "datetime_sending": "2024-12-24T09:00:00",
  "timezone": "Europe/Madrid"
}

📊 Códigos de Respuesta

Respuesta Exitosa (200 OK)

{
  "message": "Registration successful",
  "inquiry_set_id": "d891b9b4-2f79-45a0-bc99-9a2922d4f713"
}

Respuestas de Error

400 Bad Request - Parámetros Inválidos

{
  "error": "validation_failed",
  "message": "Campo requerido faltante",
  "details": {
    "field": "contact.number",
    "reason": "Este campo es requerido"
  }
}

401 Unauthorized - Clave de Acceso Inválida

{
  "error": "unauthorized",
  "message": "Clave de acceso inválida o expirada"
}

404 Not Found - Plantilla No Encontrada

{
  "error": "template_not_found",
  "message": "Plantilla 'welcome_user' no encontrada o no aprobada"
}

429 Too Many Requests - Límite de Tasa

{
  "error": "rate_limit_exceeded",
  "message": "Demasiadas solicitudes. Inténtalo de nuevo en 60 segundos",
  "retry_after": 60
}

Consultar el estado de una campaña

Después de crear una campaña puedes consultar su progreso con una solicitud GET. Usa como campaign_id el valor de inquiry_set_id devuelto por la solicitud de envío.

Endpoints

Producción:

GET https://cloud.lovi.ai/functions/v1/notify/status?access_key={TU_ACCESS_KEY}&campaign_id={CAMPAIGN_ID}

Desarrollo:

GET https://app-dev.lovi.ai/functions/v1/notify/status?access_key={TU_ACCESS_KEY_DEV}&campaign_id={CAMPAIGN_ID}

Utiliza siempre una clave del mismo entorno que la campaña. La ruta bajo https://app.lovi.ai/functions/... no es un endpoint de esta API: devuelve la aplicación web.

Parámetros de consulta

Parámetro	Requerido	Descripción
`access_key`	Sí	Clave de acceso válida. Solo permite consultar campañas de la misma compañía.
`campaign_id`	Sí	UUID de la campaña. Corresponde al campo `inquiry_set_id` de la respuesta al crearla.

No se necesita un permiso adicional: cualquier clave válida de la compañía puede consultar sus propias campañas.

Ejemplo de respuesta exitosa

{
  "campaign_id": "d891b9b4-2f79-45a0-bc99-9a2922d4f713",
  "name": "Campaña de Membresía 2026",
  "status": "processing",
  "general_failure": false,
  "alert_message": null,
  "created_at": "2026-08-10T09:30:00Z",
  "total_recipients": 100,
  "sent": 76,
  "failed": 4,
  "pending": 20,
  "responded": 18,
  "by_status": {
    "delivered": 61,
    "read": 15,
    "failed": 4,
    "pending": 20
  }
}

Significado de los campos

Campo	Descripción
`campaign_id`	Identificador de la campaña consultada.
`name`	Nombre de la campaña.
`status`	Estado general de la campaña.
`general_failure`	`true` cuando el estado general de la campaña es `failed`.
`alert_message`	Mensaje de alerta asociado a la campaña, si existe.
`created_at`	Fecha y hora de creación.
`total_recipients`	Número total de destinatarios registrados.
`sent`	Destinatarios en estado `delivered`, `read`, `sent`, `completed` o `done`.
`failed`	Destinatarios en estado `failed`, `warning`, `busy`, `no-answer` o `voicemail`.
`pending`	Destinatarios cuyo estado no pertenece a los grupos `sent` o `failed`.
`responded`	Número de chats distintos asociados a la campaña que contienen al menos un mensaje del usuario.
`by_status`	Desglose completo de destinatarios por estado original.

Los contadores se calculan con los datos actuales de la campaña, por lo que pueden cambiar mientras el envío sigue en curso.

Errores posibles

Código	Causa
`400`	Falta el parámetro `campaign_id`.
`401`	La clave de acceso no es válida.
`404`	La campaña no existe o no pertenece a la compañía de la clave utilizada.
`500`	No se pudo consultar el estado de la campaña.

📚 Documentación Relacionada

Autenticación - Cómo obtener tokens de acceso y claves API
Notificaciones de Voz - Enviar llamadas de voz automatizadas
Gestión de Plantillas - Crear y gestionar plantillas de WhatsApp
Programación - Gestión avanzada de programación y zonas horarias
Manejo de Errores - Códigos de error completos y estrategias de manejo
Mejores Prácticas - Directrices de seguridad y rendimiento

​Introducción

​Características Principales:

​📣 Enviar Notificación de WhatsApp

​Endpoint

​Parámetros de Consulta

​Encabezados

​📋 Parámetros de la Solicitud

​Parámetros Requeridos

​Parámetros Opcionales

​👥 Destinatario Único vs. Múltiples Destinatarios

​Usando contact - Enviar a Una Persona

​Usando contacts - Enviar a Múltiples Personas (Envío Masivo)

​🎨 Componentes y Multimedia

​Reglas de Nomenclatura de Componentes

​Ejemplos de Componentes

​Ejemplo 1: Plantilla con Encabezado de Imagen

​Ejemplo 2: Plantilla con Variables de Cuerpo

​📋 Ejemplos Completos

​Ejemplo 1: Destinatario Único con Variables de Cuerpo

​Ejemplo 2: Notificación con Encabezado de Imagen

​📊 Códigos de Respuesta

​Respuesta Exitosa (200 OK)

​Respuestas de Error

​400 Bad Request - Parámetros Inválidos

​401 Unauthorized - Clave de Acceso Inválida

​404 Not Found - Plantilla No Encontrada

​429 Too Many Requests - Límite de Tasa

​Consultar el estado de una campaña

​Endpoints

​Parámetros de consulta

​Ejemplo de respuesta exitosa

​Significado de los campos

​Errores posibles

​📚 Documentación Relacionada