Envoyer un SMS en Node.js : fetch, Express et webhooks

const HEADERS = {
  "X-APP-ID":     process.env.CONEXTEO_APP_ID,
  "X-API-KEY":    process.env.CONEXTEO_API_KEY,
  "Content-Type": "application/json",
};

Le piège qui coûte le plus d'heures : intervertir les deux valeurs. L'API répond alors 401 Unauthorized — exactement le même code que si la clé était fausse ou révoquée. On cherche donc du côté de la clé, on en régénère une, et le problème persiste. Le moyen mnémotechnique : APP identifie l'application, KEY est le secret. Si vous obtenez un 401 avec des identifiants fraîchement copiés, échangez les deux en-têtes avant toute autre hypothèse.

const reponse = await fetch("https://api.conexteo.com/messages/sms", {
  method:  "POST",
  headers: HEADERS,
  body: JSON.stringify({
    content:    "Votre code de connexion : 847291",
    sender:     "MaBoutique",
    recipients: ["+33612345678"],
  }),
  signal: AbortSignal.timeout(10_000),
});

console.log(reponse.status, await reponse.json());
// 200 { success: true, message: 'message created',
//       message_id: 123456, credits_used: 1 }

Le corps doit être une chaîne. Passer directement l'objet à body sans JSON.stringify envoie littéralement [object Object], et l'API répond 400. Contrairement à axios, fetch ne sérialise rien pour vous et ne pose pas non plus le Content-Type — d'où sa présence dans les en-têtes ci-dessus.

Second détail : AbortSignal.timeout(). Le fetch de Node n'a aucun délai d'expiration par défaut. Sur un envoi déclenché depuis une route web, une requête qui ne revient pas immobilise le traitement jusqu'au timeout du serveur HTTP.

// ✗ Ce code ne détecte jamais une erreur d'API
try {
  const res  = await fetch(url, options);
  const data = await res.json();
  return data.message_id;        // undefined si l'API a répondu 400
} catch (err) {
  // on n'arrive ici que si le réseau est tombé
}

// ✓ Il faut tester res.ok explicitement
const res = await fetch(url, options);
if (!res.ok) {
  throw new Error(`Conexteo ${res.status} : ${await res.text()}`);
}
return (await res.json()).message_id;

La signature de ce bug en production : des envois qui « réussissent » dans vos journaux, un message_id à undefined en base, et des clients qui n'ont rien reçu. Aucune alerte ne se déclenche, puisque rien n'a levé d'exception.

Si vous utilisez axios, le problème est inversé : axios lève sur tout code ≥ 400, y compris le 409, qui est pourtant un succès. Voir la section suivante.

// conexteo.mjs
const BASE = "https://api.conexteo.com";

export class ConexteoError extends Error {
  constructor(status, corps) {
    super(`Conexteo ${status} : ${corps}`);
    this.name   = "ConexteoError";
    this.status = status;
  }
}

const pause = (n) => new Promise((r) => setTimeout(r, 2 ** n * 500));

async function appeler(chemin, charge, { essais = 3 } = {}) {
  for (let essai = 0; ; essai++) {
    let res;
    try {
      res = await fetch(BASE + chemin, {
        method:  "POST",
        headers: HEADERS,
        body:    JSON.stringify(charge),
        signal:  AbortSignal.timeout(10_000),
      });
    } catch (err) {
      // panne réseau ou expiration : on peut rejouer
      if (essai < essais - 1) { await pause(essai); continue; }
      throw err;
    }

    // 409 : le message existe déjà. C'est un succès, pas une erreur.
    if (res.status === 409) return { deja_envoye: true };

    // On ne rejoue que les erreurs serveur. Jamais un 4xx.
    if (res.status >= 500 && essai < essais - 1) { await pause(essai); continue; }

    if (!res.ok) throw new ConexteoError(res.status, await res.text());
    return res.json();
  }
}

export const envoyerSms = (charge) => appeler("/messages/sms", charge);

Ne rejouez jamais un 4xx. Un 400 rejoué trois fois reste un 400, et chaque tentative consomme du temps de traitement. Seules les erreurs serveur et les pannes réseau méritent une reprise — avec un délai qui double à chaque essai, comme ci-dessus.

await envoyerSms({
  content:     `Votre commande ${commande.reference} est expédiée.`,
  sender:      "MaBoutique",
  recipients:  [client.mobile],
  external_id: `expedition-${commande.id}`,   // déterministe
});

import { Queue } from "bullmq";
const file = new Queue("notifications");

app.post("/commandes", async (req, res) => {
  const commande = await creerCommande(req.body);

  res.status(201).json(commande);             // on répond d'abord

  await file.add("sms-expedition", {          // puis on empile
    commandeId: commande.id,
  });
});

