Avec Papo (https://papo.global/), vous pouvez utiliser l'API REST pour lister les conversations, envoyer des messages texte, appliquer des étiquettes et attribuer des conversations à des agents, en automatisant les processus de service client sans accéder à l'interface. L'API offre des endpoints qui reflètent les fonctionnalités du module Conversations, permettant à des systèmes externes de gérer les interactions de manière programmatique.
| Action de l'API | Ce qu'elle fait | Exemple d'utilisation |
|---|---|---|
| Lister les conversations | Renvoie les conversations du compte, avec des filtres par statut, étiquette ou agent | Surveiller les conversations actives ou fermées depuis un CRM externe |
| Envoyer un message texte | Envoie un message texte à un contact (dans la limite de la fenêtre de 24 h de WhatsApp) | Notifier un client d'une mise à jour de commande |
| Appliquer une étiquette | Crée une étiquette (si elle n'existe pas) et l'applique au contact et à la conversation ouverte | Marquer automatiquement les conversations comme « Urgent » ou « Après-vente » |
| Attribuer une conversation | Attribue les conversations ouvertes d'un contact à un agent spécifique | Diriger les prospects vers le commercial responsable de la région |
Comment fonctionne l'API de Conversations de Papo
L'API de Papo suit le standard REST, avec une authentification via une clé secrète (Bearer token) et des réponses au format JSON. Toutes les opérations décrites ici utilisent la même base d'authentification et peuvent être combinées pour créer des flux de travail automatisés — par exemple, un système de tri qui, à la réception d'un nouveau prospect, liste les conversations récentes, applique une étiquette « Nouveau » et l'attribue à l'agent de permanence.
La base de l'API est https://app.papo.global/api/v1. Pour utiliser les endpoints de conversations, d'étiquettes et d'attributions, vous avez besoin d'un token d'API généré dans le panneau de Papo. La documentation complète avec les endpoints spécifiques et les paramètres est disponible sur papo.global/pt/docs.
Étape par étape pour utiliser les ressources de l'API
1. Générez un token d'API
Dans le panneau de Papo, accédez à la section développeur ou tokens d'accès. Créez une clé secrète (sk_live_…) avec les permissions appropriées pour gérer les conversations. Conservez le token en lieu sûr — il sera envoyé dans l'en-tête Authorization de toutes les requêtes.
2. Listez les conversations
Utilisez l'endpoint de listage des conversations pour obtenir les conversations du compte. La requête accepte des paramètres de filtre tels que :
- Statut : conversations ouvertes, fermées ou toutes.
- Étiquette : filtre par une ou plusieurs étiquettes appliquées.
- Agent : restreint aux conversations attribuées à un utilisateur spécifique.
- Période : intervalle de dates pour limiter la requête.
La réponse inclut l'identifiant de la conversation, le contact, le canal, le statut et les derniers messages. Avec ces données, vous pouvez surveiller le volume de conversations ou déclencher des actions conditionnelles à partir d'un système externe.
3. Envoyez un message texte
Pour envoyer un message texte à un contact, utilisez l'endpoint d'envoi de messages. La requête exige :
- Numéro du destinataire au format international (ex. :
5511999999999). - Texte du message.
- Identifiant de l'instance (facultatif) — si votre compte dispose de plusieurs connexions WhatsApp, vous pouvez spécifier laquelle utiliser.
L'API renvoie une confirmation que la demande a été acceptée. Rappelez-vous que l'envoi de messages texte est soumis à la fenêtre de 24 heures de WhatsApp ; pour les communications en dehors de cette période, il est nécessaire d'utiliser des modèles de message (HSM) préalablement approuvés.
4. Appliquez des étiquettes aux contacts et aux conversations
L'API permet de gérer les étiquettes de deux manières :
- Créer une étiquette sur le compte : définissez un titre, une couleur et une description pour la nouvelle étiquette.
- Appliquer une étiquette : associez une étiquette existante à un contact et à la conversation ouverte de ce contact. Si l'étiquette n'existe pas encore, elle sera créée automatiquement lors de l'application.
Cela est utile pour classer automatiquement les conversations en fonction des règles de votre système — par exemple, marquer comme « Réclamation » lorsqu'un client envoie un mot-clé spécifique.
5. Attribuez des conversations à des agents
Avec l'endpoint d'attribution, vous pouvez désigner un agent pour toutes les conversations ouvertes d'un contact donné. Il suffit d'indiquer l'identifiant du contact et l'ID de l'utilisateur/agent. La liste des agents du compte peut être obtenue via l'endpoint de listage des utilisateurs, qui renvoie le nom, l'e-mail et l'ID de chaque membre de l'équipe.
Cette fonctionnalité est essentielle pour le routage automatique : un système de CRM peut, en identifiant le profil du prospect, l'attribuer au commercial approprié sans intervention manuelle.
Qui doit utiliser l'API de Conversations
- Opérations qui utilisent déjà des systèmes externes (ERP, CRM, plateformes de e-commerce) et souhaitent intégrer le service client de Papo sans dupliquer les efforts.
- Équipes de support avec des règles de routage complexes, qui doivent classer et diriger automatiquement les conversations en fonction des données client.
- Développeurs qui construisent des tableaux de bord personnalisés ou déclenchent des notifications à partir d'événements du service client.
- Revendeurs white label qui gèrent plusieurs comptes et souhaitent automatiser la configuration des étiquettes et des attributions pour chaque client.
Questions fréquentes
Ai-je besoin d'un token d'API pour utiliser ces endpoints ?
Oui. Toutes les requêtes à l'API de Papo nécessitent une authentification via une clé secrète, envoyée dans l'en-tête Authorization: Bearer sk_live_…. Les tokens sont générés dans le panneau du compte.
L'API permet-elle d'envoyer des messages en dehors de la fenêtre de 24 heures de WhatsApp ?
L'envoi de messages texte via l'API respecte la fenêtre de 24 heures. Pour les communications proactives en dehors de cette période, il est nécessaire d'utiliser des modèles de message (HSM) approuvés. Papo propose des endpoints spécifiques pour l'envoi de HSM.
Puis-je lister les conversations par étiquette ?
Oui. L'endpoint de listage des conversations accepte un filtre par étiquette, vous permettant de récupérer uniquement les conversations marquées avec une ou plusieurs étiquettes spécifiques.
Comment appliquer une étiquette à un contact via l'API ?
Utilisez l'endpoint des étiquettes, en indiquant l'identifiant de l'étiquette (ou les données pour la création) et l'identifiant du contact. L'étiquette sera appliquée au contact et à la conversation ouverte correspondante.
L'API renvoie-t-elle l'historique complet de la conversation ?
Le listage des conversations renvoie les métadonnées et les derniers messages. Pour obtenir l'historique complet des messages d'une conversation spécifique, consultez la documentation de l'API, qui détaille les endpoints de récupération des messages.
Est-il possible d'attribuer une conversation à un agent sans connaître l'ID de l'utilisateur ?
Vous pouvez d'abord lister les utilisateurs du compte (endpoint des agents) pour obtenir les ID, puis utiliser l'endpoint d'attribution. La liste des agents inclut le nom et l'e-mail, ce qui facilite l'identification.
Lire aussi
- Comment utiliser l'API de Papo pour gérer les clients de votre revendeur white label
- Comment utiliser l'API de Papo pour gérer les attributs personnalisés des contacts
Testez l'API et tous les modules de Papo sans frais — le premier utilisateur est gratuit et ne nécessite pas de carte de crédit.