Aller au contenu
WbizTool

API de messagerie

API d'envoi de messages

Envoyez un texte, une image ou un document WhatsApp à un numéro de téléphone depuis votre numéro WhatsApp connecté. Utilisez-la pour les confirmations de commande, les rappels de paiement, les alertes et les réponses du support.

POSThttps://wbiztool.com/api/v1/send_msg/

Corps: JSON, champs de formulaire, ou multipart/form-data pour téléverser un fichier

Le message est mis en file d'attente et envoyé depuis votre numéro WhatsApp en quelques instants. La réponse vous fournit un msg_id que vous pouvez utiliser pour vérifier son statut.

Exemple rapide#

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

Remplacez YOUR_API_KEY et 678 par votre propre clé et l'ID de votre numéro. Consultez Authentification pour savoir où les trouver. La clé va dans l'en-tête Authorization: Bearer (recommandé) ; client_id et api_key dans le corps, en JSON ou en champs de formulaire, fonctionnent aussi : les exemples plus bas les utilisent.

Paramètres de la requête#

Authentification

AuthorizationheaderRecommandé

Bearer YOUR_API_KEY : votre clé API, dans Paramètres → Clés API. Avec l'en-tête, client_id et api_key peuvent être omis du corps ; si la clé est envoyée aux deux endroits, une clé valide dans l'en-tête est utilisée. Consultez Envoyer la clé dans un en-tête.

client_idintegerSans l'en-tête Authorization

Votre ID client API, dans Paramètres → Clés API. Facultatif avec l'en-tête ; si vous l'envoyez, il doit correspondre à l'espace de travail de la clé.

api_keystringSans l'en-tête Authorization

Votre clé API, sur cette même page, lorsque vous ne l'envoyez pas dans l'en-tête.

whatsapp_clientintegerObligatoire si vous avez plusieurs numéros

ID du numéro WhatsApp ou du compte Telegram depuis lequel envoyer, dans les paramètres WhatsApp. Si vous l'omettez, le seul numéro connecté est utilisé, WhatsApp d'abord : un seul numéro WhatsApp connecté est utilisé même si un compte Telegram est aussi connecté, et un compte Telegram seulement si aucun numéro WhatsApp n'est connecté. Un @username utilise le seul compte Telegram connecté.

Destinataire et message

phonestringobligatoire

Le numéro WhatsApp du destinataire. Les espaces, +, -, ., les parenthèses et un 00 initial sont supprimés automatiquement : +91 98765-43210 fonctionne donc. Les valeurs de tableur comme 919876543210.0 et 9.19876543210E+11 sont lues comme leurs chiffres, mais une valeur arrondie comme 9.19877E+11 est refusée, car il manque des chiffres. Envoyez le numéro soit avec son indicatif pays (919876543210), soit sans celui-ci (9876543210) accompagné de country_code. Un numéro local écrit avec son 0 initial fonctionne aussi : 09876543210 avec country_code 91 part vers 919876543210, et 0612345678 avec 39 (Italie, où le 0 fait partie du numéro) part vers 390612345678. Un numéro écrit avec + ou 00 porte son propre indicatif pays : country_code ne lui est pas ajouté, et un (0) entre parenthèses après l'indicatif est supprimé, donc +44 (0)20 7946 0018 part vers 442079460018. Depuis un compte Telegram, phone peut aussi être un @username, un lien t.me/username ou tg:<id>.

country_codestringfacultatif

Indicatif téléphonique du pays sans +, par exemple 91 pour l'Inde ou 1 pour les États-Unis. Il est ajouté devant phone, sauf si le numéro commence déjà par celui-ci ou est écrit avec + ou 00. Exception : avec 91, un numéro à 10 chiffres reçoit toujours le préfixe. Avec les autres indicatifs, un numéro local qui commence par les mêmes chiffres ne reçoit pas de préfixe : envoyez-le donc avec l'indicatif pays inclus.

msg_typeintegerfacultatif

0 texte (par défaut), 1 image, 2 fichier ou document.

msgstringObligatoire lorsque msg_type vaut 0

Texte du message, jusqu'à 3 000 caractères. Pour les images et les fichiers, il s'agit de la légende, qui peut être vide. La mise en forme WhatsApp fonctionne : *bold*, _italic_, ~strikethrough~. message est accepté comme alias.

Images et fichiers

img_urlstringObligatoire lorsque msg_type vaut 1 et qu'aucun fichier n'est téléversé

URL publique http ou https de l'image.

file_urlstringObligatoire lorsque msg_type vaut 2 et qu'aucun fichier n'est téléversé

URL publique http ou https à partir de laquelle le fichier peut être téléchargé directement.

filefilefacultatif

Téléversez l'image ou le fichier au lieu de fournir une URL. Envoyez la requête en multipart/form-data avec le champ nommé file.

file_namestringfacultatif

