مكتبة Node.js

إرسال رسائل SMS وواتساب ورموز OTP من Node.js عبر المكتبة الرسمية

envoisms هي مكتبة Node.js وTypeScript الرسمية من EnvoiSMS.ma. نفّذ npm install envoisms، وأنشئ EnvoiSMSClient بمفتاح API الخاص بك، ثم أرسل رسائل SMS وواتساب ورموز التحقق من أي خدمة 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

توجيه محلي

Maroc Telecom (IAM) • Inwi • Orange

إشعارات تسليم حقيقية DLR

توقيع HMAC-SHA256

تسعير واضح بالدرهم

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

التثبيت وأول رسالة SMS

npm install envoisms، ثم ‎const client = new EnvoiSMSClient(process.env.ENVOISMS_API_KEY!). تعيد ‎await client.send({ to: '+212600000000', message: '…', from: 'MonBusiness' })‎ معرّف الرسالة، الذي تتابعه عبر getMessage() وتجده في الويب هوك.

import { EnvoiSMSClient } from 'envoisms';
from: اسم المرسل المعتمد، أو احذفه لاستعمال المرسل الافتراضي
sendBulk({ messages: [...], from }) للإرسال الجماعي؛ وlistMessages(50, 0) لآخر عمليات الإرسال

إرسال آمن عند الإعادة وأخطاء مُنمَّطة

يحمل كل استدعاء send() وsendBulk() مفتاح Idempotency-Key — مولَّدًا، أو مرّر idempotencyKey — فلا تُفوتر إعادة المحاولة بعد انتهاء المهلة الرسالة نفسها مرتين أبدًا. ويعيد العميل محاولة ردود 5xx وأخطاء الشبكة أو المهلة حتى maxRetries مرة (2 افتراضيًا) بمهلة متزايدة، ثم يرمي EnvoiSMSError مع الخاصيتين statusCode وcode.

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

SMS أم واتساب، والانتقال التلقائي

SMS افتراضيًا: تصل إلى كل الهواتف المغربية دون أي إعداد غير مفتاح API. أما channel: 'whatsapp' فترسل من رقم WhatsApp Business الخاص بك المربوط بالمنصة — 403 WHATSAPP_NOT_CONNECTED بدونه، و400 OUT_OF_24H_WINDOW للنص الحر خارج نافذة 24 ساعة، ولا خصم في الحالتين. خارج النافذة مرّر قالبًا معتمدًا. وcascade: true تعيد الرسالة إلى SMS إذا تعذر الوصول إلى الرقم أو لم يكن لديه واتساب.

template: { name: 'order_shipped', language: 'fr', variables: ['89240'] }
خطأ شائع: نص من نوع SMS مع channel: 'whatsapp' لأن الزبون يستخدم واتساب — أرسله كـ SMS

OTP والويب هوك والحساب

تعيد ‎client.sendOtp({ to, brand, code_length: 6, expiry: 600 })‎ معرّف session_id؛ وتعيد ‎client.checkOtp({ session_id, code })‎ الحقل verified؛ وتقرأ getOtpSession() الجلسة دون استهلاك محاولة. وتتحقق ‎EnvoiSMSClient.verifyWebhookSignature(rawBody, signatureHeader, secret)‎ من الترويسة X-EnvoiSMS-Signature على الجسم الخام لا على JSON المفكك.

sendOtp({ ..., channel: 'whatsapp' }): رمز عبر واتساب من المرسل المشترك، دون ربط
getBalance() وlistPacks() وlistPaymentMethods() وcreateTopup()
analytics(30) وcreateApiKey() وcreateOptout()

أسئلة شائعة

كل ما تحتاج معرفته عن مكتبة Node.js.

هل توفر المكتبة أنماط TypeScript؟

نعم. envoisms هي مكتبة Node.js / TypeScript الرسمية: استورد EnvoiSMSClient وEnvoiSMSError مباشرة في شيفرة TypeScript.

كيف أتحقق من ويب هوك الحالة مع Express؟

احتفظ بجسم الطلب الخام (لا JSON المفكك) ومرّره، مع الترويسة X-EnvoiSMS-Signature وسرّ الويب هوك، إلى EnvoiSMSClient.verifyWebhookSignature(). لا تثق بالمحتوى إلا إذا أعادت true.

هل يمكنني إرسال رموز OTP عبر واتساب دون رقم WhatsApp Business؟

نعم. sendOtp() مع channel: 'whatsapp' تمر عبر المرسل المشترك لـ EnvoiSMS ولا تتطلب أي ربط. وحدها رسائل واتساب العادية المرسلة عبر send() تتطلب رقمك المربوط.

ابدأ التكامل مع مكتبة Node.js الآن

أنشئ حسابك في أقل من دقيقتين. احصل فوراً على رصيد 5 دراهم مجاناً لاختبار الـ API.

تفعيل حسابي المجاني تصفح توثيق الـ API