> ## 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 Voz

> Documentación oficial para usar la API de Voz de Lovi para enviar llamadas de voz automatizadas

## Introducción

Las notificaciones de voz te permiten realizar llamadas automatizadas con agentes virtuales. Este endpoint te permite enviar llamadas de voz con agentes impulsados por IA a tus contactos, proporcionando una experiencia de voz personalizada.

## 📞 Enviar Notificación de Voz

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

> **Método**: POST **Formato**: JSON

### Endpoint

```
POST https://cloud.lovi.ai/functions/v1/notify/voice?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. |

**URL de Ejemplo:**

```
POST https://cloud.lovi.ai/functions/v1/notify/voice?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. |

**Nota**: La autenticación se gestiona a través del parámetro `access_key` en la URL, no a través de los encabezados.

### Cuerpo de la Solicitud

#### Estructura con objetos anidados (unflatten=false o sin especificar)

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "first_name": "María",
    "last_name": "González",
    "email": "maria@email.com",
    "titulacion": "Técnico en Enfermería",
    "fuente_cliente": "Web Principal"
  },
  "recipient_id": "34911670470",
  "agent_id": "uuid-agente-voz",
  "notification_type": "marketing",
  "campaign_name": "Llamada Informativa Q4",
  "name_event": "info-curso-enfermeria",
  "datetime_sending": "2024-12-25T09:00:00",
  "timezone": "Europe/Madrid"
}
```

#### Estructura con variables planas (unflatten=true)

```json theme={null}
{
  "contact.number": "34666033135",
  "contact.first_name": "María",
  "contact.last_name": "González",
  "contact.email": "maria@email.com",
  "contact.titulacion": "Técnico en Enfermería",
  "contact.fuente_cliente": "Web Principal",
  "recipient_id": "34911670470",
  "agent_id": "uuid-agente-voz",
  "notification_type": "marketing",
  "campaign_name": "Llamada Informativa Q4",
  "name_event": "info-curso-enfermeria",
  "datetime_sending": "2024-12-25T09:00:00",
  "timezone": "Europe/Madrid"
}
```

### Parámetros Requeridos

| Parámetro           | Tipo   | Descripción                              | Ejemplo                          |
| ------------------- | ------ | ---------------------------------------- | -------------------------------- |
| `contact.number`    | String | Número de teléfono sin '+' ni espacios   | `"34666033135"`                  |
| `recipient_id`      | String | ID o número de teléfono del destinatario | `"34911670470"`                  |
| `agent_id`          | String | Identificador único del agente de voz    | `"uuid-agente-voz"`              |
| `notification_type` | String | Tipo para analíticas                     | `"marketing"`, `"transactional"` |
| `campaign_name`     | String | Nombre identificador de la campaña       | `"Campaña de Voz Q4"`            |

### Parámetros Opcionales

| Parámetro            | Tipo     | Descripción                       | Ejemplo                   | Predeterminado |
| -------------------- | -------- | --------------------------------- | ------------------------- | -------------- |
| `contact.first_name` | String   | Nombre del contacto               | `"María"`                 | -              |
| `contact.last_name`  | String   | Apellido del contacto             | `"González"`              | -              |
| `contact.email`      | String   | Email del contacto                | `"maria@email.com"`       | -              |
| `name_event`         | String   | Evento para activar flujos        | `"info-curso-enfermeria"` | -              |
| `datetime_sending`   | DateTime | Fecha/hora programada (ISO 8601)  | `"2024-12-25T09:00:00"`   | Inmediato      |
| `timezone`           | String   | Zona horaria para la programación | `"Europe/Madrid"`         | `"UTC"`        |

**Campos de Contacto Personalizados**: Puedes incluir cualquier campo adicional en el objeto `contact` para personalización (ej. `titulacion`, `fuente_cliente`, etc.).

### Respuesta

Cuando la solicitud es exitosa, la respuesta contendrá:

```json theme={null}
{
  "success": true,
  "message": "Notificación de voz puesta en cola correctamente",
  "notification_id": "uuid-notificacion",
  "scheduled_time": "2024-12-25T09:00:00Z"
}
```

### Características Específicas de Voz

* **Agentes Impulsados por IA**: Usa agentes virtuales con síntesis de voz natural
* **Personalización**: Incluye datos de contacto personalizados para llamadas personalizadas
* **Programación**: Programa llamadas para momentos específicos con soporte de zona horaria
* **Activadores de Eventos**: Activa flujos de conversación específicos con `name_event`

### Mejores Prácticas

* **Horario**: Programa las llamadas durante el horario comercial para mayor participación
* **Personalización**: Incluye información relevante del contacto para un mejor flujo de conversación
* **Selección de Agente**: Elige agentes apropiados según el caso de uso (ventas, soporte, etc.)
* **Cumplimiento**: Asegúrate de que las llamadas cumplan con las regulaciones locales y los requisitos de consentimiento

***

## 📚 Consejos para el Desarrollo de Voz

* Siempre incluye `agent_id` para las notificaciones de voz
* Usa las funciones de programación para respetar las zonas horarias
* Prueba con agentes de desarrollo antes de producción
* Monitoriza las tasas de finalización de llamadas y ajusta el horario en consecuencia