API Notifications vocales - Lovi AI Documentation

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)

{
  "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)

{
  "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 :

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

​Introduction

​📞 Envoyer une notification vocale

​Endpoint

​Paramètres de requête

​En-têtes

​Corps de la requête

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

​Structure avec variables plates (unflatten=true)

​Paramètres requis

​Paramètres optionnels

​Réponse

​Fonctionnalités spécifiques à la voix

​Bonnes pratiques

​📚 Conseils pour le développement vocal