Référence API

L'API REST WallaWhats vous permet de gérer vos téléphones, abonnements à des comptes X et historique de notifications de manière programmatique — exactement ce que vous feriez autrement depuis le tableau de bord.

URL de base : https://api.wallawhats.com
Type de contenu : application/json
Authentification : clé API (en-tête)
Versionnage : l'API est stable. Les changements cassants sont annoncés 30 jours à l'avance par e-mail à chaque compte.

Authentification

Chaque requête doit inclure une clé API dans l'en-tête x-api-key :

bash

curl https://api.wallawhats.com/user/profile \
  -H "x-api-key: bws_prod_00000000000000000000000000000000"

Les clés se créent dans le tableau de bord via Settings → API Keys ou via POST /apikeys. Un préfixe de clé commence par bws_ et fait 36 caractères. Les clés ne sont affichées qu'une seule fois, à la création — si vous perdez une clé, supprimez-la et créez-en une nouvelle.

Portée et expiration

Une clé authentifie l'utilisateur qui l'a créée. Elle a les mêmes permissions que cet utilisateur et est décomptée des mêmes quotas de plan.
Les clés sont valides 365 jours. Pour faire une rotation : créez une nouvelle clé, basculez dessus, puis supprimez l'ancienne.
Les clés manquantes, malformées ou révoquées renvoient 401 Unauthorized.

Limites de clés par plan

Plan	Clés autorisées
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Toute tentative d'en créer plus que ce que permet votre plan renvoie 400 avec "error": "api key limit reached".

Erreurs

Les erreurs sont renvoyées au format JSON avec un champ error et un code de statut HTTP :

json

{ "error": "phoneNumber is required" }

Statut	Signification
`400`	Paramètres invalides, quota dépassé ou violation d'une règle métier
`401`	Clé API manquante ou invalide
`402`	Crédits insuffisants pour réaliser l'opération
`404`	Ressource introuvable
`500`	Erreur serveur — réessayez avec un backoff exponentiel

Limites de débit

Par défaut : 20 requêtes/seconde par clé API, avec un burst à 40.
Les endpoints de listing renvoient jusqu'à 50 éléments par page ; utilisez le curseur lastKey pour paginer.
Les règles WAF peuvent renvoyer 403 sur des motifs abusifs. Contactez le support si vous êtes limité de façon inattendue.

Utilisateur

Obtenir votre profil

GET /user/profile

Renvoie le profil de l'utilisateur authentifié.

Réponse

json

{
  "userId": "5a4cbd70-...",
  "email": "jane@example.com",
  "name": "Jane",
  "plan": "pro_plus",
  "createdAt": 1745000000000
}

Exemple

bash

curl https://api.wallawhats.com/user/profile \
  -H "x-api-key: bws_prod_..."

Téléphones

Un téléphone est un numéro WhatsApp vérifié qui peut recevoir des alertes. Vous devez vérifier un téléphone avant d'y abonner un compte X.

Enregistrer un téléphone

POST /phones

Génère un code à 6 chiffres et l'envoie au numéro via WhatsApp. Le téléphone est créé en état pending_verification.

Requête

Champ	Type	Requis	Notes
`phoneNumber`	string	oui	Format E.164, par ex. `+34612345678`
`displayName`	string	non	Libellé convivial affiché dans le tableau de bord

Réponse

json

{ "phoneNumber": "+34612345678", "status": "pending_verification" }

Erreurs

