API publique · v1

Référence développeur

Envoyez des messages WhatsApp et gérez vos contacts par API REST. Facturation à la consommation, sans abonnement — pensée pour les intégrations et le gros volume.

BASEhttps://api.whakup.com/v1

Introduction

L'API Whakup est une API REST : requêtes et réponses en JSON, dates au format ISO 8601. Toutes les données sont scopées au workspace de la clé utilisée.

Base : https://api.whakup.com/v1
En-tête Content-Type: application/json pour les requêtes avec corps.
Facturation à la consommation, agrégée par mois.

Authentification

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

Création

Tableau de bord → Réglages → Clés API (offre Business).

Affichée une fois

La clé en clair n’apparaît qu’à la création — conservez-la.

Révocable

Révocation immédiate depuis le tableau de bord.

Sécurité

Seul le hash SHA-256 est stocké côté serveur.

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

Limites & quotas

Limite	Portée	Valeur	Dépassement
Débit API	par clé	1 200 / min	rate_limited
Débit d’envoi	par numéro	80 / seconde	throughput_exceeded
Quota marketing	par numéro / jour	limite Meta	marketing_quota_reached
Quota mensuel	par offre	inclus dans l’offre	quota_reached

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).

Erreurs

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

HTTP	code	Signification
400	—	Requête invalide (champ requis manquant).
401	—	Clé API invalide ou manquante.
402	feature_locked	Accès API non inclus dans l’offre.
402	quota_reached	Quota mensuel de messages atteint.
429	rate_limited	Trop de requêtes pour cette clé.
429	throughput_exceeded	Débit maximal du numéro atteint.
429	marketing_quota_reached	Quota marketing quotidien atteint.
502	—	Échec côté fournisseur (non envoyé).

Vérifier la clé

GET/ping

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"

Réponse 200

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

Lister les contacts

GET/contacts

Champ	Type	Requis	Notes
limit	entier	—	défaut 50, max 100
offset	entier	—	pagination (défaut 0)

curl "https://api.whakup.com/v1/contacts?limit=20&offset=0" \
  -H "Authorization: Bearer wk_votre_cle"

Réponse 200

{
  "data": [
    {
      "id": "018f…",
      "displayName": "Jean Dupont",
      "phone": "+2250700000000",
      "email": "jean.dupont@example.com",
      "createdAt": "2026-09-09T14:30:00+00:00"
    }
  ],
  "total": 5032
}

Créer un contact

POST/contacts

Champ	Type	Requis	Notes
displayName	string	✓	nom affiché
phone	string	—	format international (+225…)
email	string	—

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

Réponse 201

{
  "id": "018f…",
  "displayName": "Jean Dupont",
  "phone": "+2250700000000",
  "email": null,
  "createdAt": "2026-09-09T14:30:00+00:00"
}

Envoyer un message WhatsApp

POST/messages

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

Champ	Type	Requis	Notes
to	string	✓	numéro destinataire (international)
body	string	✓	contenu du message
category	string	—	marketing \| utility \| authentication \| service — défaut utility

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"
  }'

Réponse 201

{
  "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.

Lister les templates

GET/templates

Champ	Type	Requis	Notes
limit	entier	—	défaut 25, max 100
offset	entier	—	pagination (défaut 0)
status	string	—	draft \| pending \| approved \| rejected (filtre)

curl "https://api.whakup.com/v1/templates?status=approved" \
  -H "Authorization: Bearer wk_votre_cle"

Réponse 200

{
  "data": [
    {
      "id": "018f…",
      "name": "confirmation_commande",
      "language": "fr",
      "category": "utility",
      "status": "approved",
      "body": "Bonjour {{1}}, votre commande est confirmée.",
      "variables": ["1"]
    }
  ],
  "total": 12
}

Créer un template

POST/templates

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

Champ	Type	Requis	Notes
name	string	✓	minuscules, chiffres, underscores
language	string	✓	ex. fr, en_US
category	string	✓	marketing \| utility \| authentication
body	string	✓	≤ 1024 caractères, variables {{1}}
header	objet	—	{ type: text\|image\|video\|document, text?, mediaUrl? }
footer	string	—	≤ 60 caractères
buttons	tableau	—	quick_reply \| url \| phone_number
samples	objet	—	valeurs d’exemple des variables

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" }
  }'

Réponse 201

{
  "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.

Soumettre à Meta

POST/templates/{id}/submit

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).

Supprimer un template

DELETE/templates/{id}

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

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

Tarifs (à l'usage)

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

Catégorie	Whakup	Meta	Total
marketing	0,0088 €	0,0712 €	0,0800 €
utility	0,0088 €	0,0248 €	0,0336 €
authentication	0,0088 €	0,0248 €	0,0336 €
service	0,0088 €	0,0000 €	0,0088 €

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

Bonnes pratiques

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.

Prêt à intégrer ?

Créez une clé API depuis votre tableau de bord et envoyez votre premier message.

Ouvrir le tableau de bord