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)

📣 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:

{
  "success": true,
  "message": "Registro exitoso",
  "notification_id": "uuid-notificacion-123"
}

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)

{
  "success": true,
  "message": "Notificación puesta en cola correctamente",
  "notification_id": "uuid-notificacion-123"
}

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
}

📚 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

​📚 Documentación Relacionada