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"
}

Los errores de esta API usan el cuerpo { "success": false, "message": "…" }. No uses Authorization: la autenticación es el access_key de la query. Para crear (POST /notify) la clave necesita el permiso whatsapp_notifications. Para consultar estado no hace falta un permiso extra: vale cualquier access_key válida de la misma compañía. Máximo 100 contactos por solicitud. No hay rate limit HTTP ni paginación en el estado. Si envías el array contacts (varios destinatarios), el message de éxito es "Processing completed" y la respuesta incluye total, processed, failed y errors. Con un solo contact, el message es "Registration successful".

Respuestas de Error

400 Bad Request

Falta access_key, el cuerpo es inválido, o (en status) falta campaign_id.

{
  "success": false,
  "message": "Campo requerido faltante"
}

403 Forbidden — Crear sin permiso

La clave no tiene whatsapp_notifications (o voice_notifications en POST /notify/voice).

{
  "success": false,
  "message": "Forbidden"
}

404 Not Found — Clave inválida o recurso inexistente

Una access_key inválida no devuelve 401. Devuelve 404 (Invalid access_key). El mismo 404 aparece si la campaña no existe o es de otra compañía (Campaign not found).

{
  "success": false,
  "message": "Invalid access_key"
}

500 Internal Server Error

{
  "success": false,
  "message": "No se pudo completar la solicitud"
}

Consultar el estado de una campaña

Después de crear una campaña puedes consultar su progreso con GET. Usa como campaign_id el inquiry_set_id de la respuesta de creación. El mismo endpoint vale para WhatsApp y para voz (POST /notify/voice): no hay un status distinto. No existe el campo notification_id en esta API.

Endpoint

Producción:

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

Host verificado: https://cloud.lovi.ai/functions/v1/…. https://app.lovi.ai/functions/... no es esta API (devuelve el frontend). No documentamos app-dev.lovi.ai como host de functions: no está en este backend.

Parámetros de consulta

Parámetro	Requerido	Descripción
`access_key`	Sí	Clave válida. Solo ve campañas de la misma compañía.
`campaign_id`	Sí	UUID. Es el `inquiry_set_id` de la creación.

Cualquier clave válida de la compañía puede consultar estado. El permiso whatsapp_notifications / voice_notifications solo se exige al crear.

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 observado: `pending`, `processing`, `ready`, `completed` o `failed` (varchar; no hay ENUM de PostgreSQL).
`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 `campaign_id` o `access_key`.
`404`	`Invalid access_key`, o la campaña no existe / es de otra compañía (`Campaign not found`).
`500`	No se pudo consultar el estado.

📚 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

​403 Forbidden — Crear sin permiso

​404 Not Found — Clave inválida o recurso inexistente

​500 Internal Server Error

​Consultar el estado de una campaña

​Endpoint

​Parámetros de consulta

​Ejemplo de respuesta exitosa

​Significado de los campos

​Errores posibles

​📚 Documentación Relacionada

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

403 Forbidden — Crear sin permiso

404 Not Found — Clave inválida o recurso inexistente

500 Internal Server Error

Consultar el estado de una campaña

Endpoint

Parámetros de consulta

Ejemplo de respuesta exitosa

Significado de los campos

Errores posibles

📚 Documentación Relacionada