API de gestion des modèles WhatsApp

L'API de gestion des modèles WhatsApp vous permet de répertorier les modèles WhatsApp existants, d'en créer de nouveaux, d'en supprimer et d'importer des fichiers multimédias pour la création de modèles et l'envoi de messages. Bien que les modèles WhatsApp puissent être gérés manuellement via l' WhatsApp Business Manager UI, l'API de gestion des modèles WhatsApp de Vonage vous permet désormais de gérer vos modèles de manière programmatique par le biais de l'API WhatsApp Business.

L'API de gestion des modèles WhatsApp vous permet actuellement d'effectuer les opérations suivantes :

Les objets « Contacts » et « Lieux » de WhatsApp ne peuvent être envoyés qu'en réponse à un message reçu.

La limite de requêtes pour l'API de gestion des modèles WhatsApp est fixée à 40 rps.

Obtenir une liste de modèles

Grâce à l'API de gestion des modèles WhatsApp, vous pouvez obtenir une liste des modèles appartenant au WhatsApp Business Account spécifié. L'API offre certaines fonctionnalités de pagination et de filtrage. Par exemple, vous pouvez filtrer les demandes par modèle status, languageet name_or_content.

Création d'un modèle

Vous pouvez créer des modèles de différents types et catégories, ainsi que plusieurs variantes linguistiques d'un modèle. Lorsque vous créez des modèles avec plusieurs versions linguistiques, veillez à ce que les traductions soient cohérentes d'une version à l'autre.

Veillez à ce que vos modèles respectent Directives concernant les modèles de messages WhatsApp. Le fait de ne pas suivre correctement les lignes directrices peut avoir un impact sur les modèles en cours d'élaboration. approuvé.

Notez que les exigences relatives au contenu et à la composition d'un modèle varient en fonction du modèle. catégorieLes modèles d'authentification sont les plus restreints et les modèles de marketing les plus souples. Les modèles Méta documentation fournit plus d'informations sur ce qui est autorisé pour les différentes catégories de modèles.

Processus d'approbation

Les modèles doivent être approuvés par Meta avant de pouvoir être utilisés dans un message WhatsApp. Lorsqu'ils sont créés, les modèles ont initialement un status de PENDING. Une fois approuvés, ils disposeront d'une status de APPROVEDet peut ensuite être utilisé.

Modèles de messages aux médias

Lorsque vous créez un modèle comportant un en-tête multimédia, commencez par importer le fichier multimédia à l'aide de la commande Point de terminaison de téléchargement pour la création de modèles. Utilisez la valeur renvoyée header_handle uniquement lors de la création ou de la mise à jour du modèle. A header_handle Ce n'est pas un identifiant multimédia de l'API Cloud et il ne peut pas être utilisé lors de l'envoi d'un message.

Pour envoyer un modèle comportant un en-tête multimédia, téléchargez le fichier multimédia à l'aide de la commande point de terminaison de téléchargement au moment de l'envoi, puis utilisez la valeur renvoyée media_id dans la requête correspondante de la Messages API.

Variantes linguistiques

Vous pouvez créer plusieurs variantes d'un modèle pour répondre aux besoins de différentes langues. Pour ce faire, créez un modèle avec le même nom de fichier name et category en tant que modèle existant, et définir language et tout le contenu du texte en fonction de la nouvelle variante linguistique. Une liste des langues prises en charge est disponible dans la section Documentation sur WhatsApp.

Catégories de modèles

À partir du 1er juin 2023, WhatsApp introduit de nouvelles catégories de conversation pour les entreprises qui envoient des messages ; des informations sur ces catégories et leurs prix sont disponibles. ici. Il existe désormais trois catégories de modèles pris en charge pour chacun des types de conversations initiées par les entreprises :

  • UTILITY: Permettre la réalisation d'une demande ou d'une transaction particulière, convenue, ou fournir à un client une mise à jour sur une transaction en cours, y compris des notifications après achat et des relevés de facturation réguliers.
  • AUTHENTICATION: Permet aux entreprises d'utiliser des codes de passe à usage unique pour vérifier les utilisateurs à différentes étapes de la connexion, si nécessaire (par exemple, vérification de compte, récupération de compte, défis d'intégrité).
  • MARKETING: Conversations initiées par les entreprises pour commercialiser un bien ou un service auprès des clients, comme l'envoi d'offres pertinentes aux clients qui ont choisi de s'inscrire. Cela inclut également toute interaction liée à l'entreprise qui n'est pas une conversation d'authentification ou d'utilité.

Tous les modèles existants dans l'une de ces catégories seront migrés vers l'une des nouvelles catégories de modèles : TRANSACTIONAL, MARKETING, OTP, ACCOUNT_UPDATE, PAYMENT_UPDATE, PERSONAL_FINANCE_UPDATE, SHIPPING_UPDATE, RESERVATION_UPDATE, ISSUE_RESOLUTION, APPOINTMENT_UPDATE, TRANSPORTATION_UPDATE, TICKET_UPDATE, ALERT_UPDATE ou AUTO_REPLY.