400 "invalid phone number format" — pas au format E.164
400 "phone number limit reached" — dépasse la limite du plan (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Exemple

bash

curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: bws_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+34612345678", "displayName": "Work"}'

Vérifier un téléphone

POST /phones/verify

Confirme un téléphone en soumettant le code à 6 chiffres. Les codes expirent après 15 minutes.

Requête

Champ	Type	Requis
`phoneNumber`	string (E.164)	oui
`code`	string (6 chiffres)	oui

Réponse

json

{ "phoneNumber": "+34612345678", "status": "verified" }

Erreurs

404 "phone not found"
400 "invalid code" — code incorrect
400 "code expired" — plus de 15 minutes
400 "phone already verified"

Lister vos téléphones

GET /phones

Réponse

json

{
  "phones": [
    {
      "phoneNumber": "+34612345678",
      "status": "verified",
      "displayName": "Work",
      "createdAt": 1745000000000,
      "verifiedAt": 1745000060000
    }
  ],
  "count": 1
}

Supprimer un téléphone

DELETE /phones/{phoneNumber}

Supprime le téléphone et désactive tous les abonnements qui le ciblaient. Encodez le + en %2B dans l'URL.

Réponse

json

{ "success": true }

Exemple

bash

curl -X DELETE "https://api.wallawhats.com/phones/%2B34612345678" \
  -H "x-api-key: bws_prod_..."

Abonnements

Un abonnement relie un compte X que vous souhaitez surveiller à l'un de vos téléphones vérifiés. Lorsque le compte X publie, WallaWhats envoie une alerte WhatsApp à ce téléphone.

Créer un abonnement

POST /subscriptions

Requête

Champ	Type	Requis	Notes
`xUsername`	string	oui	1–15 caractères, alphanumériques + underscore. Le préfixe `@` est accepté et retiré.
`phoneNumber`	string (E.164)	oui	Doit être l'un de vos téléphones vérifiés.

Réponse

json

{
  "xUsername": "elonmusk",
  "xUserId": "44196397",
  "xDisplayName": "Elon Musk",
  "xProfileImage": "https://pbs.twimg.com/...",
  "phoneNumber": "+34612345678",
  "isActive": true,
  "createdAt": 1745000000000
}

Erreurs

400 "invalid X username format" — échec de l'expression régulière
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — voir le tableau des plans ci-dessous
404 "X account not found" — le nom d'utilisateur ne se résout pas sur X

Limites par plan

Plan	Abonnements
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Lister vos abonnements

GET /subscriptions

Réponse

json

{
  "subscriptions": [ /* même forme que la réponse POST /subscriptions */ ],
  "count": 3
}

Supprimer un abonnement

DELETE /subscriptions/{xUsername}

Correspondance insensible à la casse sur xUsername. Retirez le @ avant l'envoi.

Réponse

json

{ "success": true }

Notifications

Chaque alerte livrée par WallaWhats est enregistrée ici, avec son statut de livraison WhatsApp.

Lister les notifications

GET /notifications

Paramètres de requête

Paramètre	Type	Description
`from`	number (epoch ms)	Filtre sur les notifications créées à partir de cette date
`to`	number (epoch ms)	Filtre sur les notifications créées jusqu'à cette date
`lastKey`	string	Curseur de pagination renvoyé par la réponse précédente

Réponse

json

{
  "notifications": [
    {
      "notificationId": "a1b2c3d4-...",
      "userId": "5a4cbd70-...",
      "phoneNumber": "+34612345678",
      "xUsername": "elonmusk",
      "tweetId": "1797123456789000000",
      "tweetText": "...",
      "tweetUrl": "https://x.com/elonmusk/status/...",
      "waMessageId": "wamid.HBgN...",
      "status": "delivered",
      "errorMessage": null,
      "createdAt": 1745000000000,
      "updatedAt": 1745000002000
    }
  ],
  "lastKey": "eyJOT1RJRklDQVRJT05fSUQi..."
}

Valeurs possibles pour status : queued, sent, delivered, read, failed.

La taille de page est de 50. Lorsque lastKey est absent, vous avez atteint la fin.

Clés API

Gérez les clés que vos applications utilisent pour appeler cette API.

Créer une clé API

POST /apikeys

Requête

Champ	Type	Requis
`name`	string	non, vaut `"Default"` par défaut

Réponse (201 Created)

json

{
  "apiKey": "bws_prod_00000000000000000000000000000000",
  "keyPrefix": "bws_prod_00",
  "keyName": "CI server",
  "createdAt": 1745000000000,
  "expiresAt": 1776536000000
}

Valeur affichée une seule fois

apiKey n'est renvoyée qu'à la création. Stockez-la immédiatement dans votre gestionnaire de secrets. Les appels suivants n'exposent que le keyPrefix.

Lister vos clés API

GET /apikeys

Réponse

json

[
  {
    "keyPrefix": "bws_prod_00",
    "keyName": "CI server",
    "createdAt": 1745000000000,
    "lastUsedAt": 1745086400000,
    "expiresAt": 1776536000000
  }
]

Supprimer une clé API

DELETE /apikeys/{keyPrefix}

Utilisez le keyPrefix à 12 caractères issu de la réponse de listing — jamais la clé complète.

Réponse

json

{ "success": true }

Démarrage rapide

bash

# 1. Créez une clé dans le tableau de bord et exportez-la
export WALLA_API_KEY="bws_prod_..."

# 2. Enregistrez + vérifiez votre numéro WhatsApp
curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+34612345678","displayName":"Mobile"}'
# -> le téléphone reçoit un code WhatsApp. Soumettez-le :
curl -X POST https://api.wallawhats.com/phones/verify \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+34612345678","code":"123456"}'

# 3. Abonnez-vous à un compte X
curl -X POST https://api.wallawhats.com/subscriptions \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"xUsername":"elonmusk","phoneNumber":"+34612345678"}'

# 4. Regardez arriver les alertes
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

C'est tout — dès que le compte X publie, l'alerte arrive sur le téléphone en environ 10 secondes.

Support

Questions sur l'API, rapports de bugs ou demandes d'augmentation de quota : ouvrez un ticket depuis l'onglet Support de votre tableau de bord, ou écrivez à hello@support.wallawhats.com.

Référence API ​

Authentification ​

Portée et expiration ​

Limites de clés par plan ​

Erreurs ​

Limites de débit ​

Utilisateur ​

Obtenir votre profil ​

Téléphones ​

Enregistrer un téléphone ​

Vérifier un téléphone ​

Lister vos téléphones ​

Supprimer un téléphone ​

Abonnements ​

Créer un abonnement ​

Lister vos abonnements ​

Supprimer un abonnement ​

Notifications ​

Lister les notifications ​

Clés API ​

Créer une clé API ​

Lister vos clés API ​

Supprimer une clé API ​

Démarrage rapide ​

Support ​

Référence API

Authentification

Portée et expiration

Limites de clés par plan

Erreurs

Limites de débit

Utilisateur

Obtenir votre profil

Téléphones

Enregistrer un téléphone

Vérifier un téléphone

Lister vos téléphones

Supprimer un téléphone

Abonnements

Créer un abonnement

Lister vos abonnements

Supprimer un abonnement

Notifications

Lister les notifications

Clés API

Créer une clé API

Lister vos clés API

Supprimer une clé API

Démarrage rapide

Support