Commencer
Authentification et permissions
Clés API, les 20 scopes et ce que chacun débloque, rotation des clés, limites de débit par plan et isolation des espaces pour l'API WhatSetter.
Chaque requête à l’API et chaque session MCP est authentifiée par une clé API. Cette page explique ce qu’est une clé, ce qu’elle peut faire, et les limites qui s’y appliquent.
Les clés API
Section intitulée « Les clés API »- Format :
ws_live_suivi de 40 caractères hexadécimaux. - Une clé appartient à l’espace de travail, pas à une personne. Elle se crée dans Paramètres, puis API & MCP, par un propriétaire ou un admin.
- Elle est affichée une seule fois, juste après la création. WhatSetter ne conserve qu’une empreinte, personne ne peut la relire ensuite.
- Tu peux la révoquer à tout moment avec Révoquer, puis Révoquer pour de bon. Le dashboard confirme : Clé révoquée. Effectif en moins d’une minute. Révoquer coupe l’API REST et le serveur MCP en même temps.
Envoyer la clé
Section intitulée « Envoyer la clé »Passe la clé en Bearer token. L’en-tête X-Api-Key est accepté aussi.
curl https://app.whatsetter.com/api/v1/me \ -H "Authorization: Bearer ws_live_…"Sans clé tu reçois 401 missing_api_key. Avec une clé inconnue ou révoquée tu reçois 401 invalid_api_key.
Les scopes
Section intitulée « Les scopes »Quand tu crées une clé, tu choisis ses Permissions : Accès complet (tous les scopes, y compris l’envoi de messages et la modification des prompts) ou Personnalisé (tu choisis exactement ce que cette clé peut faire). Une clé sans le bon scope reçoit 403 insufficient_scope, et le message nomme le scope manquant.
| Scope | Ce qu’il débloque | Endpoints |
|---|---|---|
leads:read |
Lire les leads et leurs notes | GET /leads, GET /leads/{id}, GET /leads/{id}/notes |
leads:write |
Modifier le statut, les tags, le responsable, la prochaine action et l’issue du deal ; passer la main à un humain et la rendre à l’IA ; ajouter des notes | PATCH /leads/{id}, POST /leads/{id}/handoff, POST /leads/{id}/resume, POST /leads/{id}/notes |
conversations:read |
Boîte de réception et historique complet des messages | GET /conversations, GET /conversations/{leadId}/messages |
lists:read |
Lister tes listes de contacts | GET /lists |
lists:write |
Créer des listes et importer des contacts | POST /lists, POST /lists/{id}/leads |
campaigns:read |
Lister les campagnes | GET /campaigns |
campaigns:write |
Mettre en pause et relancer des campagnes | POST /campaigns/{id}/pause, POST /campaigns/{id}/resume |
messages:send |
Envoyer un message à un lead déjà en conversation, sur WhatsApp, Instagram ou Messenger ; ajouter un lead opt-in à une campagne (ce qui envoie son premier message) | POST /messages, POST /campaigns/{id}/leads |
bookings:read |
Les rendez-vous pris par l’agent | GET /bookings |
groups:read |
Les groupes WhatsApp suivis : détail, membres, messages, arrivées et départs | GET /groups, GET /groups/{id}, GET /groups/{id}/members, GET /groups/{id}/messages, GET /groups/{id}/events |
webhooks:manage |
Créer, lister, tester et supprimer des souscriptions webhook | GET /webhooks, POST /webhooks, DELETE /webhooks/{id}, POST /webhooks/{id}/test |
blocklist:manage |
Lire, ajouter et retirer des numéros et indicatifs bloqués | GET /blocked-contacts, POST /blocked-contacts, DELETE /blocked-contacts/{id} |
team:read |
Lister les membres de l’espace (id, nom, rôle), pour attribuer des leads | GET /team/members |
links:read |
Lire les liens traqués et leurs statistiques de clics | GET /links, GET /links/{id} |
prompts:read |
Lire les prompts qui font tourner un agent et leurs versions | GET /campaigns/{id}/prompts, GET /campaigns/{id}/prompts/{type}, GET /campaigns/{id}/prompts/{type}/versions, GET /campaigns/{id}/prompts/{type}/versions/{versionId} |
prompts:write |
Modifier un prompt ou restaurer une version. Le changement est en ligne tout de suite | PUT /campaigns/{id}/prompts/{type}, POST /campaigns/{id}/prompts/{type}/versions/{versionId}/restore |
knowledge:read |
Lire les bases de connaissances et leurs réponses, et y chercher comme le fait l’agent | GET /knowledge-bases, GET /knowledge-bases/{id}, GET /knowledge-bases/{id}/search, GET /knowledge-bases/{id}/answers |
knowledge:write |
Ajouter, corriger et retirer des réponses | POST /knowledge-bases/{id}/answers, PATCH /knowledge-bases/{id}/answers/{answerId}, DELETE /knowledge-bases/{id}/answers/{answerId} |
instagram:read |
Lire les comptes Instagram, les publications programmées, les chiffres et les meilleurs moments des publications, les automatisations et leurs chiffres | GET /instagram/accounts, GET /instagram/posts, GET /instagram/posts/{id}, GET /instagram/insights/posts, GET /instagram/insights/best-times, GET /instagram/automations, GET /instagram/stats |
instagram:write |
Programmer, modifier et annuler des publications (elles sont publiées publiquement) ; créer, modifier, allumer et supprimer des automatisations (une automatisation allumée écrit à de vraies personnes) | POST /instagram/posts, PATCH /instagram/posts/{id}, DELETE /instagram/posts/{id}, POST /instagram/automations, PATCH /instagram/automations/{id}, DELETE /instagram/automations/{id} |
GET /me ne demande aucun scope : toute clé valide peut l’appeler.
Le moindre privilège
Section intitulée « Le moindre privilège »- Une clé par intégration (CRM, Zapier, un script, un assistant IA). Révoquer l’une ne casse pas les autres, et le dashboard montre quand chacune a servi pour la dernière fois.
- Un tableau de bord ou un rapport n’a besoin que de scopes de lecture. Donne
messages:sendseulement à l’intégration qui envoie vraiment des messages. - Donne
prompts:writeseulement à une intégration ou à un assistant qui doit changer ce que disent tes agents. Avecprompts:readseul, il peut expliquer une réponse sans pouvoir rien modifier. - Les clés confiées à un assistant IA via le serveur MCP méritent le même soin : l’assistant ne peut faire que ce que la clé autorise.
Faire tourner une clé
Section intitulée « Faire tourner une clé »- Dans Paramètres, puis API & MCP, clique sur Créer une clé avec les mêmes scopes que l’ancienne.
- Mets la nouvelle clé dans ton intégration et vérifie-la avec
GET /me. - Clique sur Révoquer sur l’ancienne clé, puis Révoquer pour de bon. Elle cesse de fonctionner en moins d’une minute.
Fais la rotation tout de suite si tu soupçonnes une fuite : une clé collée dans un chat, un ticket ou un dépôt public.
Une clé pour l’API et le serveur MCP
Section intitulée « Une clé pour l’API et le serveur MCP »Le serveur MCP n’a pas de comptes à lui. Chaque appel d’outil est un appel à l’API REST avec ta clé, donc les scopes, les limites de débit et les règles anti-ban ci-dessous s’appliquent exactement de la même façon. Révoque la clé et l’assistant perd l’accès lui aussi.
Les limites de débit
Section intitulée « Les limites de débit »Les requêtes sont comptées par espace, par minute, toutes clés confondues. La limite dépend de ton plan :
| Plan | Requêtes par minute |
|---|---|
| Social | 30. Listes, groupes, liens et webhooks demandent un forfait WhatsApp : 403 not_in_plan |
| Free | 60 |
| Starter | 120 |
| Business | 300 |
| Scale | 1000 |
Chaque réponse porte trois en-têtes :
| En-tête | Sens |
|---|---|
X-RateLimit-Limit |
La limite de ton plan pour la fenêtre en cours. |
X-RateLimit-Remaining |
Les requêtes restantes dans la fenêtre. |
X-RateLimit-Reset |
Quand la fenêtre se remet à zéro, en ISO 8601. |
Au-delà de la limite tu reçois 429 rate_limited avec un en-tête Retry-After en secondes. Attends ce délai, puis réessaie.
Les envois de messages ont un quota quotidien séparé par numéro WhatsApp, indiqué dans les en-têtes X-Quota-*. Voir Erreurs, limites et idempotence.
L’isolation des espaces
Section intitulée « L’isolation des espaces »Une clé ne voit que l’espace auquel elle appartient. Si tu demandes un identifiant qui existe mais appartient à un autre espace, l’API répond 404 not_found, comme pour un identifiant inexistant. Elle ne répond jamais 403, donc un identifiant étranger ne se distingue pas d’un identifiant inconnu.