نقطة نهاية واحدة للرسائل القصيرة وواتساب
هل ترسل رسائل SMS بالفعل؟ واتساب هو الطلب نفسه مع حقل إضافي: POST https://api.envoisms.ma/v1/messages، والترويسة Authorization: Bearer <مفتاح API>، وchannel: "whatsapp". تخرج الرسالة من رقم WhatsApp Business الخاص بك، المربوط في لوحة التحكم. وبدون رقم مربوط، تجيب الواجهة 403 WHATSAPP_NOT_CONNECTED ولا يُخصم شيء.
- معامل channel نفسه في المكتبات الرسمية Node.js وPHP وPython وGo
- ترويسة Idempotency-Key تجعل كل إرسال قابلًا للإعادة: إعادة المحاولة بعد انتهاء المهلة لا تُفوتر مرتين أبدًا
- أخطاء JSON برمز ثابت (error.code) تبني عليه منطقك
قوالب Meta ونافذة 24 ساعة
يمكن لقالب معتمد من Meta أن يفتح محادثة في أي وقت: فهو معفى من نافذة الخدمة ويُسعَّر حسب الفئة المسجلة في حسابك. أما الرسالة الحرة (نص، وسائط، قائمة…) فلا تُقبل إلا إذا راسلك جهة الاتصال على واتساب خلال الـ24 ساعة الأخيرة؛ وإلا تجيب الواجهة 400 OUT_OF_24H_WINDOW قبل أي خصم.
- template: { name, language, components } لبدء محادثة
- يحمل الرد 400 OUT_OF_24H_WINDOW الحقلين window_expired وwindow_expires_at
- التفاعلات (Reactions) غير مُفوترة
رسائل غنية: وسائط وقوائم وأزرار
تنقل نقطة النهاية نفسها كل أنواع رسائل واتساب: النص، والوسائط بالمعرّف أو بالرابط، والرسائل التفاعلية (قائمة، أزرار، flow، زر رابط، طلب موقع)، والتفاعلات، وبطاقات جهات الاتصال، والمواقع والملصقات، مع سياق رد لاقتباس رسالة الزبون.
- interactive: list وbutton وflow وcta_url وlocation_request_message
- وسائط بالمعرّف (مرفوعة مسبقًا) أو بالرابط
- سياق رد على أي نوع من الرسائل
المحادثات والويب هوك ورموز OTP
تسرد GET /v1/conversations محادثاتك مع وقت انتهاء نافذة 24 ساعة لكل منها، وتعرض POST /v1/messages/typing مؤشر الكتابة بينما تُعدّ الرد. تصل حالات رسائلك إلى الويب هوك الخاصة بك موقّعة بـ HMAC-SHA256 في الترويسة X-EnvoiSMS-Signature-256. ولإرسال رمز لمرة واحدة عبر واتساب، تمر POST /v1/verify/send مع channel whatsapp عبر المرسل المشترك لـ EnvoiSMS: لا رقم يلزم ربطه.
- الأحداث message.sent وmessage.delivered وmessage.failed وmessage.undeliverable
- التوقيع t=<الطابع الزمني>,v1=<hex>: ارفض كل تسليم أقدم من 5 دقائق
- مفاتيح Sandbox من نوع env_test_: المسار كله محاكى، لا تسليم ولا خصم