Référence développeur

Chaque requête porte une clé d'API du workspace (préfixe wk_), au choix dans l'un des deux en-têtes :

# Recommandé
Authorization: Bearer wk_votre_cle

# Alternative
X-Api-Key: wk_votre_cle

Requête sans clé valide → 401 Unauthorized. Ne jamais exposer une clé côté navigateur.

Le débit d'envoi (80/s) est partagé avec l'envoi de campagnes depuis l'app. Les réponses429 incluent un en-tête Retry-After (secondes) : respectez-le (back-off).

Forme : { "error": "message", "code": "machine_code" }

Renvoie le workspace associé à la clé. Idéal pour tester l'authentification.

curl https://api.whakup.com/v1/ping \
  -H "Authorization: Bearer wk_votre_cle"

{ "workspace": { "id": "018f…", "name": "Ma Boutique" } }

Crée le contact, ou met à jourcelui qui a déjà ce numéro (quel que soit son format) : un même appel peut être rejoué sans créer de doublon — idéal pour n8n, Zapier ou un formulaire de votre site. Les groupes indiqués sont créés s'ils n'existent pas.

Au moins un des champs firstName, displayName ou phone est requis.

curl -X POST https://api.whakup.com/v1/contacts \
  -H "Authorization: Bearer wk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jean",
    "lastName": "Dupont",
    "phone": "+2250700000000",
    "groups": ["Prospects"]
  }'

{
  "id": "018f…",
  "displayName": "Jean Dupont",
  "phone": "+2250700000000",
  "email": null,
  "createdAt": "2026-09-09T14:30:00+00:00",
  "groups": [{ "id": "018f…", "name": "Prospects" }],
  "created": true
}

L'ajout à un groupe déclenche les automatisations « Ajout à un groupe » actives de ce groupe (ex. message de bienvenue).

Groupes de contacts du workspace, triés par nom, avec leur nombre de membres.

curl https://api.whakup.com/v1/groups \
  -H "Authorization: Bearer wk_votre_cle"

{
  "data": [
    { "id": "018f…", "name": "Prospects", "memberCount": 248 }
  ]
}

Ajoute des contacts existants à un groupe désigné par son identifiant ou son nom(encodé dans l'URL) ; le groupe est créé s'il n'existe pas. Un contact déjà membre est ignoré.

curl -X POST "https://api.whakup.com/v1/groups/Prospects/contacts" \
  -H "Authorization: Bearer wk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["018f…", "018f…"] }'

{
  "group": { "id": "018f…", "name": "Clients VIP", "memberCount": 250 },
  "added": 2
}

Déclenche les automatisations « Ajout à un groupe » pour les nouveaux membres.contactIds vide ou plus de 1 000 → 400.

Envoi immédiat sur le canal WhatsApp du workspace. Facturé au message (voir Tarifs).

La catégoriedoit refléter la nature réelle du message (règles Meta) : elle détermine les frais Meta et l'application du quota marketing.

curl -X POST https://api.whakup.com/v1/messages \
  -H "Authorization: Bearer wk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2250700000000",
    "body": "Votre commande est prête !",
    "category": "utility"
  }'

{
  "id": "wamid.HBg…",
  "status": "sent",
  "to": "+2250700000000",
  "category": "utility",
  "cost": { "whakup": 0.0088, "meta": 0.0248, "total": 0.0336 }
}

Prérequis : un canal WhatsApp configuré (sinon 400). Voir la table des erreurs pour 402 / 429 / 502.

Crée un template (reste en draft jusqu'à soumission à Meta).

curl -X POST https://api.whakup.com/v1/templates \
  -H "Authorization: Bearer wk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "confirmation_commande",
    "language": "fr",
    "category": "utility",
    "body": "Bonjour {{1}}, votre commande est confirmée.",
    "samples": { "1": "Jean" }
  }'

{
  "id": "018f…",
  "name": "confirmation_commande",
  "language": "fr",
  "category": "utility",
  "status": "draft",
  "variables": ["1"]
}

Nécessite l'accès API (402 feature_locked sinon). Nom déjà pris dans la langue → 409.

Envoie le template en revue Meta (→ pending). Un canal WhatsApp connecté est requis.

curl -X POST https://api.whakup.com/v1/templates/018f…/submit \
  -H "Authorization: Bearer wk_votre_cle"

Erreurs : 409 no_channel_connected (aucun canal),422 (non conforme aux règles Meta),502 (refus Meta).

curl -X DELETE https://api.whakup.com/v1/templates/018f… \
  -H "Authorization: Bearer wk_votre_cle"

Réponse 204 (aucun contenu). Introuvable → 404.

Connectez Claude, Cursor ou tout assistant compatible MCP(Model Context Protocol) à votre compte, avec la même clé API. L'assistant consulte vos contacts, groupes, campagnes et statistiques, templates, conversations et automatisations, et prépare le travail (contacts, groupes, brouillons de templates et de campagnes). Il n'envoie jamais de message : vous lancez les campagnes depuis Whakup.

claude mcp add --transport http whakup https://api.whakup.com/v1/mcp \
  --header "Authorization: Bearer wk_votre_cle"

{
  "mcpServers": {
    "whakup": {
      "url": "https://api.whakup.com/v1/mcp",
      "headers": { "Authorization": "Bearer wk_votre_cle" }
    }
  }
}

{
  "mcpServers": {
    "whakup": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.whakup.com/v1/mcp", "--header", "Authorization:${WHAKUP_AUTH}"],
      "env": { "WHAKUP_AUTH": "Bearer wk_votre_cle" }
    }
  }
}

Configuration aussi disponible, prête à copier avec votre clé, dans le tableau de bord (Réglages → Clés API → Assistant IA). Transport « Streamable HTTP », mêmes limites de débit que l'API, réservé aux offres incluant l'accès API (Business). Bientôt : connexion directe depuis claude.ai et ChatGPT.

Coût par message = frais Whakup fixes + frais Meta selon la catégorie (€, indicatifs).

Consommation du mois en cours visible dans le tableau de bord (facturation).

• Stockez la clé côté serveur (variable d'environnement) ; jamais dans le navigateur.
• Gérez les 429 avec l'en-tête Retry-After (back-off exponentiel).
• Renseignez la bonne category — impact tarifaire et conformité Meta.
• Pour de gros volumes, lissez les envois sous 80 msg/s par numéro.