Nom du fichier affiché au destinataire, par exemple invoice-4821.pdf. Son extension détermine la façon dont le fichier est envoyé : incluez-en donc une. Il est envoyé en minuscules, les caractères comme & : ? * $ ; sont remplacés par _, et il est tronqué à 150 caractères. Si vous l'omettez, le nom est tiré de l'URL ou du fichier téléversé.

Options d'envoi

expire_after_secondsintegerfacultatif

Marque le message comme expiré (statut 4) s'il n'a pas été envoyé dans ce nombre de secondes, par exemple 3600 pour une heure. Utile pour les messages urgents comme les heures de livraison estimées. Une tâche en arrière-plan s'en charge au moins 30 secondes après l'échéance : ne comptez donc pas dessus pour des délais inférieurs à une minute.

webhookstringfacultatif

URL qui reçoit un POST lorsque le message est envoyé, échoue, est annulé ou expire. Consultez Webhook.

Envoyer des images et des fichiers#

Limites de téléchargement pour img_url et file_url :

  • L'URL doit être publique : http ou https, accessible depuis Internet. Jusqu'à 5 redirections sont suivies, et chacune doit aussi mener à une adresse publique.
  • Les fichiers liés peuvent peser jusqu'à 100 Mo. Le serveur doit commencer à répondre dans les 45 secondes et ne pas rester bloqué plus longtemps.
  • Le fichier est récupéré au moment où vous appelez l'API : un lien cassé échoue donc immédiatement avec Invalid file url.

Les fichiers envoyés avec msg_type 2 gardent ces extensions :

CatégorieExtensions
Images.jpg, .jpeg, .jpe, .png, .gif, .webp, .bmp
Documents.pdf, .doc, .docx, .docm, .xls, .xlsx, .xlsm, .xlsb, .ppt, .pptx, .pptm, .txt, .csv
Audio.mp3, .mpga, .m4a, .aac, .wav, .ogg, .oga
Vidéo.mp4, .mov, .avi, .webm
Archives.zip, .rar

Ces vérifications ont lieu au moment de l'envoi du message, et non lors de l'appel à l'API : ces échecs n'apparaissent donc que dans Statut du message et dans le webhook :

Problèmeerror dans Statut du message
Une image (msg_type 1) de plus de 16 MoFile exceeds WhatsApp size limit (16MB max)
Une vidéo (.mp4, .webm) de plus de 64 Mo, y compris envoyée comme image (msg_type 1)File exceeds WhatsApp size limit (64MB max)
Tout autre fichier (msg_type 2) de plus de 100 MoFile exceeds WhatsApp size limit (100MB max)
Un fichier vide (0 octet)The file is empty
Un fichier .wav ou .ogg envoyé comme image (msg_type 1)File type not supported

L'audio WAV et OGG ne peut pas être envoyé comme image (msg_type 1). Envoyé comme fichier (msg_type 2), il arrive comme document sous son propre nom, par exemple recording.wav. Les fichiers .mp3, .mpga, .m4a et .aac arrivent comme audio lisible dans la discussion, et msg suit dans un message texte séparé (l'audio n'a pas de légende).

Image depuis une URL
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 1,
    "country_code": "91",
    "phone": "9876543210",
    "img_url": "https://example.com/offers/diwali-sale.jpg",
    "msg": "Our Diwali sale starts today 🎉"
  }'
Téléverser un fichier
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -F client_id=12345 \
  -F api_key=YOUR_API_KEY \
  -F whatsapp_client=678 \
  -F msg_type=2 \
  -F country_code=91 \
  -F phone=9876543210 \
  -F "msg=Your invoice for order #4821 is attached." \
  -F file_name=invoice-4821.pdf \
  -F file=@./invoice-4821.pdf

Utiliser les clients officiels#

Les clients Python et Node.js appellent cet endpoint pour vous.

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id="12345")

result = client.send_message(
    phone="9876543210",
    country_code="91",
    msg="Hi Aman, your order #4821 has shipped.",
    whatsapp_client=678,
)
print(result)

Les erreurs lèvent requests.HTTPError. Lisez la raison avec e.response.json()["message"].

Réponse#

Une requête réussie renvoie le code HTTP 200 :

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}
ChampTypeDescription
statusinteger1 si le message a été mis en file d'attente, 0 si la requête a échoué.
messagestringCreated en cas de succès, sinon l'erreur.
msg_idintegerID du message en file d'attente. Enregistrez-le pour vérifier son statut plus tard. Présent uniquement en cas de succès.

"status": 1 signifie que le message a été mis en file d'attente, pas qu'il a déjà atteint le destinataire. Utilisez un webhook ou Statut du message pour confirmer qu'il a été envoyé.

Erreurs#

