WhatsApp Template API

API développeur

Envoyez des modèles WhatsApp approuvés depuis vos propres systèmes avec un seul appel API ; la conversation se poursuit ensuite dans MonoChat.

• WhatsApp
• API REST
• API uniquement

Installer depuis MonoStoreVoir sur monochat.ai

Présentation

WhatsApp Template API permet à votre CRM, ERP, site e-commerce ou à tout backend d’envoyer un modèle de message WhatsApp approuvé à un client via MonoChat. Une seule requête indique le numéro WhatsApp d’envoi, le numéro de téléphone du client, le modèle et ses variables.

Quand le client répond, la conversation arrive dans votre boîte de réception MonoChat comme n’importe quelle autre. L’application n’a pas d’écrans propres : tout passe par trois endpoints API.

Points forts

• Un seul appel API. Envoyez un modèle par nom et par langue, avec les variables d’en-tête, de corps, de bouton et de carrousel renseignées à partir de vos données.
• Directement dans le chat. Chaque envoi renvoie l’identifiant de la conversation et un lien direct vers celle-ci dans MonoChat.
• Les nouveaux clients sont les bienvenus. Si le numéro de téléphone n’est pas encore un client, le client est créé avec le nom que vous envoyez.

Installation et configuration

1. Connectez votre numéro WhatsApp Business à MonoChat et assurez-vous qu’il est vérifié et dispose de modèles approuvés par Meta.
2. Installez WhatsApp Template API depuis Paramètres › MonoStore › Applications, ou ouvrez le lien d’installation app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Sans compte MonoChat, le lien vous permet de vous inscrire d’abord, puis installe l’application pour vous.
3. Créez un jeton d’API sous Profil › Jetons d'API. Le jeton n’est affiché qu’une seule fois : copiez-le immédiatement.
4. Appelez template/list.js pour voir vos modèles approuvés et leurs variables.
5. Appelez template/send.js avec le numéro du client et les valeurs des variables pour envoyer votre premier modèle.

remarque

• Chaque message est facturé comme n’importe quel message modèle envoyé depuis MonoChat.
• Les URL de médias doivent rester accessibles jusqu’à ce que WhatsApp ait récupéré le fichier.
• Envoyez aux clients qui ont accepté d’être contactés : WhatsApp peut limiter les numéros dont les messages sont bloqués ou signalés.

Fonctionnalités

Lister les modèles

Les modèles approuvés d’un numéro WhatsApp, avec leur langue, catégorie, statut et variables, pour que votre système sache ce qu’il peut envoyer.

Envoyer un modèle

Par nom et langue de modèle, avec les variables d’en-tête, de corps, de bouton et de carrousel. Une valeur manquante bloque l’envoi : rien de partiellement rempli n’arrive donc au client.

Attribuer à un agent

Indiquez l’e-mail d’un agent et la conversation est ouverte à son nom.

En-têtes multimédias

Obtenez des identifiants de téléversement temporaires, déposez une image, une vidéo ou un document sur le stockage de MonoChat et utilisez son URL comme en-tête du modèle.

Lien de conversation

Chaque envoi renvoie l’identifiant de session, l’identifiant du message et un lien qui ouvre la conversation dans MonoChat.

Erreurs claires

Un appel en échec indique ce qui s’est mal passé, par exemple « Channel not found » ou « Variable missing ».

Avant de commencer

• Votre numéro WhatsApp Business est connecté à MonoChat et vérifié. Consultez Canaux.
• Les modèles que vous voulez envoyer sont approuvés par Meta. Les modèles sont le moyen d’écrire en premier, ou de joindre un client en dehors de la fenêtre de 24 heures. Consultez Messages modèles.
• Vous disposez d’un jeton d’API obtenu sous Profil › Jetons d'API. Consultez Jetons d’API.
• Vous connaissez votre tenant slug : la partie après /tenants/ dans votre adresse MonoChat. Dans https://app.monochat.ai/tenants/mybusiness, le slug est mybusiness.

Référence de l’API

L’application n’a pas d’écrans propres. Tout passe par trois endpoints, chacun une requête POST avec un corps JSON :

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Endpoint	Ce qu’il fait
template/list.js	Liste les modèles de l’un de vos numéros WhatsApp, avec leurs variables.
template/send.js	Envoie un modèle à un client et renvoie un lien vers la conversation.
upload/get-token.js	Fournit des identifiants de téléversement temporaires pour une image, une vidéo ou un document d’en-tête.

Les numéros de téléphone s’écrivent toujours avec l’indicatif du pays et sans +, par exemple 905334445566. Un appel réussi répond 200 avec les données de l’endpoint sous result.

1. Lister les modèles

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Liste tous les modèles du numéro WhatsApp Business indiqué : nom, code de langue, catégorie, composants (en-tête, corps, pied de page, boutons), types de variables et statut d’approbation.

