مكتبة PHP

إرسال رسائل SMS وواتساب ورموز OTP بلغة PHP عبر المكتبة الرسمية

envoisms/envoisms-php هي مكتبة PHP الرسمية من EnvoiSMS.ma. عميل واحد ومفتاح API واحد: إرسال رسائل SMS وواتساب، ورموز OTP، والإرسال الجماعي، وحالة الرسائل، والتحقق من الويب هوك، ورصيد الحساب. وهي أيضًا أساس حزمة Laravel ‏envoisms/laravel-otp.

cURL REST API

curl -X POST https://api.envoisms.ma/v1/messages \
  -H "Authorization: Bearer env_live_votretoker" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+212661234567",
    "message": "Votre code de confirmation est : 849201. Expire dans 3 minutes.",
    "from": "VOTREMARQUE"
  }'

● 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

composer require envoisms/envoisms-php، ثم ‎$client = new EnvoiSMS\Client(getenv('ENVOISMS_API_KEY')). تعيد ‎$client->send(['to' => '+212600000000', 'message' => '…', 'from' => 'MonBusiness'])‎ معرّف الرسالة، الذي تجده لاحقًا عبر getMessage() وفي الويب هوك.

'from': اسم المرسل المعتمد، أو احذفه لاستعمال المرسل الافتراضي
sendBulk(['messages' => [...], 'from' => ...]) للإرسال الجماعي
getMessage($id) وlistMessages(50, 0) لتتبع عمليات الإرسال

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

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

new Client(getenv('ENVOISMS_API_KEY'), maxRetries: 3, timeoutSeconds: 20)
catch (EnvoiSMS\EnvoiSMSError $e): $e->statusCode, $e->errorCode

SMS أم واتساب: اختيار القناة

SMS هي القناة الافتراضية: تصل إلى كل الهواتف المغربية (اتصالات المغرب، إنوي، أورنج) دون أي إعداد غير مفتاح API. أما ‎'channel' => 'whatsapp'‎ فترسل من رقم WhatsApp Business الخاص بك: يجب أن يكون مربوطًا (وإلا 403 WHATSAPP_NOT_CONNECTED)، ولا يُقبل النص الحر إلا خلال 24 ساعة من آخر رسالة للزبون (وإلا 400 OUT_OF_24H_WINDOW). خارج هذه النافذة أرسل قالبًا معتمدًا. ولا يُخصم شيء عندما ترفض الواجهة.

'template' => ['name' => 'order_shipped', 'language' => 'fr', 'variables' => ['89240']]
'cascade' => true: انتقال تلقائي إلى SMS إذا لم يكن للرقم واتساب

رموز OTP والويب هوك

تعيد ‎$client->sendOtp(['to' => …, 'brand' => 'MonBusiness', 'code_length' => 6, 'expiry' => 600])‎ معرّف session_id؛ وتعيد ‎$client->checkOtp($sessionId, $code)‎ الحقل verified. وتقرأ getOtpSession() حالة الجلسة دون استهلاك محاولة. ولويب هوك حالة التسليم، تتحقق ‎Client::verifyWebhookSignature($rawBody, $signature, $secret)‎ من الترويسة X-EnvoiSMS-Signature على جسم الطلب الخام.

'channel' => 'whatsapp' في sendOtp(): رمز عبر واتساب من المرسل المشترك، دون ربط
getBalance() وlistPacks() وcreateTopup() لإدارة الحساب
createOptout($phone) لتسجيل طلب STOP

أسئلة شائعة

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

كيف أتحقق من ويب هوك حالة التسليم بلغة PHP؟

اقرأ الجسم الخام عبر file_get_contents('php://input') — لا المصفوفة المفككة — ومرّره إلى Client::verifyWebhookSignature() مع الترويسة X-EnvoiSMS-Signature وسرّ الويب هوك. لا تعالج التسليم إلا إذا نجح التحقق.

هل يمكن استعمال المكتبة مع Laravel؟

نعم، مباشرة، أو عبر حزمة envoisms/laravel-otp المبنية عليها والتي تضيف قناة إشعارات وواجهة Laravel.

ماذا يحدث إذا أرسل برنامجي رسالة SMS نفسها مرتين؟

لا شيء إضافي: مع مفتاح Idempotency-Key نفسه تعيد الواجهة الرد الأصلي دون إرسال الرسالة أو فوترتها من جديد. يبقى المفتاح صالحًا 24 ساعة.

ابدأ التكامل مع مكتبة PHP الآن

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

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