وثائق Amargi Reach

نظرة عامّة

Amargi Reach هو منصّة رسائل متعدّدة القنوات مبنيّة على WhatsApp Business Cloud API (Amargi هي مزوّد تقنيّ معتمد لدى Meta)، بالإضافة إلى Facebook Messenger، Instagram Direct، والبريد الإلكترونيّ. يستخدمه الفِرَق لـ:

• إرسال رسائل المعاملات (OTPs، إيصالات، تنبيهات الشحن) عبر WhatsApp.
• تشغيل حملات تسويقيّة لجماهير مُجزَّأة.
• دعم العملاء عبر صندوق وارد المشغّل (للوكلاء البشريّين).
• الردود التلقائيّة (out-of-office، الترحيب، الكلمات المفتاحيّة).
• تكامل الويب-هوكس بحيث تستهلك أنظمتك أحداث الرسائل الواردة + تغييرات حالة التسليم.

بدء سريع

1. سجِّل في Amargi Hub (راجع وثائق Hub). افتح Reach من المُشغِّل.
2. تواصل WABA الخاصّ بك عبر Meta Embedded Signup: Settings → Channels → WhatsApp → Connect. الحوار يعالج كلّ شيء (مصادقة Facebook، اختيار البورتفوليو، اختيار رقم الهاتف، إنشاء مستخدم النظام).
3. أرسل أوّل رسالة من Send. لرسائل WhatsApp خارج نافذة الخدمة 24 ساعة، يجب أن تستخدم قالباً مُعتمداً (UTILITY / AUTHENTICATION / MARKETING).
4. أنشئ ويب-هوك في Webhooks → New subscription. تتلقّى أحداث message.inbound، message.status_changed، contact.opted_out على عنوان URL الخاصّ بك، موقَّعة بـ HMAC-SHA256.
5. افتح صندوق الوارد في Conversations. الرسائل الواردة تظهر في الوقت الفعليّ عبر SignalR.

مفاهيم رئيسيّة

WABA، رقم الهاتف، القالب

حساب WhatsApp Business (WABA) هو الكيان الذي يملك واحداً أو أكثر من أرقام الهواتف. كلّ رقم هاتف يحمل تقييم جودة (GREEN / YELLOW / RED) وطبقة رسائل (TIER_250 / TIER_1K / TIER_10K / TIER_100K / TIER_UNLIMITED) — هذه يديرها Meta بناءً على ملاحظات المستخدم. تستخدم القوالب لأيّ رسالة خارج نافذة الخدمة 24 ساعة (راجع أدناه). كلّ قالب يجب أن يُعتمَد من Meta قبل أن يكون قابلاً للاستخدام (UTILITY عادة موافقة في الدقيقة، MARKETING يستغرق ~30 دقيقة).

نافذة الخدمة 24 ساعة (CSW)

سياسة Meta: بعد أن يُرسل المستخدم رسالة لـ WABA الخاصّ بك، يحقّ لك إرسال أيّ نوع من الرسائل (نصّ حرّ، وسائط، إلخ.) لمدّة 24 ساعة بدون رسوم لكلّ رسالة. بعد إغلاق هذه النافذة، يجب أن تستخدم قالباً مُعتمَداً، ويتمّ تحصيل سعر القالب لكلّ منطقة. يفرض Reach هذا تلقائياً، الرسائل خارج CSW بدون قالب تُرفَض على API.

فئات القوالب

• UTILITY — إشعارات معاملاتيّة (تأكيد طلب، تحديث شحن، تذكير بموعد). الأرخص.
• AUTHENTICATION — OTPs ورموز التحقّق. مُسعَّرة بشكل منفصل، مُحسَّنة للتسليم السريع.
• MARKETING — العروض، الحملات، إعادة الاستهداف. الأغلى؛ تتطلّب موافقة المُستلِم الصريحة (opt-in).

الموافقة والاشتراك

يفرض Reach اكتشاف الكلمات المفتاحيّة STOP/UNSUBSCRIBE تلقائياً على الرسائل الواردة بأكثر من 30 لغة (إنجليزيّة، عربيّة، إسبانيّة، برتغاليّة، ألمانيّة، فرنسيّة، إندونيسيّة، إلخ.). عندما يُرسل المستخدم STOP، تُضاف عضويّته في جهة الاتصال إلى سجلّ الموافقة كـ opt_out وتُحظَر الرسائل التسويقيّة (MARKETING) المستقبليّة إليه على API. رسائل UTILITY و AUTHENTICATION لا تزال مسموحة (Meta + معظم اللوائح تسمح بها على أساس "المعاملات الضروريّة").

حدود السرعة + إعادة المحاولة 429

لكلّ رقم هاتف نافذة منزلقة تفرضها Reach (افتراضي: 80 رسالة/ثانية لـ TIER_1K، يتدرّج مع الطبقة). الردود 429 من Meta تُعاد محاولتها تلقائياً مع backoff تَنازليّ (يحترم رأس Retry-After، يعود إلى أسّيّ مع ±20٪ jitter).

مهامّ شائعة

إنشاء قالب

