Documentation de l'API WhatsApp

Référence complète de l'API REST WhatsApp. Authentification, endpoints, webhooks, codes d'erreur et exemples de code.

Authentification

Toutes les requêtes API nécessitent une clé API transmise dans l'en-tête Authorization. Votre clé API est générée lors de la création d'une instance et est disponible dans votre tableau de bord.

Authorization: Bearer YOUR_API_KEY

Les requêtes sans clé API valide renvoient une erreur 401 Unauthorized. Les clés API sont propres à chaque instance — chaque instance possède sa propre clé.

URL de Base

https://api2whats.com

Tous les endpoints sont relatifs à cette URL de base. Utilisez exclusivement HTTPS — les requêtes HTTP sont rejetées.

Envoyer un Message Texte

Envoyer un message texte à un numéro WhatsApp.

POST /send-text

Corps de la requête :

{
  "to": "971501234567",
  "message": "Hello from the API!"
}

Paramètres :

  • to (chaîne, requis) — Numéro de téléphone du destinataire avec l'indicatif du pays, sans + ni espaces
  • message (chaîne, requis) — Contenu du texte, prend en charge Unicode et les emoji

Réponse :

{
  "success": true,
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "sent"
  }
}

Envoyer une Image

Envoyer une image via URL ou Base64.

POST /send-image

{
  "to": "971501234567",
  "image": "https://example.com/photo.jpg",
  "caption": "Check out this product!"
}

Paramètres :

  • to (chaîne, requis) — Numéro de téléphone du destinataire
  • image (chaîne, requis) — URL de l'image ou chaîne encodée en Base64
  • caption (chaîne, facultatif) — Légende textuelle sous l'image

Envoyer une Vidéo

Envoyer un fichier vidéo.

POST /send-video

{
  "to": "971501234567",
  "video": "https://example.com/demo.mp4",
  "caption": "Product demo video"
}

Envoyer un Audio

Envoyer un fichier audio (note vocale ou clip audio).

POST /send-audio

{
  "to": "971501234567",
  "audio": "https://example.com/voice.mp3"
}

Envoyer un Sticker

Envoyer une image sticker (format WebP ou PNG).

POST /send-sticker

{
  "to": "971501234567",
  "sticker": "https://example.com/sticker.webp"
}

Envoyer un Document

Envoyer une pièce jointe (PDF, DOCX, XLSX, etc.).

POST /send-document

{
  "to": "971501234567",
  "document": "https://example.com/invoice.pdf",
  "filename": "invoice-march-2026.pdf"
}

Paramètres :

  • to (chaîne, requis) — Numéro de téléphone du destinataire
  • document (chaîne, requis) — URL du document ou chaîne encodée en Base64
  • filename (chaîne, facultatif) — Nom du fichier affiché (par défaut, le nom du fichier de l'URL)

Envoyer une Position

Envoyer une position géographique.

POST /send-location

{
  "to": "971501234567",
  "latitude": 25.2048,
  "longitude": 55.2708,
  "name": "Dubai Office"
}

Configuration du Webhook

Les webhooks permettent à votre serveur de recevoir les messages entrants en temps réel. Définissez votre URL de webhook via l'API :

POST /set-webhook

{
  "url": "https://yourserver.com/webhook"
}

Lorsque quelqu'un envoie un message à votre numéro connecté, l'API envoie une requête POST à votre URL :

{
  "event": "message",
  "instance": "instance_abc123",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hi, I need help",
    "timestamp": 1691234567,
    "type": "text"
  }
}

Vérifiez les webhooks entrants à l'aide de l'en-tête X-Signature inclus dans chaque requête.

Gestion des Instances

Vérifiez l'état de connexion de votre instance WhatsApp :

GET /instance/status

Réponse :
{
  "connected": true,
  "phone": "971501234567",
  "name": "Business Account"
}

Codes d'Erreur

Code HTTPCode d'ErreurDescription
400INVALID_PHONELe format du numéro de téléphone est invalide
400MISSING_FIELDUn champ requis est absent de la requête
401INVALID_API_KEYLa clé API est invalide ou manquante
404INSTANCE_NOT_FOUNDL'instance n'existe pas ou n'est pas connectée
429RATE_LIMIT_EXCEEDEDTrop de requêtes, consultez l'en-tête Retry-After
500INTERNAL_ERRORErreur serveur, réessayez avec un backoff exponentiel

Limites de Débit

Les limites de débit varient selon le forfait :

  • Basic — 100 requêtes/minute
  • Professional — 300 requêtes/minute
  • Enterprise — 1000 requêtes/minute

En cas de limitation de débit, l'API renvoie 429 Too Many Requests avec un en-tête Retry-After indiquant quand vous pourrez réessayer.

Exemples de Code

Des exemples fonctionnels en PHP, Python, JavaScript et cURL sont disponibles dans notre section d'exemples de code. Chaque exemple est un script complet et exécutable.

Pagination et Limites

Lors de l'énumération de ressources (instances, historique des messages), l'API prend en charge la pagination via des paramètres de requête :

GET /messages?page=1&limit=50

