API de Gestion des Templates - Lovi AI Documentation

Introduction

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

📋 Obtenir les Templates Disponibles

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

Endpoint

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

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 templates (sans signe ’+’).

Exemple de Requête :

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

Réponse

L’API retourne un tableau d’objets template (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 de status sont en MAJUSCULES : "APPROVED", "PENDING", "REJECTED"
Les valeurs de category sont en MAJUSCULES : "MARKETING", "UTILITY", "AUTHENTICATION"
Chaque template inclut parameter_format (généralement "POSITIONAL")
Le tableau components montre la structure du template mais PAS quels composants sont dynamiques

🔍 Obtenir les Composants d’un Template

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

Endpoint

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

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 template à interroger.

Exemple de Requête :

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

Réponse

Cet endpoint retourne 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" en cas de succès
components : Tableau de chaînes listant les noms des composants dynamiques que vous devez fournir

Exemples de Réponses : Template avec en-tête image et 2 variables de corps :

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

Template avec uniquement des variables de corps (sans média) :

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

Template avec contenu statique uniquement (sans composants dynamiques) :

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

Template avec en-tête vidéo :

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

Template avec document PDF :

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

Template avec bouton URL dynamique :

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

Notes Importantes :

Cet endpoint ne retourne PAS la structure complète du template
Il retourne uniquement les noms des composants que vous devez fournir lors de l’envoi de la notification
Le pied de page et les boutons statiques ne sont PAS inclus (ils sont statiques dans le template)
Les noms des composants suivent le modèle :
- En-têtes : header_image, header_video, header_document (sans numéro de suffixe)
- Variables du corps : body_text_0, body_text_1, body_text_N (avec index)
- URLs des boutons : buttons_url_0, buttons_url_1 (avec index)

🆕 Créer un Nouveau Template

Créez un nouveau template de message WhatsApp pour approbation par Meta.

Endpoint

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 au format JSON.

Corps de la Requête

{
  "company_id": "uuid-company",
  "waba_id": "whatsapp-business-account-id",
  "name_template": "nuevo_template",
  "language_template": "es_ES",
  "category_template": "MARKETING",
  "components_template": {
    "HEADER": {
      "format": "TEXT",
      "text": "Important: {1}"
    },
    "BODY": {
      "text": "Hello {1}, we inform you that {2}. For more information visit {3}."
    },
    "FOOTER": {
      "text": "Support Team"
    },
    "BUTTONS": [
      {
        "type": "URL",
        "text": "View Details",
        "url": "https://example.com/details/{1}"
      },
      {
        "type": "QUICK_REPLY",
        "text": "Contact Support"
      }
    ]
  }
}

Paramètres Requis

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

Catégories de Templates

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

Types de Composants

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

BODY

text : Contenu principal du message
Variables : Utilisez {1}, {2}, etc. pour le contenu dynamique (accolades simples lors de la création du template)

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

BUTTONS

Tableau d’objets bouton : Bouton URL :

{
  "type": "URL",
  "text": "Button Text",
  "url": "https://example.com/{1}"
}

Bouton Réponse Rapide :

{
  "type": "QUICK_REPLY",
  "text": "Button Text"
}

Réponse

{
  "success": true,
  "message": "Template created successfully",
  "template": {
    "id": "new_template_id",
    "name": "nuevo_template",
    "status": "pending",
    "submitted_at": "2024-12-25T10:00:00Z"
  }
}

Processus d’Approbation des Templates

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

Valeurs de Statut des Templates

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

📝 Bonnes Pratiques pour les Templates

Conventions de Nommage

Utilisez uniquement des lettres minuscules
Utilisez des underscores pour les espaces
Soyez descriptif : welcome_new_user vs template1
Incluez la langue si multiple : welcome_es, welcome_en

Directives de Contenu

Soyez Clair : Les templates doivent être facilement compréhensibles
Variables : Utilisez des espaces réservés numérotés {1}, {2}, {3} (WhatsApp utilise des variables positionnelles)
Conformité : Respectez les politiques commerciales de WhatsApp
Tests : Testez avec des données réelles avant la soumission

Raisons Courantes de Rejet

❌ Salutations génériques (“Hello”, “Hi there”)
❌ Langage promotionnel dans les templates UTILITY
❌ Contexte manquant ou objectif peu clair
❌ Utilisation incorrecte des variables
❌ Violations de politique (spam, contenu inapproprié)

Conseils pour l’Approbation

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

🔧 Conseils de Développement

Mettez en cache les informations des templates pour réduire les appels API
Surveillez les changements de statut des templates
Prévoyez des templates de secours pour ceux qui sont rejetés
Utilisez un nommage cohérent dans toute votre organisation
Documentez les templates pour la référence de l’équipe

Documentation API

Documentation Index

​Introduction

​📋 Obtenir les Templates Disponibles

​Endpoint

​Paramètres de Requête

​Réponse

​🔍 Obtenir les Composants d’un Template

​Endpoint

​Paramètres de Requête

​Réponse

​🆕 Créer un Nouveau Template

​Endpoint

​En-têtes

​Corps de la Requête

​Paramètres Requis

​Catégories de Templates

​Types de Composants

​HEADER

​BODY

​FOOTER

​BUTTONS

​Réponse

​Processus d’Approbation des Templates

​Valeurs de Statut des Templates

​📝 Bonnes Pratiques pour les Templates

​Conventions de Nommage

​Directives de Contenu

​Raisons Courantes de Rejet

​Conseils pour l’Approbation

​🔧 Conseils de Développement

Introduction

📋 Obtenir les Templates Disponibles

Endpoint

Paramètres de Requête

Réponse

🔍 Obtenir les Composants d’un Template

Endpoint

Paramètres de Requête

Réponse

🆕 Créer un Nouveau Template

Endpoint

En-têtes

Corps de la Requête

Paramètres Requis

Catégories de Templates

Types de Composants

HEADER

BODY

FOOTER

BUTTONS

Réponse

Processus d’Approbation des Templates

Valeurs de Statut des Templates

📝 Bonnes Pratiques pour les Templates

Conventions de Nommage

Directives de Contenu

Raisons Courantes de Rejet

Conseils pour l’Approbation

🔧 Conseils de Développement