1. Templates → New template
2. اختر اللغة، الفئة (UTILITY/MARKETING/AUTHENTICATION)، ابنِ المكوِّنات (header، body، buttons).
3. يُحقّق Reach من المكوِّنات محلياً قبل الإرسال إلى Meta لتجنّب رفض على نقطة API الخاصّة بهم.
4. اضغط إرسال. الحالة تنتقل: PENDING → APPROVED / REJECTED. تظهر تحديثات الحالة عبر ويب-هوك Meta والتي تُحلّل في الوقت الفعليّ.

تشغيل حملة

1. حدِّد جمهوراً في Audiences (تجزئة استناداً إلى صفات جهة الاتصال أو رفع ملف CSV).
2. أنشئ حملة في Campaigns → New campaign. اربط قالباً + جمهوراً.
3. جدوِل (schedule_at مستقبليّ) أو أطلق فوراً (/start).
4. راقب التقدّم في صفحة الحملة (queued / sent / delivered / read / failed).

إعداد ويب-هوك

1. Webhooks → New subscription
2. أدخل عنوان URL الخاصّ بك (HTTPS فقط)، اختر أنواع الأحداث.
3. يُولِّد Reach سرّاً للتوقيع. انسخه إلى تكوين خادم الـ webhook الخاصّ بك.
4. تحقّق من رأس X-Reach-Signature على كلّ طلب وارد بـ HMAC-SHA256 من نَصّ الحمولة.
5. أعِد 2xx ضمن 5 ثوانٍ. عدم القيام بذلك يضع الحدث في طابور إعادة المحاولة (backoff أسّيّ، أقصى 5 محاولات).

الردّ من صندوق الوارد

1. Conversations — يفتح صندوق الوارد. رسائل WhatsApp + Email + Messenger + Instagram تظهر بفلاتر القناة في الأعلى.
2. اختر محادثة. اكتب الردّ في المُؤلِّف.
3. إن كانت داخل CSW: الإرسال مباشر. خارجه: اختر قالباً معتمداً.
4. حالة التسليم (sent → delivered → read) تتدفّق إلى الفقّاعة في الوقت الفعليّ.

مرجع API

كلّ نقاط نهاية Reach تحت https://reach.amargicreative.com/api/v1/. يجب أن تحمل الطلبات إمّا كوكي amargi_hub_access (للمتصفّحات) أو رأس Authorization: Bearer <api_key>.

• POST /api/v1/messages — إرسال رسالة. مفتاح idempotency في رأس Idempotency-Key.
• GET /api/v1/messages/:id — استرجاع رسالة بـ id.
• GET /api/v1/conversations — سرد المحادثات. تصفية حسب state، channel_kind، assigned_user_id.
• GET /api/v1/conversations/:id/messages — الرسائل في محادثة.
• GET /api/v1/wabas — سرد WABAs المرئيّة.
• GET /api/v1/wabas/:id/templates — القوالب لـ WABA معيَّن.
• POST /api/v1/wabas/:id/templates — إرسال قالب جديد للموافقة من Meta.
• GET /api/v1/campaigns — سرد الحملات.
• POST /api/v1/campaigns — إنشاء حملة (draft أو scheduled).
• POST /api/v1/campaigns/:id/start — إطلاق الحملة فوراً.
• GET /api/v1/webhook-subscriptions — سرد اشتراكات webhook.
• POST /api/v1/webhook-subscriptions — إنشاء اشتراك webhook جديد.
• POST /api/v1/contacts/:id/consents — تسجيل تحديث الموافقة يدوياً.
• GET /api/v1/reports/messaging — تقرير حجم الرسائل (group_by=day|week).
• GET /api/v1/reports/billing — تقرير تكلفة الفوترة (group_by=day|category).

أحداث الويب-هوكس

كلّ الأحداث الصادرة موقَّعة بـ HMAC-SHA256، السرّ يدور لكلّ اشتراك (يُمكنك تدويره يدوياً في أيّ وقت). أنواع الأحداث:

• message.inbound — وصلت رسالة من المستخدم النهائيّ.
• message.status_changed — sent → delivered → read → failed.
• conversation.assigned — تمّ تعيين محادثة لمشغّل.
• conversation.status_changed — open → pending → resolved → snoozed.
• contact.opted_out — أرسل المستخدم STOP أو UNSUBSCRIBE.
• template.status_changed — PENDING → APPROVED / REJECTED.
• phone_number.quality_changed — GREEN / YELLOW / RED + تغيير الطبقة.
• campaign.completed — انتهت حملة.

حزم SDK

• TypeScript / Node.js — @amargi/reach — العميل الرسميّ. مُتاح على npm.
• Python — مُخطَّط لـ Q3 2026.
• .NET — مُخطَّط لـ Q3 2026.

الحصول على المساعدة

• دعم البريد الإلكترونيّ: contact@amargicreative.com
• موقف الخصوصيّة (موقف Reach الخاصّ بـ BSP): موقف الخصوصيّة.
• المُعالِجون الفرعيّون (Meta، 360dialog، إلخ.): المُعالِجون الفرعيّون.