Envoyez des messages WhatsApp par API gratuitement

Pour envoyer des messages WhatsApp depuis votre logiciel avec SageMessaging, connectez votre numéro WhatsApp à votre compte en scannant un QR code, créez une clé API, puis installez le SDK de votre langage : une ligne, client.messages.send(), suffit ensuite pour envoyer un message. Il part de votre propre numéro, et SageMessaging ne facture ni abonnement ni message.

Ce guide suit chaque étape, du compte au premier message, puis l'envoi de fichiers, le suivi de la remise et la réception des réponses.

Comment fonctionne SageMessaging pour WhatsApp

SageMessaging se connecte à votre WhatsApp comme un appareil connecté, de la même façon que WhatsApp Web. Votre logiciel envoie une requête à SageMessaging, qui envoie le message depuis votre numéro. Vos clients voient votre nom et votre numéro, pas un numéro partagé ou inconnu, et peuvent vous répondre normalement.

Avec SageMessaging, votre logiciel peut :

• envoyer du texte, des images, des vidéos, de l'audio et des documents, jusqu'à 10 fichiers de 16 Mo par envoi ;
• suivre la remise de chaque message, jusqu'à sa lecture ;
• recevoir les réponses de vos clients et les traiter automatiquement.

Votre équipe garde la main : les conversations apparaissent aussi dans une boîte de réception web, où l'on peut répondre manuellement.

Ce qu'il vous faut avant de commencer

• Un compte SageMessaging, gratuit.
• Un téléphone avec WhatsApp ou WhatsApp Business, sur le numéro qui enverra les messages.
• Une clé API avec la permission messages:send.
• Le SDK de votre langage : JavaScript ou Python. Pour les autres langages, l'API REST fait la même chose.

Créer votre compte

Rendez-vous sur messaging.sagecoders.com et cliquez sur « Créer un compte ». L'inscription est gratuite. Vous arrivez sur votre tableau de bord, d'où vous connecterez WhatsApp et créerez vos clés.

Connecter votre WhatsApp

La connexion se fait en six étapes, comme pour ouvrir WhatsApp Web :

1. Afficher le QR code. Dans le tableau de bord, cliquez sur « Afficher le QR code » dans la carte WhatsApp.
2. Ouvrir WhatsApp sur votre téléphone : WhatsApp ou WhatsApp Business, avec le numéro qui enverra les messages.
3. Aller dans « Appareils connectés ». Sur Android : menu ⋮ en haut à droite, puis « Appareils connectés ». Sur iPhone : Réglages, puis « Appareils connectés ».
4. Connecter un appareil. Touchez « Connecter un appareil », puis déverrouillez le téléphone si WhatsApp le demande.
5. Scanner le QR code affiché à l'écran. Il se renouvelle toutes les 15 secondes : gardez la page ouverte.
6. C'est connecté. Après quelques secondes, la carte affiche « WhatsApp connecté ».

Créer une clé API

Dans l'onglet « Clés API » du tableau de bord, créez une clé pour votre logiciel et cochez seulement les permissions dont il a besoin :

Pour un logiciel qui envoie seulement des notifications, messages:send suffit.

Envoyer votre premier message

Le plus simple est d'utiliser le SDK officiel de votre langage : il gère l'authentification, les erreurs et les fichiers à votre place.

Avec le SDK JavaScript

Le SDK fonctionne avec Node 20 ou plus récent, Bun et Deno, en ESM comme en CommonJS, sans aucune autre dépendance.

npm install sage-messaging

import { SageMessaging } from 'sage-messaging'

// La clé est lue dans la variable SAGE_MESSAGING_API_KEY
const client = new SageMessaging()

await client.messages.send({ phone: '+2250700000000', message: 'Bonjour, votre commande est prête.' })

Avec le SDK Python

Le SDK fonctionne avec Python 3.9 ou plus récent, en version synchrone ou asynchrone (AsyncSageMessaging, mêmes méthodes avec await).

pip install sage-messaging

from sage_messaging import SageMessaging

client = SageMessaging()  # clé lue dans SAGE_MESSAGING_API_KEY

client.messages.send(phone="+2250700000000", message="Bonjour, votre commande est prête.")

Le numéro du destinataire s'écrit au format international, avec l'indicatif du pays. Sans autre précision, le message part sur WhatsApp, depuis le numéro connecté à votre compte.

Votre langage n'a pas de SDK ? Utilisez l'API REST

PHP, Java, C#, Go, Dart ou Ruby n'ont pas encore de SDK : votre logiciel appelle directement l'API REST, par une simple requête HTTP. La clé se place dans l'en-tête Authorization.

curl -X POST https://messaging.sagecoders.com/api/messages \
  -H "Authorization: Bearer $SAGE_MESSAGING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"phone": "+2250700000000", "message": "Bonjour, votre commande est prête."}'

L'API répond 201 Created, avec l'identifiant du message et de la conversation. Les fonctions présentées ci-dessous existent aussi en REST, avec les mêmes paramètres : la référence complète, avec un testeur intégré, se trouve dans l'onglet « Documentation » de votre espace.

Envoyer des fichiers : factures, photos, documents

