> ## 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.

# Gestion des modèles

> Documentation officielle pour la gestion des modèles de messages WhatsApp

## 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).

```json theme={null}
[
  {
    "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.

```json theme={null}
{
  "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 :**

```json theme={null}
{
  "status": "OK",
  "components": ["header_image", "body_text_0", "body_text_1"]
}
```

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

```json theme={null}
{
  "status": "OK",
  "components": ["body_text_0", "body_text_1"]
}
```

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

```json theme={null}
{
  "status": "OK",
  "components": []
}
```

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

```json theme={null}
{
  "status": "OK",
  "components": ["header_video"]
}
```

**Modèle avec document PDF :**

```json theme={null}
{
  "status": "OK",
  "components": ["header_document"]
}
```

**Modèle avec bouton URL dynamique :**

```json theme={null}
{
  "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

```json theme={null}
{
  "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 :**

```json theme={null}
{
  "type": "URL",
  "text": "Texte du bouton",
  "url": "https://example.com/{1}"
}
```

**Bouton de réponse rapide :**

```json theme={null}
{
  "type": "QUICK_REPLY",
  "text": "Texte du bouton"
}
```

### Réponse

```json theme={null}
{
  "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

1. **Soumission** : Le modèle est envoyé à Meta pour examen
2. **Examen** : Meta examine le modèle (généralement 24 à 48 heures)
3. **Approbation/Rejet** : Le modèle est approuvé ou rejeté avec des commentaires
4. **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