Créer et gérer des modèles

Les modèles sont utilisés lors de l’envoi de modèles de message avec l’API Cloud, hébergés par Meta ou avec l’API On-Premises. L’API Cloud examine les modèles et les paramètres des variables à l’aide du machine learning pour protéger la sécurité et l’intégrité de ses services. Cet examen n’occasionne aucun partage d’informations avec WhatsApp.

Ces modèles peuvent être créés par le biais de l’API Business Management ou de WhatsApp Business Manager. Le nombre de modèles que peut avoir un compte WhatsApp Business est déterminé par son entreprise mère. Si une entreprise mère n’est pas vérifiée, chacun de ses comptes WhatsApp Business est limité à 250 modèles. En revanche, si elle est vérifiée et qu’au moins un de ses comptes WhatsApp Business est associé à un numéro de téléphone professionnel avec un nom à l’écran approuvé, chacun de ses comptes WhatsApp Business peut avoir jusqu’à 6 000 modèles.

Avant de commencer

Vous aurez besoin des éléments suivants :

• Un token d’accès d’utilisateur·ice système lié à l’entreprise
• L’autorisation whatsapp_business_management
• L’ID du compte WhatsApp Business de l’entreprise
• L’alias de l’élément multimédia pour tout document, image ou fichier vidéo à inclure dans un modèle de média. Pour obtenir un alias d’élément multimédia, vous devez charger l’élément à l’aide de l’API d’importation avec reprise.

Limites

• Le champ de nom du modèle de message est limité à 512 caractères.
• Le champ de contenu du modèle de message est limité à 1 024 caractères.
• Un modèle peut être modifié uniquement dans l’état Approuvé, Rejeté ou En pause. Un modèle peut être modifié une fois par jour, et jusqu’à 10 fois par mois.
• Les comptes WhatsApp Business peuvent créer un maximum de 100 modèles de message par heure.
• Les modèles contenant 4 boutons ou plus, ou un bouton de réponse rapide et un ou plusieurs boutons d’un autre type, ne peuvent pas être consultés sur les clients de bureau WhatsApp. Les utilisateur·ices de WhatsApp qui reçoivent l’un de ces modèles de message sont invité·es à consulter le message sur un téléphone à la place.

Localisation

Vous pouvez ajouter un modèle de message dans une langue spécifique lors de la création d’un modèle. Ces modèles entrent dans la comptabilisation de la limite. Respectez une certaine cohérence dans vos traductions. Pour plus d’informations, consultez l’article Pourquoi les erreurs de type « structure indisponible » s’affichent-elles dans mon rappel ? des pages d’aide.

Création de modèles

Pour créer un modèle, envoyez une requête POST au point de terminaison Compte WhatsApp Business > Modèles de message.

Syntaxe de la requête

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

Corps de la requête POST

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "allow_category_change": <ALLOW_CATEGORY_CHANGE>,
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

Propriétés du corps

Catégories de modèles

Les modèles doivent être classés dans l’une des catégories suivantes : Les catégories sont prises en compte dans les tarifs et la catégorie que vous désignez sera validée lors de la création du modèle.

• AUTHENTICATION
• MARKETING
• UTILITY

Consultez notre document Catégorisation des modèles pour déterminer la catégorie à utiliser lors de la création de modèles.

Composants du modèle

Les modèles incluent du texte, du contenu multimédia et des composants interactifs en fonction des besoins de votre entreprise. Consultez le document Composants du modèle qui fournit la liste complète des composants disponibles et de leurs exigences, ainsi que des exemples de requêtes.

Lorsque vous créez un modèle, définissez ses composants en affectant une grille d’objets composants à la propriété components dans le corps de la requête.

Voici un exemple de grille contenant un corps de texte avec deux variables et quelques valeurs, un bouton numéro de téléphone et un bouton URL :

[
  {
    "type": "BODY",
    "text": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
    "example": {
      "body_text": [
        [
          "Pablo","860198-230332"
        ]
      ]
    }
  },
  {
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "PHONE_NUMBER",
        "text": "Call",
        "phone_number": "15550051310"
      },
      {
        "type": "URL",
        "text": "Contact Support",
        "url": "https://www.luckyshrub.com/support"
      }
    ]
  }
]

Consultez le document Composants du modèle qui fournit la liste complète des composants disponibles et de leurs exigences, ainsi que des exemples de requêtes.

Notez que les modèles de la catégorie AUTHENTICATION ont des exigences spécifiques liées à leurs composants. Consultez la page Modèles d’authentification.

Validation de la catégorie

Lorsque vous envoyez une requête de création de modèle, nous validons immédiatement sa catégorie en utilisant nos règles de catégorisation de modèle.

• Si nous acceptons la catégorie que vous avez désignée, nous créons le modèle et définissons son status sur PENDING. Le modèle sera alors soumis à examen.
• Si nous n’acceptons pas votre désignation, nous créons le modèle, mais nous définissons son status sur REJECTED et déclenchons un webhook de mise à jour du statut du modèle de message avec reason défini sur INCORRECT_CATEGORY. Nous vous recommandons d’écouter attentivement ce webhook pour identifier les modèles refusés, ou d’interroger le champ rejected_reason sur les modèles qui viennent d’être créés, lequel aura la valeur TAG_CONTENT_MISMATCH.

