Centre d’aide / API PALMS et clés API

API PALMS et clés API

Créez une clé API, choisissez ses permissions, et lisez ou modifiez contacts, conversations et messages depuis votre logiciel.

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é

  1. Ouvrez Intégrations → API PALMS et cliquez sur Créer une clé API.
  2. Nommez la clé selon son usage, par exemple Formulaire du site ou Zapier.
  3. 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.
  4. Choisissez ses permissions : uniquement ce dont l’outil a besoin (voir permissions).
  5. 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/me

Vous 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

PermissionPermet à 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êteCe qu’elle fait
GET /meLa clé, son organisation et son espace de travail.
GET /contactsLes contacts, les plus récents d’abord. Filtres : q, phone, email, tag, updatedSince.
POST /contactsCré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/upsertCré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 /conversationsLes 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}/messagesLes messages, les plus récents d’abord.
POST /conversations/{id}/messagesUne réponse texte, ou une note interne ("type": "note").
POST /messages/templateEnvoyer un modèle WhatsApp approuvé à un contact.
GET /templates, /channels, /members, /teams, /tagsListes 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épond 409 avec 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 voir sent, delivered, read ou failed.
  • Ajoutez un clientId (un UUID que vous générez) pour qu’un envoi puisse être réessayé sans risque : le même clientId n’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.

HTTPCodeSignificationQue faire
401UNAUTHENTICATEDPas 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é.
403FORBIDDENLa clé n’a pas la permission requise.Créez une clé avec cette permission.
404NOT_FOUNDRien 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.
409CONFLICTLa 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.
422VALIDATION_FAILEDUne valeur manque ou est invalide.fields indique lesquelles.
429RATE_LIMITEDTrop 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é>.

Toujours bloqué ?

Notre équipe répond sur WhatsApp, en français ou en anglais.

WhatsAppOuvrir Graphwafe