Remarque : un compte professionnel WhatsApp non vérifié peut avoir un maximum de 250 modèles de messages, tandis qu'un compte professionnel WhatsApp non vérifié peut avoir un maximum de 250 modèles de messages. compte d'entreprise vérifié peut avoir un maximum de 6000 modèles de messages. Chaque variante linguistique compte pour un modèle ; par exemple, un modèle de message appelé hello_world traduit en deux langues compte comme un modèle à deux messages en ce qui concerne cette limite.

Un compte WhatsApp Business peut créer un maximum de 100 modèles de messages par heure.

Suppression d'un modèle

Vous pouvez supprimer un modèle associé à un WhatsApp Business Account spécifique en spécifiant le modèle par son nom ou via son identifiant. Si un modèle particulier a plusieurs versions linguistiques pour le même nom, tous pour ce nom de modèle seront supprimées.

Une fois supprimé, le nom du modèle (approuvé) ne peut plus être utilisé pendant 30 jours.

Les messages envoyés pour un modèle supprimé peuvent encore être délivrés à l'intérieur 30 jours s'ils ont été envoyés mais n'ont pas encore été livrés.

Mise à jour d'un modèle

Vous pouvez mettre à jour un modèle existant identifié par son ID. Il y a quelques points à garder à l'esprit lors de la modification d'un modèle :

  1. Les modèles de messages ne peuvent être modifiés que lorsqu'ils se trouvent dans un formulaire de demande d'information. Approved, Rejectedou Paused état.
  2. Lors de la modification d'un modèle en ligne, les modèles pourront faire l'objet d'une approbation automatique. Les modèles qui passent les contrôles de formatage et de politique commerciale seront immédiatement remis en ligne, sans qu'aucune action supplémentaire ne soit nécessaire pour continuer à envoyer des messages utilisant déjà ces modèles.
  3. Lors de l'édition d'un Paused les modèles pourront faire l'objet d'une approbation automatique. Les modèles qui passent avec succès les contrôles de formatage et les contrôles de la politique commerciale pourront à nouveau être mis en ligne. Pour commencer à envoyer des messages à l'aide de ces modèles, les entreprises devront faire appel à l'API de messagerie.
  4. Le point de terminaison "Mise à jour" vous permet de modifier la catégorie du modèle. Une fois la demande soumise avec succès, vous pourrez voir à la fois la "catégorie_précédente" et la "catégorie" mise à jour lorsque vous utiliserez le point de terminaison "Liste des modèles".
  5. Les modèles de messages approuvés peuvent être modifiés jusqu'à 10 fois par période de 30 jours ou 1 fois par période de 24 heures. Les messages rejetés ou en pause peuvent être modifiés un nombre illimité de fois.

Téléchargement de fichiers multimédias pour la création de modèles

N'utilisez ce point de terminaison que pour créer ou mettre à jour un modèle comportant un en-tête multimédia. Il renvoie un objet Meta de type « resumable-upload ». header_handle, que vous devez intégrer dans le composant « media-header » du modèle. Ce identifiant est valable pendant 30 jours et ne peut pas être utilisé pour envoyer un message WhatsApp de type « modèle », « interactif » ou « libre ».

Les header_handle La valeur renvoyée par ce point de terminaison n'est pas un identifiant de média de l'API Cloud. Ne l'utilisez pas comme identifiant de pièce jointe au moment de l'envoi.

Remarque : un délai d'expiration peut survenir si vous essayez de télécharger des fichiers multimédias volumineux (par exemple, supérieurs à 25 Mo). Dans ce cas, nous vous recommandons d'utiliser l'interface utilisateur de WhatsApp Business Manager pour télécharger ces fichiers.

Exemple de requête cURL

curl --location 'https://api.nexmo.com/v2/whatsapp-manager/media/uploads?file_type=image%2Fjpg' \
--header 'Authorization: Basic NTE1...g==' \
--form 'mediafile=@"Directory/WhatsApp_Image.jpeg"'

Téléchargement de fichiers multimédias à envoyer

Utilisez ce point de terminaison pour télécharger des fichiers multimédias une seule fois avant d'envoyer un message WhatsApp de type « modèle multimédia », « interactif » ou « libre ». Il sert d'intermédiaire à l'API Media Upload de Meta et renvoie une API Cloud stable. media_id. Utilisez cet identifiant dans la Messages API correspondante media_id champ au lieu d'une URL publique.

L'utilisation d'une URL publique oblige Meta à télécharger le fichier multimédia à chaque envoi, ce qui peut entraîner des 131053 erreurs de téléchargement de fichiers multimédias. Le header_handle provenant du point de terminaison de création de modèles n'est acceptée que lors de la création ou de la mise à jour de modèles et est rejetée au moment de l'envoi.

Point final

POST https://api.nexmo.com/v2/whatsapp-manager/numbers/{phone_number}/media?file_type=image/jpg

La requête utilise multipart/form-data et comprend le file champ. Définir file_type au type MIME du média.

Exemple de requête cURL

curl --location 'https://api.nexmo.com/v2/whatsapp-manager/numbers/447700900001/media?file_type=image%2Fjpg' \
--header 'Authorization: Basic NTE1...g==' \
--form 'file=@"c:/local/media/assets/image.jpg"'

Exemple de réponse

{
  "media_id": "1037543291543636"
}