SDK Node.js

Envoyer des SMS, WhatsApp et OTP depuis Node.js avec le SDK officiel

envoisms est le SDK Node.js et TypeScript officiel d'EnvoiSMS.ma. npm install envoisms, un EnvoiSMSClient créé avec votre clé API, et vous envoyez SMS, messages WhatsApp et codes à usage unique depuis n'importe quel service Node.js.

send.ts (SDK envoisms, Node.js & TypeScript)

// npm install envoisms
import { EnvoiSMSClient, EnvoiSMSError } from 'envoisms';

const client = new EnvoiSMSClient({
  apiKey: process.env.ENVOISMS_API_KEY!,
  maxRetries: 3,      // 5xx et erreurs réseau, délai exponentiel
  timeoutMs: 20000,
});

try {
  const result = await client.send({
    to: '+212600000000',
    message: 'Votre commande #1042 est confirmée.',
    from: 'MonBusiness', // Sender ID validé, ou omis
  }); // Idempotency-Key ajouté : un nouvel essai ne facture jamais deux fois

  console.log('Message ID:', result.id); // getMessage(result.id), webhooks
} catch (err) {
  if (err instanceof EnvoiSMSError) {
    console.error(`${err.statusCode} ${err.code}: ${err.message}`);
  }
}

● Routes locales MarocIAM • Inwi • Orange

https://api.envoisms.ma/v1

Routes locales

Maroc Telecom (IAM) • Inwi • Orange

Accusés réels DLR

Signatures HMAC-SHA256

Tarifs clairs en MAD

dès 0,60 MAD/SMS • 5 MAD offerts

Installation et premier SMS

npm install envoisms, puis const client = new EnvoiSMSClient(process.env.ENVOISMS_API_KEY!). await client.send({ to: '+212600000000', message: '…', from: 'MonBusiness' }) renvoie l'identifiant du message, que vous suivez avec getMessage() et retrouvez dans vos webhooks.

import { EnvoiSMSClient } from 'envoisms';
from : votre Sender ID validé, ou omis pour l'expéditeur par défaut
sendBulk({ messages: [...], from }) pour un envoi groupé ; listMessages(50, 0) pour les derniers envois

Envois rejouables et erreurs typées

Chaque send() et sendBulk() porte un Idempotency-Key — généré, ou passez idempotencyKey — : un nouvel essai après un timeout ne facture jamais le même message deux fois. Le client rejoue les réponses 5xx et les erreurs réseau ou de timeout jusqu'à maxRetries fois (2 par défaut), avec un délai exponentiel, puis lève EnvoiSMSError avec les propriétés statusCode et code.

new EnvoiSMSClient({ apiKey, maxRetries: 3, timeoutMs: 20000 })
err instanceof EnvoiSMSError → err.statusCode, err.code

SMS ou WhatsApp, et la cascade

Le SMS par défaut : il atteint tous les mobiles marocains sans autre configuration que la clé API. channel: 'whatsapp' envoie depuis votre propre numéro WhatsApp Business connecté — 403 WHATSAPP_NOT_CONNECTED sans numéro, 400 OUT_OF_24H_WINDOW pour un texte libre hors de la fenêtre de 24 heures, rien de facturé dans les deux cas. Hors de la fenêtre, passez un template approuvé. cascade: true repasse en SMS si le numéro est injoignable ou n'a pas WhatsApp.

template: { name: 'order_shipped', language: 'fr', variables: ['89240'] }
Erreur fréquente : un texte de type SMS avec channel: 'whatsapp' parce que le client utilise WhatsApp — envoyez-le en SMS

OTP, webhooks et compte

client.sendOtp({ to, brand, code_length: 6, expiry: 600 }) renvoie un session_id ; client.checkOtp({ session_id, code }) renvoie verified ; getOtpSession() lit une session sans consommer de tentative. EnvoiSMSClient.verifyWebhookSignature(rawBody, signatureHeader, secret) vérifie l'en-tête X-EnvoiSMS-Signature sur le corps brut, pas sur le JSON décodé.

sendOtp({ ..., channel: 'whatsapp' }) : code WhatsApp via l'expéditeur partagé, sans connexion
getBalance(), listPacks(), listPaymentMethods(), createTopup()
analytics(30), createApiKey(), createOptout()

Questions fréquentes

Tout savoir sur SDK Node.js.

Le SDK fournit-il des types TypeScript ?

Oui. envoisms est le SDK Node.js / TypeScript officiel : importez EnvoiSMSClient et EnvoiSMSError directement dans votre code TypeScript.

Comment vérifier un webhook de statut avec Express ?

Gardez le corps brut de la requête (pas le JSON décodé) et passez-le, avec l'en-tête X-EnvoiSMS-Signature et votre secret de webhook, à EnvoiSMSClient.verifyWebhookSignature(). Ne faites confiance à la charge utile que si elle renvoie true.

Puis-je envoyer des codes OTP sur WhatsApp sans numéro WhatsApp Business ?

Oui. sendOtp() avec channel: 'whatsapp' passe par l'expéditeur partagé d'EnvoiSMS et ne demande aucune connexion. Seuls les messages WhatsApp ordinaires envoyés avec send() exigent votre propre numéro connecté.

Prêt à intégrer SDK Node.js ?

Créez votre compte en moins de 2 minutes. Bénéficiez immédiatement de 5 MAD de crédit gratuit pour tester l'API.

Activer mon compte gratuit Parcourir la Doc API