Une facture en PDF, la photo d'un produit, un bon de livraison : sendMedia envoie jusqu'à 10 fichiers de 16 Mo, dans l'ordre. La légende accompagne le premier fichier. Chaque fichier peut venir du disque, d'une URL publique ou de la mémoire.

En JavaScript :

import { readFile } from 'node:fs/promises'

const res = await client.messages.sendMedia({
  phone: '+2250700000000',
  caption: 'Votre facture de novembre',
  media: [
    { data: await readFile('facture.pdf'), filename: 'facture.pdf' },
    { url: 'https://exemple.com/photo-produit.jpg' },
  ],
})

if (res.failed.length) console.warn('Envoi partiel :', res.failed)

En Python :

res = client.messages.send_media(
    phone="+2250700000000",
    caption="Votre facture de novembre",
    media=[
        {"path": "facture.pdf"},
        {"url": "https://exemple.com/photo-produit.jpg"},
    ],
)

if res["failed"]:
    print("Envoi partiel :", res["failed"])

Si une partie des fichiers seulement est passée, la réponse le signale (code HTTP 207) et liste ceux qui ont échoué : vous pouvez renvoyer uniquement ceux-là.

SageMessaging ne conserve aucun fichier sur ses serveurs : seul le type du fichier est enregistré.

Suivre la remise de chaque message

Chaque message a son accusé, mis à jour en temps réel dans la boîte de réception : vous savez si votre client a reçu sa facture, et s'il l'a ouverte.

Recevoir les réponses de vos clients

Avec les webhooks

Déclarez une adresse de votre logiciel dans l'onglet « Webhooks » de votre espace. À chaque message reçu ou envoyé, SageMessaging y envoie un événement (message.received ou message.sent), signé en HMAC-SHA256 et relancé trois fois en cas d'échec. Les SDK vérifient la signature pour vous.

En JavaScript, avec Express :

import express from 'express'
import { verifyWebhook } from 'sage-messaging'

// Corps brut obligatoire : un JSON re-sérialisé casserait la signature
app.post('/webhooks/sage', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = await verifyWebhook(req.body, req.headers, process.env.SAGE_WEBHOOK_SECRET)

  if (event.event === 'message.received') {
    const { message, conversation } = event.data
    console.log(conversation.contact_phone, message.body)
  }
  res.sendStatus(200)
})

En Python, avec FastAPI :

from sage_messaging import verify_webhook, WebhookVerificationError

@app.post("/webhooks/sage")
async def sage_webhook(request: Request):
    try:
        event = verify_webhook(await request.body(), request.headers, WEBHOOK_SECRET)
    except WebhookVerificationError:
        raise HTTPException(400)

    if event["event"] == "message.received":
        message = event["data"]["message"]
        ...
    return {"ok": True}

Sans webhook

Si votre logiciel ne peut pas recevoir d'appels (une application de bureau, par exemple), il peut aller chercher les nouveaux messages lui-même, avec la permission messages:read :

for await (const msg of client.messages.poll({ direction: 'received' })) {
  console.log(msg.contact_phone, msg.body)
}

Pour reprendre après un redémarrage sans rien manquer, conservez l'identifiant du dernier message traité et passez-le en after_id. Les SDK permettent aussi de lister les conversations non lues et de les marquer comme lues.

Gérer les erreurs

Les SDK transforment chaque erreur en exception précise :

import { ValidationError, GatewayError, SageMessagingError } from 'sage-messaging'

try {
  await client.messages.send({ phone: '+2250700000000', message: 'Bonjour' })
} catch (e) {
  if (e instanceof ValidationError) console.log(e.errors)
  else if (e instanceof GatewayError) console.log(e.detail)
  else if (e instanceof SageMessagingError) console.log(e.message)
  else throw e
}

Les envois ne sont jamais relancés automatiquement. C'est volontaire : un envoi dont la réponse s'est perdue a pu partir, et le relancer enverrait le message en double. Les lectures, elles, sont relancées par les SDK en cas d'erreur réseau.

Les bonnes pratiques

• Écrivez à des personnes qui vous connaissent : vos clients, vos patients, vos élèves. WhatsApp peut restreindre un numéro qui envoie des messages non sollicités en masse ; un message « Non remis » avec le motif « compte restreint » en est le signe.
• Ouvrez WhatsApp au moins tous les 14 jours sur le téléphone, pour garder l'appareil connecté.
• Une clé par logiciel, avec seulement les permissions utiles : en cas de fuite, vous la révoquez sans couper les autres.

Des usages concrets

Une confirmation de commande, une facture en PDF, un rappel de rendez-vous, un résumé quotidien pour le gérant : tout événement de votre logiciel peut devenir un message WhatsApp.

Nous l'utilisons dans nos propres produits. SageHotel envoie chaque soir à l'hôtelier le résumé de sa journée. Sur ce site, les codes de connexion partent par WhatsApp, et notre assistant envoie les cahiers des charges en PDF directement sur le WhatsApp de nos clients.

Récapitulatif

Pour les SMS, SageMessaging fonctionne aussi depuis la carte SIM d'un téléphone Android : lisez notre guide pour envoyer des SMS par API gratuitement. Et si vous préférez qu'on s'en charge, notre équipe développe des logiciels sur mesure avec WhatsApp déjà branché.