> ## 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 Notifications vocales

> Documentation officielle pour utiliser l'API Voice de Lovi pour envoyer des appels vocaux automatisés

## Introduction

Les notifications vocales vous permettent d'effectuer des appels automatisés avec des agents virtuels. Cet endpoint vous permet d'envoyer des appels vocaux avec des agents alimentés par l'IA à vos contacts, offrant une expérience vocale personnalisée.

## 📞 Envoyer une notification vocale

Pour envoyer une notification vocale via l'API Lovi, effectuez une requête POST vers l'endpoint vocal avec les paramètres nécessaires et l'authentification.

> **Méthode** : POST **Format** : JSON

### Endpoint

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

### Paramètres de requête

| Paramètre    | Requis | Description                                                                                                                                                         |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_key` | Oui    | Votre clé d'accès API unique.                                                                                                                                       |
| `unflatten`  | Non    | Si défini à `true`, le corps doit contenir des variables plates (pas d'objets imbriqués). Si défini à `false` ou omis, le corps peut contenir des objets imbriqués. |

**Exemple d'URL :**

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

### En-têtes

| Clé          | Valeur           | Requis | Description                                            |
| ------------ | ---------------- | ------ | ------------------------------------------------------ |
| Content-Type | application/json | Oui    | Indique que le corps de la requête est au format JSON. |

**Note** : L'authentification est gérée via le paramètre `access_key` dans l'URL, pas via les en-têtes.

### Corps de la requête

Le corps de la requête contient les détails de la notification vocale.

#### Structure avec objets imbriqués (unflatten=false ou omis)

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

#### Structure avec variables plates (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"
}
```

### Paramètres requis

| Paramètre           | Type   | Description                               | Exemple                          |
| ------------------- | ------ | ----------------------------------------- | -------------------------------- |
| `contact.number`    | String | Numéro de téléphone sans '+' ni espaces   | `"34666033135"`                  |
| `recipient_id`      | String | ID ou numéro de téléphone du destinataire | `"34911670470"`                  |
| `agent_id`          | String | Identifiant unique de l'agent vocal       | `"uuid-agente-voz"`              |
| `notification_type` | String | Type pour les analytiques                 | `"marketing"`, `"transactional"` |
| `campaign_name`     | String | Nom identifiant de la campagne            | `"Voice Campaign Q4"`            |

### Paramètres optionnels

| Paramètre            | Type     | Description                          | Exemple                   | Par défaut |
| -------------------- | -------- | ------------------------------------ | ------------------------- | ---------- |
| `contact.first_name` | String   | Prénom du contact                    | `"María"`                 | -          |
| `contact.last_name`  | String   | Nom de famille du contact            | `"González"`              | -          |
| `contact.email`      | String   | Email du contact                     | `"maria@email.com"`       | -          |
| `name_event`         | String   | Événement pour déclencher des flux   | `"info-curso-enfermeria"` | -          |
| `datetime_sending`   | DateTime | Date/heure programmée (ISO 8601)     | `"2024-12-25T09:00:00"`   | Immédiat   |
| `timezone`           | String   | Fuseau horaire pour la programmation | `"Europe/Madrid"`         | `"UTC"`    |

**Champs de contact personnalisés** : Vous pouvez inclure tout champ supplémentaire dans l'objet `contact` pour la personnalisation (ex. `titulacion`, `fuente_cliente`, etc.).

### Réponse

Quand la requête est réussie, la réponse contiendra :

```json theme={null}
{
  "success": true,
  "message": "Voice notification queued successfully",
  "notification_id": "uuid-notification",
  "scheduled_time": "2024-12-25T09:00:00Z"
}
```

### Fonctionnalités spécifiques à la voix

* **Agents alimentés par l'IA** : Utilisez des agents virtuels avec synthèse vocale naturelle
* **Personnalisation** : Incluez des données de contact personnalisées pour des appels personnalisés
* **Programmation** : Programmez des appels à des heures spécifiques avec support des fuseaux horaires
* **Déclencheurs d'événements** : Déclenchez des flux de conversation spécifiques avec `name_event`

### Bonnes pratiques

* **Timing** : Programmez les appels pendant les heures ouvrables pour un meilleur engagement
* **Personnalisation** : Incluez les informations de contact pertinentes pour un meilleur flux de conversation
* **Sélection de l'agent** : Choisissez les agents appropriés en fonction du cas d'usage (ventes, support, etc.)
* **Conformité** : Assurez-vous que les appels sont conformes aux réglementations locales et aux exigences de consentement

***

## 📚 Conseils pour le développement vocal

* Incluez toujours `agent_id` pour les notifications vocales
* Utilisez les fonctionnalités de programmation pour respecter les fuseaux horaires
* Testez avec des agents de développement avant la production
* Surveillez les taux de complétion des appels et ajustez le timing en conséquence