La tentation à éviter : appeler l'API sans await pour « ne pas attendre ». Une promesse non attendue qui échoue devient un unhandledRejection, et selon votre configuration Node, le processus s'arrête. Vous aurez échangé une latence de deux secondes contre un redémarrage de conteneur.

// ✗ Chaîne sans fuseau : interprétée en heure locale du serveur
const quand = "2026-09-15T09:00:00";

// ✓ On exprime l'heure voulue avec son fuseau, puis on convertit
const quand = new Date("2026-09-15T09:00:00+02:00").toISOString();
// "2026-09-15T07:00:00.000Z"

await envoyerSms({
  content:    "Votre rendez-vous est demain à 14h.",
  sender:     "Cabinet",
  recipients: ["+33612345678"],
  scheduleAt: quand,
});

Un conteneur Docker tourne presque toujours en UTC, une machine de développement en Europe/Paris. Le même code produit donc deux résultats différents selon l'endroit où il s'exécute : l'envoi part à la bonne heure sur votre poste, et deux heures trop tôt en production l'été. Exprimez toujours le fuseau dans la chaîne d'entrée, et laissez toISOString() produire le Z final.

import express from "express";
import crypto from "node:crypto";

const app = express();
const SECRET = process.env.CONEXTEO_WEBHOOK_SECRET;        // whsec_…
// Le nom exact de l'en-tête de signature figure dans votre espace
// Mon Compte / API / Webhook. On le lit depuis l'environnement.
const EN_TETE = process.env.CONEXTEO_SIGNATURE_HEADER;

app.post(
  "/webhooks/conexteo",
  express.raw({ type: "application/json" }),        // ← le corps reste un Buffer
  (req, res) => {
    const attendue = crypto
      .createHmac("sha256", SECRET)
      .update(req.body)                             // Buffer brut, pas l'objet
      .digest("hex");

    const recue = Buffer.from(req.get(EN_TETE) ?? "", "utf8");
    const ref   = Buffer.from(attendue, "utf8");

    // timingSafeEqual lève si les longueurs diffèrent : on teste avant.
    if (recue.length !== ref.length || !crypto.timingSafeEqual(recue, ref)) {
      return res.sendStatus(401);
    }

    const evenement = JSON.parse(req.body);
    const idEvenement = req.get("X-Conexteo-Webhook-Id");

    // Conexteo réessaie huit fois sur environ dix-huit heures.
    // Le même événement peut donc arriver plusieurs fois.
    if (dejaTraite(idEvenement)) return res.sendStatus(200);

    traiter(evenement);            // rapide, ou empilé dans une file
    res.sendStatus(200);
  },
);

Si express.json() est déclaré globalement par un app.use() plus haut dans le fichier, il s'applique aussi à cette route et le express.raw() local arrive trop tard. Déclarez la route de webhook avant le middleware global, ou conservez le corps brut via l'option verify de express.json().

Répondez 200 vite. Un traitement long fait expirer la requête côté Conexteo, qui considère l'envoi comme échoué et réessaie — vous recevez alors le même événement encore et encore. Accusez réception d'abord, travaillez ensuite.

export const envoyerRcs = (charge) => appeler("/messages/rcs", charge);

await envoyerRcs({
  type: "card",
  data: {
    title:       "Votre commande est prête",
    description: "Retrait en boutique jusqu'à samedi 19h.",
    media:       "https://exemple.fr/colis.jpg",     // jamais de WebP
    buttons: [
      { type: "url",      title: "Suivre",   url: "https://…" },
      { type: "location", title: "Itinéraire" },
    ],
  },
  fallback: {                          // parti en SMS si le mobile ne gère pas le RCS
    content: "Votre commande est prête. Retrait jusqu'à samedi 19h.",
    sender:  "MaBoutique",
  },
  contacts: [{ recipient: "+33612345678" }],
});

// La réponse sépare les deux compteurs :
// { rcs: { sent: 412 }, sms: { sent: 88 } }
//   → 82 % de votre base a reçu la version enrichie.

Le champ s'appelle contacts, pas recipients. C'est la première erreur quand on recopie le code SMS : l'API répond 400. En contrepartie, chaque entrée peut porter des variables libres, réutilisables dans le corps du message.

Les deux compteurs de la réponse sont la mesure la plus utile de toute l'API : ils vous donnent le taux de compatibilité RCS réel de votre base, campagne après campagne. Aucune statistique de marché ne remplace ce chiffre.

Votre premier SMS en Node dans dix minutes

L'inscription est gratuite et sans carte bancaire, avec cinq SMS de test pour vérifier le rendu réel sur mobile. Vos identifiants d'API sont disponibles immédiatement dans Mon Compte / API / Webhook.