API & Envoi de messages

Votre clé API

wap_VOTRE_CLE_API

Créez un compte et activez un plan pour obtenir votre clé API personnelle. Envoyez-la ensuite dans l'en-tête X-API-Key (ou Authorization: Bearer <clé>). Créer un compte · Se connecter

Connexion automatique (bouton « Connecter WhatsApp »)

Pour une plateforme externe (chatbot, no-code, etc.) qui doit obtenir automatiquement un session_id et une api_key sans que le client ait besoin de les copier à la main : ouvrez ce lien dans une popup depuis votre bouton « Connecter WhatsApp ». Le client s'authentifie (ou crée son compte) sur https://thebigsender.com, choisit son numéro, puis est renvoyé automatiquement vers votre redirect_uri avec les informations nécessaires.

URL à ouvrir en popup depuis votre application

https://thebigsender.com/connect?redirect_uri=<VOTRE_URL_DE_RETOUR>&webhook=<VOTRE_URL_DE_WEBHOOK>&state=<VALEUR_LIBRE>&app=<NOM_DE_VOTRE_APP>

Ce que vous recevez sur redirect_uri une fois autorisé

GET <redirect_uri>?session_id=9&api_key=wap_xxxxxxxxxxxxxxxx&state=<VALEUR_LIBRE>

Utilisez ensuite ce session_id et cette api_key pour envoyer des messages via l'API décrite ci-dessous (voir « Envoyer un message texte »). Si le client refuse ou ferme la popup, il n'est jamais redirigé — prévoyez simplement un délai d'attente côté votre application.

Envoyer un message texte

Exemple cURL

curl -X POST https://thebigsender.com/api/v1/messages/send \
  -H "X-API-Key: VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": 1,
    "to": "33612345678",
    "message": "Bonjour depuis WhatsApp Platform !"
  }'

Réponse (succès)

{
  "success": true,
  "result": {
    "Details": "Sent",
    "Id": "3EB0...C5",
    "Timestamp": "2026-01-01T12:00:00+01:00"
  }
}

Envoyer une image, un document ou un audio

Même endpoint que le texte : https://thebigsender.com/api/v1/messages/send, en changeant le champ type. Le média peut être fourni de deux façons :

Exemple — Image (avec légende)

curl -X POST https://thebigsender.com/api/v1/messages/send \
  -H "X-API-Key: VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": 1,
    "type": "image",
    "to": "33612345678",
    "media_url": "https://exemple.com/photo.jpg",
    "caption": "Regardez ça !"
  }'

Exemple — Document (PDF, Word, etc.)

curl -X POST https://thebigsender.com/api/v1/messages/send \
  -H "X-API-Key: VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": 1,
    "type": "document",
    "to": "33612345678",
    "media_url": "https://exemple.com/facture.pdf",
    "filename": "facture.pdf"
  }'

Exemple — Audio (message vocal)

curl -X POST https://thebigsender.com/api/v1/messages/send \
  -H "X-API-Key: VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": 1,
    "type": "audio",
    "to": "33612345678",
    "media_url": "https://exemple.com/note.ogg"
  }'

L'audio doit être au format Opus (.ogg) pour apparaître comme un message vocal WhatsApp natif. Les autres formats audio sont généralement reçus comme un fichier audio classique.

Cadence d'envoi (protection anti-bannissement)

Le volume de messages est illimité sur tous les plans. En revanche la cadence est régulée par numéro : un numéro qui envoie plusieurs messages dans la même seconde est le premier motif de blocage côté WhatsApp. Le rythme imposé est celui d'un usage humain.

Chaque session a son propre compteur : plusieurs numéros envoient donc en parallèle sans se gêner. Au-delà de la cadence, l'API répond 429 avec l'en-tête Retry-After et un champ retry_after (secondes) : il suffit de rejouer la requête après ce délai.

Réponse en cas de dépassement

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "success": false,
  "error": "Rate limit anti-bannissement : 1200 ms minimum entre deux messages sur une même session.",
  "retry_after": 1
}

Vos sessions (session_id)

Après connexion, vos sessions (numéros connectés) et leurs session_id s'affichent ici, et sur le tableau de bord.

Recevoir les messages (webhook entrant)

Définissez votre URL de webhook dans Paramètres. Chaque message reçu par vos numéros y sera relayé en POST (JSON) par notre relais — texte, image, document et audio compris.

Exemple de payload relayé vers votre webhook (message texte)

POST <votre_webhook>
Content-Type: application/json
X-WA-Platform-Session: 1

{
  "session_id": 1,
  "session_label": "Support",
  "type": "Message",
  "from": "212612345678",
  "message": "Bonjour, j'ai une question",
  "message_type": "text",
  "push_name": "Nom WhatsApp de l'expéditeur",
  "event": { ... payload brut du moteur WhatsApp (horodatage, IDs, métadonnées) ... }
}

Les champs from, message, message_type et push_name sont fournis en plus du payload brut event, pour une intégration simple avec des plateformes no-code / chatbot génériques qui n'ont pas besoin de la structure native du moteur WhatsApp.

Exemple — image reçue

{
  "session_id": 1,
  "type": "Message",
  "event": {
    "info": { "Sender": "33612345678@s.whatsapp.net", ... },
    "message": {
      "imageMessage": {
        "mimetype": "image/jpeg",
        "caption": "Regardez ça",
        "url": "https://mmg.whatsapp.net/...",
        "fileSha256": "...",
        "mediaKey": "...",
        "fileLength": "48213"
      }
    }
  }
}

Selon l'événement, le média reçu (imageMessage, documentMessage, audioMessage) contient soit une URL chiffrée + clé de déchiffrement (url / mediaKey — format natif WhatsApp), soit directement le fichier en base64 si le moteur WhatsApp est configuré pour l'inclure. Dans tous les cas, le champ mimetype indique le type de fichier et caption la légende éventuelle (image/document). Le contenu brut de l'événement event est transmis tel que reçu du moteur WhatsApp, sans transformation de notre côté.

Lister vos sessions par API

curl -H "X-API-Key: VOTRE_CLE" https://thebigsender.com/api/v1/sessions