Champ	Obligatoire	Description
phoneNumber	oui	Votre numéro WhatsApp Business dans MonoChat, avec l’indicatif du pays, sans +.
options	non	Pagination et filtres, par exemple { "pagination": { "currentPage": 1, "pageItems": 50 } }.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Réponse (abrégée) :

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

Comment la lire :

• name : le nom système avec lequel vous envoyez le modèle.
• languageCode : la langue d’envoi.
• category : la catégorie WhatsApp (MARKETING, UTILITY, AUTHENTICATION).
• components : les parties dont le modèle est composé.

Composant	Contenu	Description
HEADER	IMAGE, VIDEO, DOCUMENT ou texte	Pour un média, le format est indiqué ; les variables figurent sous variables.
BODY	Texte avec variables	Le corps du message, avec des espaces réservés comme {{1}}, {{2}}.
FOOTER	Texte	N’a généralement pas de variables.
BUTTONS	URL, réponse rapide…	Les textes des boutons et leurs variables, le cas échéant.

Le modèle d’exemple ci-dessus nécessite une image pour l’en-tête et deux textes pour le corps (nom du client et nom du produit). Le pied de page est fixe (« Teşekkürler ») et il n’y a pas de boutons.

2. Envoyer un modèle

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Envoie un modèle approuvé à un client. Si le numéro de téléphone n’est pas encore un client, le client est créé ; la conversation est ouverte (ou réutilisée) et le modèle y est envoyé.

Champ	Obligatoire	Description
phoneNumber	oui	Le numéro WhatsApp Business d’envoi. Il doit être connecté à MonoChat et vérifié.
templateMessageName	oui	Le name du modèle, exactement tel que la liste le renvoie.
languageCode	oui	La langue du modèle, telle que la liste la renvoie (par exemple tr-TR).
customerPhoneNumber	oui	Le numéro WhatsApp du client.
variables	si le modèle en comporte	Les valeurs des variables du modèle (voir ci-dessous).
customerFirstName, customerLastName	non	Utilisés lorsque le client est nouveau dans MonoChat.
agentEmailAddress	non	Attribue la conversation à l’agent ayant cet e-mail.

Variables. Chaque élément du tableau variables a un type et une liste de parameters, donnés dans l’ordre des espaces réservés du modèle :

type	parameters
HEADER	La variable de texte de l’en-tête, ou l’URL publique de l’image, de la vidéo ou du document d’en-tête.
BODY	Les {{1}}, {{2}}, … du corps, dans l’ordre.
BUTTONS	Une valeur pour chaque bouton qui a une variable (par exemple la partie dynamique d’un bouton URL ou un code promo), dans l’ordre des boutons.
CAROUSEL	À la place de parameters, un tableau cards avec une entrée par carte du carrousel, chacune avec ses propres components.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

Une valeur manquante bloque l’envoi avec Variable missing : rien de partiellement rempli n’arrive donc au client. FOOTER a rarement des variables.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

Réponse :

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

• url : ouvre la conversation dans MonoChat, pour les personnes connectées et autorisées à la voir.
• sessionId : l’identifiant de la conversation.
• messageId : l’identifiant du message dans MonoChat. Son statut de livraison et de lecture apparaît dans le chat comme pour n’importe quel autre message.

Médias dans les modèles. WhatsApp télécharge le média d’en-tête depuis l’URL que vous indiquez : l’URL doit donc être valide et accessible publiquement. Les liens qui exigent une connexion ne fonctionnent pas. Si vous avez téléversé le fichier avec upload/get-token.js, utilisez l’URL du fichier construite à partir de cette réponse.

3. Téléverser un média pour un en-tête

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

Quand l’en-tête d’un modèle est une image, une vidéo ou un document, le fichier a besoin d’une adresse publique depuis laquelle WhatsApp peut le télécharger. Cet endpoint vous donne une autorisation temporaire pour déposer le fichier sur le stockage de MonoChat.

Champ	Obligatoire	Description
fileName	oui	Le nom du fichier avec son extension, par exemple product.jpg ou promo.pdf.

Les fichiers sont toujours stockés dans le dossier chat-assets de votre espace de travail ; les anciens exemples qui envoient un champ key continuent de fonctionner, la valeur n’est pas nécessaire.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

La réponse indique où déposer le fichier et fournit les identifiants pour le faire :

Champ	Description
bucket, region, path	L’emplacement du fichier.
temporaryCredentials	Identifiants valables uniquement pour téléverser vers ce chemin, valides 15 minutes.
baseUrl	L’adresse publique du stockage. L’URL du fichier est baseUrl + / + path.

Téléversez le fichier immédiatement avec n’importe quel client S3 en utilisant ces identifiants, puis passez son URL comme paramètre HEADER lors de l’envoi du modèle. Les fichiers très volumineux ou les formats que WhatsApp ne prend pas en charge (il accepte les formats courants d’image, de vidéo et de PDF) échouent.

