Gestion des modèles - Lovi AI Documentation

Introduction

Les points de terminaison de gestion des modèles permettent de récupérer, inspecter et créer des modèles de messages WhatsApp. Les modèles sont des formats de messages pré-approuvés requis par WhatsApp pour les communications professionnelles.

📋 Modèles disponibles

Récupérez tous les modèles disponibles pour votre entreprise et votre numéro de téléphone.

Point de terminaison

GET https://cloud.lovi.ai/functions/v1/notify/templates?access_key={VOTRE_CLE_D_ACCES}&phone_number={NUMERO_DE_TELEPHONE}

Paramètres de requête

Paramètre	Requis	Description
`access_key`	Oui	Votre clé d’accès API unique.
`phone_number`	Oui	Numéro de téléphone pour filtrer les modèles (sans le signe ’+’).

Exemple de requête:

GET https://cloud.lovi.ai/functions/v1/notify/templates?access_key=votre-cle-api&phone_number=34666033135

Réponse

L’API renvoie un tableau d’objets de modèle (non encapsulé dans un objet).

[
  {
    "id": "696796403510039",
    "name": "welcome_message",
    "status": "APPROVED",
    "category": "MARKETING",
    "language": "en",
    "components": [
      {
        "text": "Welcome! This is a test message.",
        "type": "BODY"
      }
    ],
    "parameter_format": "POSITIONAL"
  },
  {
    "id": "1269099831552940",
    "name": "order_confirmation",
    "status": "APPROVED",
    "category": "MARKETING",
    "language": "es",
    "components": [
      {
        "text": "Hello `{"{1}"}`, your order `{"{2}"}` is ready!",
        "type": "BODY",
        "example": {
          "body_text": [["John", "Premium Package"]]
        }
      }
    ],
    "parameter_format": "POSITIONAL"
  },
  {
    "id": "2616178978766893",
    "name": "promo_with_image",
    "status": "APPROVED",
    "category": "MARKETING",
    "language": "es",
    "components": [
      {
        "type": "HEADER",
        "format": "IMAGE",
        "example": {
          "header_handle": ["https://example.com/image.jpg"]
        }
      },
      {
        "text": "Check out our special offer!",
        "type": "BODY"
      },
      {
        "text": "Thank you for choosing us!",
        "type": "FOOTER"
      }
    ],
    "parameter_format": "POSITIONAL"
  }
]

Notes importantes :

La réponse est un tableau direct, pas un objet avec une clé “templates”
Les valeurs status sont en MAJUSCULES : "APPROVED", "PENDING", "REJECTED"
Les valeurs category sont en MAJUSCULES : "MARKETING", "UTILITY", "AUTHENTICATION"
Chaque modèle inclut parameter_format (généralement "POSITIONAL")
Le tableau components montre la structure du modèle mais PAS quels composants sont dynamiques

🔍 Obtenir les composants du modèle

Récupérez des informations détaillées sur les composants et la structure d’un modèle spécifique.

Point de terminaison

GET https://cloud.lovi.ai/functions/v1/notify/template/components?access_key={VOTRE_CLE_D_ACCES}&template={ID_DU_MODELE}

Paramètres de requête

Paramètre	Requis	Description
`access_key`	Oui	Votre clé d’accès API unique.
`template`	Oui	ID ou nom du modèle à interroger.

Exemple de requête:

GET https://cloud.lovi.ai/functions/v1/notify/template/components?access_key=votre-cle-api&template=template_001

Réponse

Ce point de terminaison renvoie UNIQUEMENT les composants dynamiques que vous devez fournir lors de l’envoi d’une notification.

{
  "status": "OK",
  "components": ["header_image", "body_text_0", "body_text_1"]
}

Structure de la réponse :

status : Toujours "OK" si réussi
components : Tableau de chaînes listant les noms des composants dynamiques à fournir

Exemples de réponses : Modèle avec en-tête image et 2 variables de corps :

{
  "status": "OK",
  "components": ["header_image", "body_text_0", "body_text_1"]
}

Modèle avec uniquement des variables de corps (pas de média) :

{
  "status": "OK",
  "components": ["body_text_0", "body_text_1"]
}

Modèle avec uniquement du contenu statique (pas de composants dynamiques) :

{
  "status": "OK",
  "components": []
}

Modèle avec en-tête vidéo :

{
  "status": "OK",
  "components": ["header_video"]
}

Modèle avec document PDF :

{
  "status": "OK",
  "components": ["header_document"]
}

Modèle avec bouton URL dynamique :

{
  "status": "OK",
  "components": ["buttons_url_0"]
}

Notes importantes :

Ce point de terminaison ne renvoie PAS la structure complète du modèle
Il renvoie uniquement les noms des composants à fournir lors de l’envoi de la notification
Les pieds de page et les boutons statiques ne sont PAS inclus (ils sont statiques dans la définition du modèle)
Les noms de composants suivent le modèle :
- En-têtes : header_image, header_video, header_document (sans suffixe numérique)
- Variables de corps : body_text_0, body_text_1, body_text_N (avec indice)
- URL des boutons : buttons_url_0, buttons_url_1 (avec indice)

🆕 Créer un nouveau modèle

Créez un nouveau modèle de message WhatsApp pour approbation par Meta.

Point de terminaison

POST https://cloud.lovi.ai/functions/v1/admin/whatsapp/create/template

En-têtes

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

Corps de la requête