Dans les deux cas, le statut initial du modèle est renvoyé avec la réponse de l’API.

Si le statut de votre modèle a été défini sur REJECTED dans le cadre de la validation de la catégorie, vous disposez de plusieurs options :

• Modifier les composants du modèle pour qu’ils soient conformes à nos règles.
• Modifier la catégorie du modèle pour qu’elle soit conforme à nos règles.
• Créer un nouveau modèle.

Catégorisation automatique

Vous pouvez inclure la propriété allow_category_change dans votre requête pour nous permettre d’affecter automatiquement une catégorie en fonction du contenu de votre modèle et de nos règles de catégorisation de modèle. Cela peut éviter que le statut de votre modèle soit défini immédiatement sur REJECTED en raison de l’affectation à une mauvaise catégorie.

Notez que la catégorisation automatique n’est possible que lors de la création d’un modèle.

Examen du modèle

Les modèles ayant le statut PENDING sont soumis à examen. Nous examinons le contenu de chaque modèle venant d’être créé ou modifié pour nous assurer qu’il respecte nos règles et politiques relatives au contenu. Selon les résultats de cet examen, nous modifions automatiquement son statut pour le définir sur APPROVED ou REJECTED, ce qui déclenche un webhook de mise à jour du statut du modèle de message.

Statut du modèle

Selon le résultat de la validation de catégorie et de l’examen du modèle, nous définissons ou modifions le status de votre modèle sur l’une des valeurs suivantes :

• APPROVED : le modèle a passé l’examen avec succès et il a été approuvé, il peut alors être envoyé dans les messages du modèle.
• PENDING : le modèle a passé la validation de catégorie avec succès et il est soumis à examen.
• REJECTED : le modèle a échoué à la validation de catégorie ou à l’examen. Vous pouvez interroger le champ rejected_reason pour en connaître la raison.

Consultez la référence du point de terminaison du modèle de message WhatsApp pour tous les champs et statuts possibles.

Réponse

Si la requête aboutit, l’API renvoie l’ID du modèle que vous venez de créer, son statut et sa catégorie. Il y a trois résultats possibles :

• Nous acceptons la catégorie que vous avez désignée et le modèle est soumis à examen (le status est PENDING).
• Nous n’acceptons pas la catégorie que vous avez désignée (le status est REJECTED)
• Nous avons approuvé automatiquement le modèle (le status est APPROVED). Cela est possible uniquement pour les modèles d’authentification avec des boutons de mot de passe unique.

{
    "id": "<ID>",
    "status": "<STATUS>",
    "category": "<CATEGORY>"
}

Propriétés des réponses

Exemple de requête

Voici un exemple de requête visant à créer un modèle de promotion saisonnière avec les composants suivants :

• un en-tête contenant du texte
• un corps contenant du texte
• un pied de page
• deux boutons de réponse rapide

Pour d’autres exemples, consultez cette section.

curl 'https://graph.facebook.com/v19.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Summer Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of August","25OFF","25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type":"QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Exemple de réponse

{
    "id": "572279198452421",
    "status": "PENDING",
    "category": "MARKETING"
}

Envoi de modèles

Utilisez l’API Cloud ou l’API On-Premises pour envoyer un modèle dans un modèle de message.

Recommandations sur les modèles marketing

Bouton de désinscription marketing

Nous vous recommandons d’ajouter un bouton de réponse rapide aux modèles de catégorie MARKETING pour que votre clientèle puisse facilement se désinscrire de vos messages marketing sans bloquer votre activité. Par conséquent, vous pourrez adapter le volume plus rapidement. Pour découvrir les avantages de l’ajout d’un bouton de désinscription aux modèles marketing, consultez cet article.

Récupérer des modèles

Pour obtenir la liste des modèles appartenant à un compte WhatsApp Business, envoyez une requête GET au point de terminaison Compte WhatsApp Business > Modèles de message.

Syntaxe de la requête

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?fields=<FIELDS>
  &limit=<LIMIT>

Paramètres de la chaîne de requête

Exemple de requête

curl 'https://graph.facebook.com/v19.0/102290129340398/message_templates?fields=name,status&limit=3' \
-H 'Authorization: Bearer EAAJB...'

Exemple de réponse

{
  "data": [
    {
      "name": "seasonal_promotion_text_only",
      "status": "APPROVED",
      "id": "564750795574598"
    },
    {
      "name": "seasonal_promotion_video",
      "status": "PENDING",
      "id": "1252715608684590"
    },
    {
      "name": "seasonal_promotion_image_header",
      "status": "PENDING",
      "id": "1372429296936443"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MgZDZD"
    },
    "next": "https://graph.facebook.com/v19.0/102290129340398/message_templates?fields=name%2Cstatus&limit=3&after=MgZDZD"
  }
}

Exemple de requête (modèles rejetés)