Exemple : un modèle avec un en-tête image

Imaginons que vous avez un modèle approuvé new_product_announcement avec un en-tête image et deux variables de corps (nom du client et nom du produit), et que vous voulez l’envoyer à un client.

1. Listez les modèles. Appelez template/list.js avec votre numéro WhatsApp et trouvez new_product_announcement. Ses composants montrent une variable IMAGE dans l’en-tête et deux variables TEXT dans le corps.
2. Téléversez l’image. Appelez upload/get-token.js avec { "fileName": "urun.jpg" }, téléversez le fichier avec les identifiants renvoyés et construisez son URL à partir de baseUrl et path.
3. Envoyez le modèle. Appelez template/send.js avec l’URL du fichier comme paramètre HEADER et ["Ayşe", "XYZ Telefon"] comme paramètres BODY ({{1}} → Ayşe, {{2}} → XYZ Telefon). Si le modèle avait des variables de bouton, vous ajouteriez un élément BUTTONS de la même façon.
4. Ouvrez le chat. L’url de la réponse ouvre la conversation ; quand le client répond, elle se poursuit dans votre boîte de réception MonoChat.

Erreurs

Un appel qui échoue répond avec un statut d’erreur et un message qui indique ce qui s’est mal passé. Journalisez ces messages dans votre système et affichez un message explicite à vos utilisateurs si nécessaire.

Message	Cause
phoneNumber field is required	template/list.js a été appelé sans phoneNumber.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	Un champ obligatoire de template/send.js est manquant.
Channel not found	Le phoneNumber n’est pas un numéro WhatsApp de votre espace de travail.
Channel is not verified	Le numéro WhatsApp est connecté mais non vérifié.
Template message not found	Aucun modèle approuvé avec ce nom et cette langue sur le numéro. Vérifiez l’orthographe et languageCode.
Template message is not approved	Le modèle existe mais n’est pas approuvé par Meta.
Variable missing: …	variables ne correspond pas au modèle, par exemple le modèle attend deux valeurs de corps et vous en avez envoyé une.
Agent user not found	Aucun agent avec l’e-mail indiqué dans agentEmailAddress.
Customer Channel not found	L’identité WhatsApp du client n’a pas pu être créée ou trouvée.

Codes de statut HTTP que vous pouvez rencontrer :

• 401 Unauthorized : l’en-tête Authorization: Bearer <API_TOKEN> est manquant, ou le jeton est incorrect ou expiré. Utilisez un jeton valide de votre compte.
• 403 Forbidden : le jeton n’a pas accès à cet espace de travail ou à cette application, par exemple à cause d’un tenant slug incorrect.
• 404 Not Found : l’adresse de l’endpoint est incorrecte. Vérifiez le chemin complet /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error : un problème inattendu dans MonoChat ou chez le fournisseur WhatsApp, ou un refus côté WhatsApp (le numéro n’est pas sur WhatsApp, le client vous a bloqué, limites de qualité ou de débit). Réessayez plus tard et contactez le support MonoChat si le problème persiste.

Captures d’écran

Envoi d’un modèle WhatsApp approuvé depuis un CRM, un ERP ou un système e-commerce avec un seul appel API via MonoChatLa liste des modèles WhatsApp approuvés avec leurs variablesL’envoi d’un modèle à un nouveau numéro crée automatiquement le clientUn même modèle envoyé en plusieurs languesModèles avec en-têtes image, vidéo, document et PDF

FAQ

WhatsApp Template API a-t-elle une interface utilisateur ?

Non. C’est une application uniquement API avec trois endpoints : lister les modèles, envoyer un modèle et obtenir des identifiants de téléversement pour les en-têtes multimédias.

De quoi ai-je besoin avant de pouvoir l’utiliser ?

Un numéro WhatsApp Business connecté à MonoChat et vérifié, des modèles approuvés par Meta et un jeton API obtenu sous Profil › Jetons d'API.

Que se passe-t-il quand le client répond ?

La conversation arrive dans votre boîte de réception MonoChat comme n’importe quelle autre. Chaque envoi renvoie aussi un lien direct vers la conversation, et vous pouvez l’attribuer à un agent par e-mail.

Puis-je envoyer à un numéro qui n’est pas encore un client ?

Oui. Si le numéro de téléphone n’est pas encore un client, le client est créé avec le nom que vous envoyez.

Combien coûtent les messages modèles ?

Chaque message est facturé comme n’importe quel message modèle envoyé depuis MonoChat. Meta tarife les modèles selon la catégorie et le pays du destinataire ; utilisez le calculateur de coût d’envoi en masse WhatsApp pour estimer un envoi.

Voir aussi

• Session Link
• Bulk Template Message API
• Messages modèles
• Applications MonoStore