{
  "company_id": "uuid-entreprise",
  "waba_id": "whatsapp-business-account-id",
  "name_template": "nouveau_modele",
  "language_template": "es_ES",
  "category_template": "MARKETING",
  "components_template": {
    "HEADER": {
      "format": "TEXT",
      "text": "Important : {1}"
    },
    "BODY": {
      "text": "Bonjour {1}, nous vous informons que {2}. Pour plus d'informations, visitez {3}."
    },
    "FOOTER": {
      "text": "Équipe de support"
    },
    "BUTTONS": [
      {
        "type": "URL",
        "text": "Voir les détails",
        "url": "https://example.com/details/{1}"
      },
      {
        "type": "QUICK_REPLY",
        "text": "Contacter le support"
      }
    ]
  }
}

Paramètres requis

Paramètre	Type	Description	Exemple
`company_id`	String	Identifiant unique de l’entreprise	`"uuid-company"`
`waba_id`	String	Identifiant du compte WhatsApp Business	`"123456789"`
`name_template`	String	Nom du modèle (minuscules, underscores)	`"order_confirmation"`
`language_template`	String	Code de langue	`"es_ES"`, `"en_US"`
`category_template`	String	Catégorie du modèle	`"MARKETING"`, `"UTILITY"`
`components_template`	Objet	Structure des composants du modèle	Voir l’exemple ci-dessus

Catégories de modèles

Catégorie	Description	Cas d’utilisation
`MARKETING`	Messages promotionnels	Offres, annonces
`UTILITY`	Messages transactionnels	Mises à jour de commande, alertes
`AUTHENTICATION`	Messages de sécurité et vérification	Codes OTP, confirmations

Types de composants

EN-TÊTE

format : "TEXT", "IMAGE", "VIDEO", "DOCUMENT"
text : Contenu textuel (uniquement pour le format TEXT)
example : Exemple pour les variables

CORPS

text : Contenu principal du message
Variables : Utilisez {1}, {2}, etc. pour le contenu dynamique

PIED DE PAGE

text : Texte du pied de page (statique uniquement, pas de variables)

BOUTONS

Tableau d’objets bouton : Bouton URL :

{
  "type": "URL",
  "text": "Texte du bouton",
  "url": "https://example.com/{1}"
}

Bouton de réponse rapide :

{
  "type": "QUICK_REPLY",
  "text": "Texte du bouton"
}

Réponse

{
  "success": true,
  "message": "Modèle créé avec succès",
  "template": {
    "id": "new_template_id",
    "name": "nouveau_modele",
    "status": "pending",
    "submitted_at": "2024-12-25T10:00:00Z"
  }
}

Processus d’approbation des modèles

Soumission : Le modèle est envoyé à Meta pour examen
Examen : Meta examine le modèle (généralement 24 à 48 heures)
Approbation/Rejet : Le modèle est approuvé ou rejeté avec des commentaires
Utilisation : Les modèles approuvés peuvent être utilisés dans les notifications

Statuts des modèles

Statut	Description
`pending`	Soumis pour examen
`approved`	Approuvé et prêt à l’emploi
`rejected`	Rejeté (vérifier les commentaires)
`disabled`	Temporairement désactivé

📝 Bonnes pratiques pour les modèles

Conventions de nommage

Utilisez uniquement des lettres minuscules
Utilisez des underscores pour les espaces
Soyez descriptif : welcome_new_user plutôt que template1
Incluez la langue si vous en avez plusieurs : welcome_es, welcome_en

Directives de contenu

Soyez clair : Les modèles doivent être facilement compréhensibles
Variables : Utilisez des espaces réservés numérotés {1}, {2}, {3}
Conformité : Respectez les politiques commerciales de WhatsApp
Test : Testez avec de vraies données avant la soumission

Raisons courantes de rejet

❌ Salutations génériques (“Bonjour”, “Salut”)
❌ Langage promotionnel dans les modèles UTILITY
❌ Contexte manquant ou but non clair
❌ Utilisation incorrecte des variables
❌ Violations des politiques (spam, contenu inapproprié)

Conseils d’approbation

✅ Incluez un contexte commercial spécifique
✅ Utilisez un langage clair et professionnel
✅ Fournissez des exemples significatifs
✅ Suivez les directives de modèles WhatsApp
✅ Testez soigneusement la substitution des variables

🔧 Conseils de développement

Mettez en cache les informations de modèle pour réduire les appels API
Surveillez les changements de statut des modèles
Ayez des modèles de secours pour ceux qui sont rejetés
Utilisez une convention de nommage cohérente dans votre organisation
Documentez les modèles pour référence de l’équipe

​Introduction

​📋 Modèles disponibles

​Point de terminaison

​Paramètres de requête

​Réponse

​🔍 Obtenir les composants du modèle

​Point de terminaison

​Paramètres de requête

​Réponse

​🆕 Créer un nouveau modèle

​Point de terminaison

​En-têtes

​Corps de la requête

​Paramètres requis

​Catégories de modèles

​Types de composants

​EN-TÊTE

​CORPS

​PIED DE PAGE

​BOUTONS

​Réponse

​Processus d’approbation des modèles

​Statuts des modèles

​📝 Bonnes pratiques pour les modèles

​Conventions de nommage

​Directives de contenu

​Raisons courantes de rejet

​Conseils d’approbation

​🔧 Conseils de développement

Introduction

📋 Modèles disponibles

Point de terminaison

Paramètres de requête

Réponse

🔍 Obtenir les composants du modèle

Point de terminaison

Paramètres de requête

Réponse

🆕 Créer un nouveau modèle

Point de terminaison

En-têtes

Corps de la requête

Paramètres requis

Catégories de modèles

Types de composants

EN-TÊTE

CORPS

PIED DE PAGE

BOUTONS

Réponse

Processus d’approbation des modèles

Statuts des modèles

📝 Bonnes pratiques pour les modèles

Conventions de nommage

Directives de contenu

Raisons courantes de rejet

Conseils d’approbation

🔧 Conseils de développement