Vous pouvez uniquement renvoyer des modèles avec des valeurs de champs spécifiques en incluant le champ et la valeur souhaitée dans votre requête. Par exemple, ajoutez status=REJECTED pour obtenir uniquement les modèles qui ont été refusés.

curl 'https://graph.facebook.com/v19.0/104996122399160/message_templates?fields=name,status&status=REJECTED' \
-H 'Authorization: Bearer EAAJB...'

Exemple de réponse

{
  "data": [
    {
      "name": "seasonal_promotion_text_only_v4",
      "status": "REJECTED",
      "id": "564750795574598"
    },
    {
      "name": "discount_qualifier",
      "status": "REJECTED",
      "id": "163917509772674"
    },
    {
      "name": "limited_time_offer_tuscan_getaway_2023",
      "status": "REJECTED",
      "id": "202389039167147"
    },
    {
      "name": "2023_mar_promo_2",
      "status": "REJECTED",
      "id": "1116034925734553"
    },
    {
      "name": "2023_mar_promo",
      "status": "REJECTED",
      "id": "952600926095321"
    }
  ]
}

Récupérer l’espace de noms d’un modèle

L’espace de noms du modèle de message est nécessaire pour envoyer des messages avec les modèles.

Pour obtenir l’espace de noms d’un modèle, envoyez une requête GET au point de terminaison /{whatsapp-business-account-ID} et incluez le champ message_template_namespace.

Exemple de requête

curl -i -X GET "https://graph.facebook.com/v19.0/{whatsapp-business-account-ID}
  ?fields=message_template_namespace
  &access_token={system-user-access-token}"

Si la demande aboutit, un objet JSON contenant l’ID du compte WhatsApp Business et l’espace de nom est renvoyé :

{
    "id": "1972385232742141",
    "message_template_namespace": "12abcdefghijk_34lmnop" 
}

Modifier des modèles

Pour modifier un modèle, envoyez une requête POST au point de terminaison Modèle de message WhatsApp. Vous pouvez aussi modifier un modèle manuellement en utilisant le panneau Gestionnaire WhatsApp > Outils du compte > Modèles de message.

Limites

• Vous pouvez uniquement modifier les modèles dont le statut est APPROVED, REJECTED ou PAUSED.
• Vous pouvez uniquement modifier la category ou les components d’un modèle.
• Vous ne pouvez pas modifier la category d’un modèle approuvé.
• Un modèle approuvé peut être modifié jusqu’à 10 fois sur une période de 30 jours, ou 1 fois sur une période de 24 heures. Il n’y a aucune limite de modification pour les modèles refusés ou en pause.
• Un modèle approuvé ou en pause qui a été modifié sera automatiquement approuvé sauf en cas d’échec de l’examen.

Syntaxe de la requête

POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>

Corps de la publication

{
  "category": "<CATEGORY>",
  "components": [<COMPONENTS>]
}

Propriétés

Exemple de requête (Modification des composants)

Exemple de requête pour le corps de texte d’un modèle qui contenait à la fois du contenu marketing et du contenu utilitaire afin qu’il ne contienne plus que du contenu marketing.

curl 'https://graph.facebook.com/v19.0/564750795574598' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Spring Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of April",
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubcribe from Promos"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Exemple de requête (Modification de la catégorie uniquement)

Exemple de requête pour modifier la catégorie du modèle de UTILITY à MARKETING.

curl 'https://graph.facebook.com/v19.0/1252715608684590' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "category": "MARKETING"
}'

Exemple de réponse

Exemple de réponse en cas de réussite.

{
  "success": true
}

Supprimer des modèles

Utilisez le point de terminaison Compte WhatsApp Business > Modèles de message pour supprimer un modèle à partir de son nom ou de son ID.

Remarques

• Si vous supprimez un modèle qui a été envoyé dans un modèle de message, mais qui n’a pas encore été délivré (si le téléphone de l’utilisateur·ice est éteint, par exemple), le modèle aura le statut PENDING_DELETION et nous tenterons de délivrer le message pendant 30 jours. Passé ce délai, vous recevrez une erreur « Structure indisponible », car le message ne sera pas délivré.
• Une fois un modèle approuvé supprimé, son nom ne peut plus être utilisé pendant 30 jours.

Suppression par nom

Tous les modèles portant le même nom, quelle que soit la langue, seront supprimés.

Syntaxe de la requête

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?name=<NAME>

Exemple de requête

curl -X DELETE 'https://graph.facebook.com/v16.0/102290129340398/message_templates?name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Exemple de réponse

{
  "success": true
}

Suppression par ID

Pour supprimer uniquement le modèle avec un ID particulier, la requête doit contenir cet ID en plus du nom du modèle.

Syntaxe de la requête

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?hsm_id=<HSM_ID>,
  &name=<NAME>

Exemple de requête

curl -X DELETE 'https://graph.facebook.com/v19.0/102290129340398/message_templates?hsm_id=1407680676729941&name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Exemple de réponse

{
  "success": true
}

En savoir plus

Étapes suivantes

• Démarrer avec l’API Cloud pour envoyer des messages