L’API PALMS permet à votre site web, votre CRM, votre système scolaire ou un outil comme Zapier, Make ou n8n de travailler avec PALMS : créer et modifier des contacts, lire les conversations, les attribuer et les fermer, et envoyer des messages et des modèles WhatsApp. Votre logiciel prouve son identité avec une clé API.
Avant de commencer
- Vous êtes Propriétaire ou Administrateur de l’organisation.
- Vous savez pour quel espace de travail est l’intégration : une clé agit sur l’espace de travail ouvert au moment de sa création.
- La personne qui construit l’intégration (vous, un développeur ou une agence) peut garder un secret sur un serveur. Ne mettez jamais une clé dans une page web ou une application mobile téléchargeable : n’importe qui pourrait la lire.
Créer une clé
- Ouvrez Intégrations → API PALMS et cliquez sur Créer une clé API.
- Nommez la clé selon son usage, par exemple Formulaire du site ou Zapier.
- Choisissez quand elle expire : dans 30 jours, 90 jours, 1 an, ou jamais. Plus court est plus sûr ; vous pouvez créer une nouvelle clé à tout moment.
- Choisissez ses permissions : uniquement ce dont l’outil a besoin (voir permissions).
- Cliquez sur Créer la clé. PALMS affiche la clé une seule fois : copiez-la et gardez-la en lieu sûr (gestionnaire de mots de passe ou paramètres de votre serveur).
Tester votre clé
Exécutez ceci dans un terminal (remplacez la clé) :
curl -H "Authorization: Bearer palms_xxxxxxxxxx_…" https://<api-address>/v1/api/meVous devez voir le nom de la clé, ses permissions, votre organisation et votre espace de travail. En cas d’erreur, consultez le tableau des erreurs.
Permissions
| Permission | Permet à la clé de |
|---|---|
Lire les contacts (contacts:read) | Lister, rechercher et lire les contacts, leurs étiquettes et champs personnalisés ; lister les étiquettes. |
Modifier les contacts (contacts:write) | Créer, modifier et supprimer des contacts ; ajouter et retirer des étiquettes. |
Lire les conversations (conversations:read) | Lister et lire les conversations. |
Gérer les conversations (conversations:write) | Attribuer, fermer et rouvrir les conversations. |
Lire les messages (messages:read) | Lire les messages d’une conversation. |
Envoyer des messages (messages:write) | Envoyer des réponses, des notes internes et des modèles WhatsApp. |
Lire les modèles (templates:read) | Lister vos modèles WhatsApp. |
Lire les canaux (channels:read) | Lister vos canaux connectés. |
Lire l’équipe (team:read) | Lister les membres et les équipes (pour attribuer des conversations). |
Une permission de modification permet aussi la lecture.
Ce que vous pouvez faire
Toutes les adresses commencent par https://<api-address>/v1/api. Remplacez <api-address> par l'adresse affichée à l'étape Test de la clé dans PALMS. Envoyez et recevez du JSON. La référence complète (pour Postman ou les générateurs de code) est sur /v1/api/openapi.json.
| Requête | Ce qu’elle fait |
|---|---|
GET /me | La clé, son organisation et son espace de travail. |
GET /contacts | Les contacts, les plus récents d’abord. Filtres : q, phone, email, tag, updatedSince. |
POST /contacts | Créer un contact. Si le téléphone ou l’e-mail existe déjà, vous recevez un 409 avec le contactId existant. |
POST /contacts/upsert | Créer ou mettre à jour, en cherchant d’abord le téléphone, puis l’e-mail. Idéal pour les formulaires et synchronisations. |
GET / PATCH / DELETE /contacts/{id} | Lire, modifier ou supprimer un contact. |
POST /contacts/{id}/tags · DELETE /contacts/{id}/tags/{name} | Ajouter ou retirer une étiquette. |
GET /conversations | Les conversations, activité la plus récente d’abord. Filtres : status, contactId, assigneeId. |
GET / PATCH /conversations/{id} | Lire ; fermer, rouvrir, attribuer ou désattribuer. |
GET /conversations/{id}/messages | Les messages, les plus récents d’abord. |
POST /conversations/{id}/messages | Une réponse texte, ou une note interne ("type": "note"). |
POST /messages/template | Envoyer un modèle WhatsApp approuvé à un contact. |
GET /templates, /channels, /members, /teams, /tags | Listes de référence. |
Créer ou mettre à jour un contact depuis un formulaire :
curl -X POST https://<api-address>/v1/api/contacts/upsert \
-H "Authorization: Bearer $PALMS_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"Ama Mensah","phone":"+233241234567","tags":["Website"],"customFields":{"programme":"Nursing"}}'Envoyer un modèle WhatsApp :
curl -X POST https://<api-address>/v1/api/messages/template \
-H "Authorization: Bearer $PALMS_API_KEY" -H "Content-Type: application/json" \
-d '{"contactId":"…","templateId":"…","values":["Ama","15 juin"]}'Les listes renvoient { "data": [...], "nextCursor": "…" }. Pour la page suivante, envoyez cursor=<nextCursor> ; nextCursor vaut null sur la dernière page. limit vaut 25 par défaut, 100 au maximum.
Les numéros de téléphone sont au format international (+233241234567). Sans indicatif, c’est le pays de votre organisation qui s’applique.
Les champs personnalisés utilisent la clé du champ (voir Paramètres → Contacts → Champs personnalisés). Envoyez null pour en vider un.
Envoyer des messages : les règles
- Fenêtre de 24 heures de WhatsApp : un texte libre n’est possible que dans les 24 heures suivant le dernier message du client. Ensuite, envoyez un modèle approuvé (
POST /messages/template). L’API répond409avec une explication si la fenêtre est fermée. - Les messages sont mis en file et envoyés en arrière-plan : la réponse contient
"status": "queued"; relisez le message plus tard pour voirsent,delivered,readoufailed. - Ajoutez un
clientId(un UUID que vous générez) pour qu’un envoi puisse être réessayé sans risque : le mêmeclientIdn’envoie jamais deux fois. - Les contacts désinscrits ne reçoivent jamais de modèles.
- Les messages envoyés par l’API apparaissent dans la boîte de réception sous API · <nom de la clé>.
Limites
Chaque clé peut faire 120 requêtes par minute. Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes avant la remise à zéro). Au-delà, vous recevez 429 avec un en-tête Retry-After : attendez ce nombre de secondes et réessayez. Une organisation peut avoir jusqu’à 25 clés actives.
Erreurs
Les erreurs ont la forme { "error": { "code": "…", "message": "…", "referenceId": "…", "fields": {…} } }. Le message explique quoi faire. Donnez-nous le referenceId si vous contactez le support.
| HTTP | Code | Signification | Que faire |
|---|---|---|---|
| 401 | UNAUTHENTICATED | Pas de clé, mauvaise clé, ou clé révoquée ou expirée. | Envoyez Authorization: Bearer <clé>. Vérifiez que vous l’avez copiée en entier. Créez une nouvelle clé si elle a été révoquée ou a expiré. |
| 403 | FORBIDDEN | La clé n’a pas la permission requise. | Créez une clé avec cette permission. |
| 404 | NOT_FOUND | Rien avec cet identifiant dans l’espace de travail de la clé. | Vérifiez l’identifiant et que la clé est pour le bon espace de travail. |
| 409 | CONFLICT | La requête contredit l’état actuel (contact existant, conversation fermée, fenêtre de 24 h fermée). | Lisez le message : il indique quoi faire. |
| 422 | VALIDATION_FAILED | Une valeur manque ou est invalide. | fields indique lesquelles. |
| 429 | RATE_LIMITED | Trop de requêtes cette minute. | Attendez Retry-After secondes. |
Protéger vos clés
- Une clé par outil, avec seulement les permissions nécessaires, et une date d’expiration.
- Gardez les clés sur un serveur, jamais dans une page web, une application mobile ou un document partagé.
- Révoquez une clé dès que vous ne l’utilisez plus, ou si elle a pu fuiter : ouvrez Intégrations → API PALMS et cliquez sur Révoquer. Elle cesse de fonctionner immédiatement.
- La liste des clés montre la dernière utilisation de chaque clé et son nombre de requêtes sur 24 heures, pour repérer les clés inutilisées.
- Tout ce qu’une clé modifie figure dans le journal d’audit (Paramètres → Journal d’audit) sous API · <nom de la clé>.