> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Notificaciones de WhatsApp

> Documentación oficial para usar la API de Lovi con WhatsApp

## 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](./authentication).

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**.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

```json theme={null}
{
  "components_push": {
    "header_image": "https://cdn.ejemplo.com/promo.jpg"
  }
}
```

#### Ejemplo 2: Plantilla con Variables de Cuerpo

```json theme={null}
{
  "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}`!"

```json theme={null}
{
  "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:**

```json theme={null}
{
  "success": true,
  "message": "Registro exitoso",
  "notification_id": "uuid-notificacion-123"
}
```

### Ejemplo 2: Notificación con Encabezado de Imagen

```json theme={null}
{
  "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)

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

### Respuestas de Error

#### 400 Bad Request - Parámetros Inválidos

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

#### 401 Unauthorized - Clave de Acceso Inválida

```json theme={null}
{
  "error": "unauthorized",
  "message": "Clave de acceso inválida o expirada"
}
```

#### 404 Not Found - Plantilla No Encontrada

```json theme={null}
{
  "error": "template_not_found",
  "message": "Plantilla 'welcome_user' no encontrada o no aprobada"
}
```

#### 429 Too Many Requests - Límite de Tasa

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

***

## 📚 Documentación Relacionada

* **[Autenticación](./authentication)** - Cómo obtener tokens de acceso y claves API
* **[Notificaciones de Voz](./voice_notifications)** - Enviar llamadas de voz automatizadas
* **[Gestión de Plantillas](./template_management)** - Crear y gestionar plantillas de WhatsApp
* **[Programación](./scheduling)** - Gestión avanzada de programación y zonas horarias
* **[Manejo de Errores](./error_handling)** - Códigos de error completos y estrategias de manejo
* **[Mejores Prácticas](./best_practices)** - Directrices de seguridad y rendimiento