Les erreurs renvoient le code HTTP 400 avec status à 0 (Account Disabled n'a pas de champ status) :

{ "status": 0, "message": "Msg cant be null" }
MessageComment corriger
Auth Error - Please send correct API key and Client idEnvoyez une api_key non vide.
Invalid client id.Envoyez client_id sous forme de nombre.
Auth Error: invalid api keyVérifiez que la clé existe, n'a pas été supprimée et appartient à ce client_id.
Either phone or group_name parameter is requiredAjoutez phone.
Please provide either phone OR group_name, not bothSupprimez l'un des deux.
Invalid phone numberphone doit être un numéro de 6 à 17 chiffres. Les lettres et les autres symboles ne sont pas acceptés, pas plus qu'une valeur de tableur arrondie comme 9.19877E+11.
Invalid Contact Number "…"Une fois l'indicatif pays ajouté, le numéro doit comporter de 7 à 15 chiffres.
Msg cant be nullLes messages texte (msg_type 0) nécessitent msg.
Message length is too longLimitez msg à 3 000 caractères maximum.
Image Url Can't be nullPour msg_type 1, envoyez img_url ou téléversez un file.
File Url Can't be nullPour msg_type 2, envoyez file_url ou téléversez un file.
Invalid file url, Can't download / Invalid file urlL'URL n'est pas publique, le délai a expiré ou le fichier dépasse 100 Mo.
Invalid whatsapp clientCet ID whatsapp_client ne fait pas partie de votre espace de travail.
Invalid whatsapp client id.Envoyez whatsapp_client. Il est obligatoire lorsque votre espace de travail possède plusieurs numéros connectés.
Telegram usernames can only be sent to from a Telegram account: pass its id as whatsapp_clientUn @username, un lien t.me ou tg:<id> dans phone nécessite un compte Telegram comme whatsapp_client.
Not enough creditsL'espace de travail est sur le forfait gratuit et n'a plus de messages : les forfaits payants envoient des messages illimités. Voir Quand il ne reste plus de messages.
Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow. (HTTP 429, "code": "daily_limit_reached")Ce numéro a pris 1 000 messages au cours des dernières 24 heures (usage raisonnable). La réponse contient quand même le msg_id du message refusé, qui apparaît en échec. Envoyez le reste plus tard ou depuis un autre numéro.
Demo Account can not access apisUtilisez un compte standard.
Account DisabledVotre compte est désactivé. Contactez le support.
Invalid JSON format: …Le corps JSON n'est pas valide, souvent à cause d'une virgule finale ou d'un saut de ligne non échappé dans msg. Utilisez \n pour les retours à la ligne.

Un message mis en file d'attente peut encore échouer au moment de son envoi, par exemple avec File exceeds WhatsApp size limit (…). Ces erreurs n'apparaissent jamais dans cette réponse. Consultez Envoyer des images et des fichiers et vérifiez le statut du message.

Webhook#

Si vous transmettez webhook, WbizTool envoie un POST à cette URL lorsque le message est envoyé ou échoue, ainsi que lorsqu'il est annulé ou expire avant d'avoir été envoyé. Le corps est encodé comme un formulaire (application/x-www-form-urlencoded), et non en JSON :

msg_id=9817263&status=SENT
ChampValeurs
msg_idLe msg_id renvoyé lors de l'envoi du message.
statusSENT, FAILED, CANCELLED (annulé avant l'envoi : avec Annuler un message, depuis le tableau de bord, ou suite à la suppression de son numéro WhatsApp ou de sa campagne) ou EXPIRED (non envoyé avant l'écoulement de expire_after_seconds)

Chaque webhook est signé : les en-têtes WbizTool-Timestamp et WbizTool-Signature (v1= suivi d'un HMAC-SHA256 de <timestamp>.<raw body> avec le secret de signature de votre espace de travail) vous permettent de vérifier qu'il vient de WbizTool. Le secret et la vérification en Python et Node.js se trouvent dans Signatures des webhooks ; les récepteurs qui ignorent les en-têtes continuent de fonctionner.

Répondez avec n'importe quel code 2xx ; une redirection est suivie, 3 fois au maximum. Si votre endpoint ne répond pas dans les 10 secondes, est injoignable ou renvoie un code 429 ou 5xx, WbizTool réessaie après 30 secondes, 1 minute et 2 minutes (4 tentatives au total). Les autres réponses 4xx ne sont pas retentées. L'URL doit être une adresse publique d'internet : un webhook vers une adresse privée ou locale (comme 192.168.x.x ou localhost) n'est pas envoyé.

Conseils#

  • Numéros de téléphone : stockez les numéros au format international et envoyez-les avec country_code pour éviter toute ambiguïté.
  • Retours à la ligne en JSON : écrivez-les sous la forme \n dans msg. Un saut de ligne brut rend le JSON invalide.
  • Gardez votre numéro connecté : les messages sont envoyés depuis votre numéro WhatsApp, qui doit donc rester connecté dans les paramètres WhatsApp.
  • Nombreux destinataires : pour envoyer le même message à plusieurs numéros en une seule requête, utilisez Envoyer à plusieurs numéros. Pour les campagnes importantes, téléversez plutôt un tableur depuis la page Campagnes.