Réponse :
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 342,
    "pages": 7
  }
}

La taille de page par défaut est de 50. Le maximum est de 100. Utilisez les paramètres de requête page et limit pour parcourir les résultats.

Envoi par Lot

Envoyez des messages à plusieurs destinataires en un seul appel API. C'est plus efficace que d'effectuer des requêtes individuelles pour chaque destinataire.

POST /send-batch

{
  "messages": [
    { "to": "971501234567", "message": "Hello Ahmed!" },
    { "to": "971509876543", "message": "Hello Sara!" },
    { "to": "971501112222", "message": "Hello Omar!" }
  ]
}

L'envoi par lot applique automatiquement la limitation de débit. La réponse inclut le statut de chaque message afin que vous sachiez lesquels ont réussi et lesquels ont échoué.

Recommandations pour l'Envoi de Média

Lors de l'envoi de média, suivez ces recommandations pour une livraison optimale :

  • Images — JPEG ou PNG, 5 Mo maximum via Base64, plus via URL. Dimensions recommandées : 1200x630 pour le format paysage, 600x600 pour le format carré.
  • Videos — Format MP4, 16 Mo maximum. L'encodage H.264 est recommandé pour une compatibilité optimale.
  • Documents — PDF, DOCX, XLSX, PPTX, TXT. 100 Mo maximum via URL.
  • Audio — Format MP3 ou OGG. 16 Mo maximum.
  • Stickers — WebP ou PNG, 512x512 pixels, 500 Ko maximum.
  • Locations — Coordonnées latitude/longitude avec nom et adresse facultatifs.

Pour l'encodage Base64, incluez le préfixe d'URI de données : data:image/jpeg;base64,/9j/4AAQ.... Pour les URL, assurez-vous que l'URL est publiquement accessible et renvoie l'en-tête Content-Type correct.

Variables d'Environnement

Stockez votre clé API et votre configuration dans des variables d'environnement, et non dans votre code :

# .env file
WHATSAPP_API_KEY=your_api_key_here
WHATSAPP_API_BASE=https://api2whats.com
WEBHOOK_SECRET=your_webhook_secret_here

Ne commitez jamais votre fichier .env dans votre gestionnaire de versions. Ajoutez-le à .gitignore. Utilisez les paramètres de variables d'environnement de votre plateforme de déploiement en production.

Gestion des Versions

L'API est versionnée via le chemin de l'URL. La version actuelle est v1 (la version par défaut). Lorsque nous introduirons des changements incompatibles, nous publierons une nouvelle version et maintiendrons l'ancienne pendant au moins 12 mois.

# Current version (implicit)
https://api2whats.com/send-text

# Explicit version (future-proof)
https://api2whats.com/v1/send-text

Journal des Modifications

Nous tenons un journal des modifications public pour tous les changements de l'API. Abonnez-vous au flux RSS du changelog ou suivez-nous sur GitHub pour rester informé. Les changements majeurs sont annoncés par e-mail à tous les utilisateurs enregistrés au moins 30 jours avant le déploiement.

Besoin d'Aide ?

Consultez la FAQ pour les questions courantes. Pour des problèmes spécifiques, contactez notre équipe support. Nous répondons sous 24 heures.

FAQ

Quelle est la longueur maximale d'un message ?

Les messages texte prennent en charge jusqu'à 4 096 caractères. Pour un contenu plus long, envisagez d'envoyer un document ou de diviser le message en plusieurs envois.

Puis-je envoyer des messages à des groupes ?

Actuellement, l'API prend en charge uniquement la messagerie individuelle. La messagerie de groupe figure sur notre feuille de route pour une version future.

Quelle est la vitesse de livraison des messages ?

La plupart des messages sont livrés en 1 à 3 secondes. Le délai de livraison dépend de la connexion réseau du destinataire et de l'état de son appareil. Les messages destinés à des appareils hors ligne sont mis en file d'attente par WhatsApp et livrés dès que l'appareil se reconnecte.

Existe-t-il une offre gratuite ?

Vous pouvez créer un compte et explorer le tableau de bord gratuitement. Les forfaits payants démarrent à 9,99 $/mois pour l'accès à l'API et l'envoi de messages. Contactez-nous pour un accès d'essai.

Que faire si ma clé API est compromise ?

Révoquez immédiatement la clé compromise depuis votre tableau de bord et générez-en une nouvelle. Toutes les sessions actives utilisant l'ancienne clé seront terminées. Nous vous recommandons de renouveler régulièrement vos clés API et de les stocker dans des variables d'environnement.

Puis-je utiliser l'API pour l'envoi en masse ?

Yes, with proper rate limiting. Send messages with 2-3 second delays between them. Do not send identical messages to large groups — personalize each message. Monitor delivery rates and slow down if they drop below 90%. docspage.faq.a6.link

Page de Statut

Consultez l'état de notre système et l'historique de disponibilité sur notre page de statut. Nous fournissons des mises à jour en temps réel pendant les incidents et publions des analyses détaillées après chaque interruption de service.

Prêt à Intégrer ?

Créez un compte et commencez à envoyer des messages en quelques minutes.

Commencer Gratuitement