API Notifications WhatsApp - Lovi AI Documentation

Introduction

Cette section fournit la documentation officielle pour utiliser l’API Lovi avec WhatsApp via Postman. Elle comprend des instructions détaillées sur la configuration et le test des requêtes API pour l’intégration WhatsApp, garantissant une communication fluide via la plateforme. L’authentification est effectuée à l’aide de tokens qui permettent l’authentification de base pour les services API. Pour plus de détails sur l’authentification, veuillez consulter la page Authentification. L’API Lovi prend en charge les notifications WhatsApp avec du contenu multimédia, des placeholders dynamiques, une livraison programmée et l’intégration de flux de conversation.

Fonctionnalités clés :

Notifications WhatsApp avec support multimédia
Personnalisation dynamique du contenu avec des placeholders
Livraison programmée des messages avec support des fuseaux horaires
Intégration de flux de conversation
Deux formats de structure de données (imbriqué et plat)

📣 Envoyer une notification WhatsApp

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

Méthode : POST Format : JSON

Endpoint

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

Exemples d’URL :

POST https://cloud.lovi.ai/functions/v1/notify?access_key=your-api-key
POST https://cloud.lovi.ai/functions/v1/notify?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.

📋 Paramètres de requête

L’API prend en charge deux formats de structure de données contrôlés par le paramètre unflatten.

Paramètres requis

Paramètre	Type	Description	Exemple
`contact` OU `contacts`	Object OU Array	Choisissez un : Contact unique (objet) OU Contacts multiples (tableau, max 100)	Voir ci-dessous
`language_template`	String	Code de langue du template	`"es_ES"`, `"en_US"`
`name_template`	String	Nom du template approuvé	`"welcome_user"`
`recipient_id`	String	ID ou numéro de téléphone du destinataire	`"34666033135"`
`notification_type`	String	Type pour les analytiques	`"marketing"`, `"transactional"`, `"utility"`
`campaign_name`	String	Nom identifiant de la campagne	`"Black Friday 2024"`

Important : Vous devez utiliser soit contact (pour un seul destinataire) SOIT contacts (pour plusieurs destinataires), mais PAS les deux.

Paramètres optionnels

Paramètre	Type	Description	Quand l’utiliser	Exemple
`contact.name`	String	Nom du contact pour la personnalisation	Pour les messages personnalisés	`"Juan Pérez"`
`contact.email`	String	Email du contact	Pour des données de contact supplémentaires	`"juan@email.com"`
`name_event`	String	Événement pour déclencher des flux	Quand vous voulez démarrer un flux de conversation spécifique	`"intent-general-push"`
`datetime_sending`	DateTime	Heure de livraison programmée (ISO 8601)	Quand vous voulez programmer le message pour plus tard	`"2024-12-25T10:30:00"`
`timezone`	String	Fuseau horaire pour la livraison programmée	Quand vous utilisez `datetime_sending`	`"Europe/Madrid"`
`components_push.*`	Mixed	Composants du template (texte, média)	Quand le template nécessite du contenu dynamique	Voir la section composants

👥 Destinataire unique vs multiples

Utiliser `contact` - Envoyer à une personne

Utilisez contact quand vous voulez envoyer une notification à un seul destinataire. Structure :

{
  "contact": {
    "number": "34666033135",
    "name": "John",
    "email": "john@example.com"
  }
}

contact est un objet (pas une liste)
Champ requis : number
Champs optionnels : name, email, et tout champ personnalisé

Utiliser `contacts` - Envoyer à plusieurs personnes (Envoi en masse)

Utilisez contacts quand vous voulez envoyer la même notification à plusieurs destinataires à la fois. Structure :

{
  "contacts": [
    {
      "number": "34666033135",
      "name": "John"
    },
    {
      "number": "34777044246",
      "name": "Sarah"
    },
    {
      "number": "34888055357",
      "name": "Michael"
    }
  ]
}

contacts est une liste/tableau (pas un objet unique)
Maximum : 100 contacts par requête
Chaque contact dans la liste doit avoir un number
Champs optionnels : name, email, et tout champ personnalisé

Restrictions importantes :

⚠️ Impossible d’utiliser unflatten=true avec contacts - L’envoi en masse ne fonctionne qu’avec la structure imbriquée
⚠️ Impossible d’utiliser contact et contacts dans la même requête - choisissez l’un
⚠️ La liste contacts ne peut pas être vide - doit avoir au moins 1 contact

🔄 Formats de structure de données

L’API prend en charge deux formats basés sur le paramètre unflatten :

Structure imbriquée (unflatten=false ou omis)

Quand unflatten=false ou non spécifié, utilisez des objets imbriqués :

{
  "contact": {
    "number": "34666033135",
    "name": "Juan Pérez",
    "email": "juan@email.com"
  },
  "components_push": {
    "header_text_0": "Welcome Message",
    "body_text_0": "Hello {{name}}",
    "body_text_1": "Your order is ready!",
    "footer_text_0": "Support Team"
  },
  "language_template": "es_ES",
  "name_template": "order_ready",
  "recipient_id": "34666033135",
  "notification_type": "transactional",
  "campaign_name": "Order Notifications"
}

Structure plate (unflatten=true)

Quand unflatten=true, tous les objets imbriqués doivent être aplatis avec la notation par point :

{
  "contact.number": "34666033135",
  "contact.name": "Juan Pérez",
  "contact.email": "juan@email.com",
  "components_push.header_text_0": "Welcome Message",
  "components_push.body_text_0": "Hello {{name}}",
  "components_push.body_text_1": "Your order is ready!",
  "components_push.footer_text_0": "Support Team",
  "language_template": "es_ES",
  "name_template": "order_ready",
  "recipient_id": "34666033135",
  "notification_type": "transactional",
  "campaign_name": "Order Notifications"
}

Quand utiliser chaque format

Structure imbriquée (unflatten=false) : Recommandée pour une meilleure lisibilité et quand votre système supporte les objets imbriqués
Structure plate (unflatten=true) : À utiliser quand votre système ne supporte pas les objets imbriqués ou nécessite une structure de données plate

Pour la documentation complète des composants, du multimédia, des variables de template, de la programmation, des exemples complets, des codes de réponse, des bonnes pratiques et des erreurs courantes, veuillez consulter la version anglaise car les endpoints API, les structures JSON et les exemples de code restent identiques.

📚 Documentation connexe

Authentification - Comment obtenir des tokens d’accès et des clés API
Notifications vocales - Envoyer des appels vocaux automatisés
Gestion des templates - Créer et gérer les templates WhatsApp
Programmation - Gestion avancée de la programmation et des fuseaux horaires
Gestion des erreurs - Codes d’erreur complets et stratégies de gestion
Bonnes pratiques - Directives de sécurité et de performance

​Introduction

​Fonctionnalités clés :

​📣 Envoyer une notification WhatsApp

​Endpoint

​Paramètres de requête

​En-têtes

​📋 Paramètres de requête

​Paramètres requis

​Paramètres optionnels

​👥 Destinataire unique vs multiples

​Utiliser contact - Envoyer à une personne

​Utiliser contacts - Envoyer à plusieurs personnes (Envoi en masse)

​🔄 Formats de structure de données

​Structure imbriquée (unflatten=false ou omis)

​Structure plate (unflatten=true)

​Quand utiliser chaque format

​📚 Documentation connexe