Node.js SDK

Send SMS, WhatsApp and OTP from Node.js with the official SDK

envoisms is EnvoiSMS.ma's official Node.js and TypeScript SDK. npm install envoisms, create an EnvoiSMSClient with your API key, and send SMS, WhatsApp messages and one-time codes from any Node.js service.

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

Local Routes

Maroc Telecom (IAM) • Inwi • Orange

Verified DLR Receipts

HMAC-SHA256 Signed

Clear MAD Pricing

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

Install and send your first SMS

npm install envoisms, then const client = new EnvoiSMSClient(process.env.ENVOISMS_API_KEY!). await client.send({ to: '+212600000000', message: '…', from: 'MyBusiness' }) returns the message id, which you poll with getMessage() and match in your webhooks.

import { EnvoiSMSClient } from 'envoisms';
from: your validated Sender ID, or omit it for your default
sendBulk({ messages: [...], from }) for a bulk send; listMessages(50, 0) for recent sends

Retry-safe sends and typed errors

Every send() and sendBulk() carries an Idempotency-Key — generated, or pass idempotencyKey — so a retry after a timeout can never bill the same message twice. The client retries 5xx responses and network or timeout errors up to maxRetries times (2 by default) with exponential backoff, then throws EnvoiSMSError with statusCode and code properties.

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

SMS or WhatsApp, and the cascade

Default to SMS: it reaches every Moroccan mobile with no setup beyond the API key. channel: 'whatsapp' sends from your own connected WhatsApp Business number — 403 WHATSAPP_NOT_CONNECTED without one, 400 OUT_OF_24H_WINDOW for free text outside the 24-hour customer window, nothing charged in either case. Outside the window, pass an approved template. cascade: true drops back to SMS when the number is unreachable or has no WhatsApp.

template: { name: 'order_shipped', language: 'fr', variables: ['89240'] }
Common mistake: an SMS-style text with channel: 'whatsapp' because the customer uses WhatsApp — send it as SMS

OTP, webhooks and the account

client.sendOtp({ to, brand, code_length: 6, expiry: 600 }) returns a session_id; client.checkOtp({ session_id, code }) returns verified; getOtpSession() inspects a session without consuming an attempt. EnvoiSMSClient.verifyWebhookSignature(rawBody, signatureHeader, secret) checks the X-EnvoiSMS-Signature header against the raw body, not parsed JSON.

sendOtp({ ..., channel: 'whatsapp' }): a WhatsApp code through the shared sender, no connection needed
getBalance(), listPacks(), listPaymentMethods(), createTopup()
analytics(30), createApiKey(), createOptout()

Frequently asked questions

Everything you need to know about Node.js SDK.

Does the SDK ship TypeScript types?

Yes. envoisms is the official Node.js / TypeScript SDK: import EnvoiSMSClient and EnvoiSMSError straight into TypeScript code.

How do I verify a delivery webhook in Express?

Keep the raw request body (not the parsed JSON) and pass it, with the X-EnvoiSMS-Signature header and your webhook secret, to EnvoiSMSClient.verifyWebhookSignature(). Trust the payload only when it returns true.

Can I send WhatsApp OTP codes without a WhatsApp Business number?

Yes. sendOtp() with channel: 'whatsapp' goes through EnvoiSMS's shared sender and needs no connection. Only regular WhatsApp messages sent with send() need your own connected number.

Ready to integrate with Node.js SDK?

Create your account in under 2 minutes. Get 5 MAD of free credit instantly to test the API.

Activate my free account Browse API Docs