تسجيل موافقة واتساب

اعتماد القالب لا يعني موافقة العميل. على خادم الموقع تسجيل موافقة العميل الفعلية على رسائل واتساب قبل طلب رسالة الترحيب. استدعِ الواجهة فقط بعد اختيار العميل مربع الموافقة صراحةً؛ إذا لم يوافق، لا تسجّل موافقة ولا ترسل رسالة. احتفظ بمفتاح API على الخادم ولا تضعه في JavaScript المتصفح.

الصلاحيات والنطاق

أنشئ مفتاحاً من الإعدادات ← API بصلاحيتي whatsapp:consent:write وwhatsapp:send. أضف whatsapp:templates:read لعرض القوالب. المفاتيح الحالية لا تكتسب الصلاحية الجديدة تلقائياً. تسري الموافقة على رسائل واتساب من التاجر صاحب المفتاح عبر قنواته. لا ترسل merchant_id أو account_id أو phone_number_id إلى واجهة الموافقة.

1. سجّل الموافقة

Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json
Accept: application/json
Idempotency-Key: mehad-lead-123-consent

{
  "to": "+966500000001",
  "opted_in": true,
  "occurred_at": "2026-09-05T09:30:00+03:00",
  "evidence_reference": "mehad:lead:123",
  "consent_text": "أوافق على تلقي رسائل واتساب من مهاد، ويمكنني إلغاء الاشتراك في أي وقت.",
  "source_url": "https://mehad.example/lead"
}

الحقول الستة مطلوبة. استبدل المثال برقم العميل ووقت موافقته الأصلي والنص الذي وافق عليه حرفياً ورابط النموذج الفعلي ومرجع فريد لإرسال النموذج. احتفظ بالإرسال الأصلي في نظامك. يحفظ نبّه الدليل مشفّراً ويضيف حدث موافقة إلى سجل سياسات المستلمين؛ لا ينشئ هذا الطلب محادثة ولا يرسل رسالة.

• to: رقم دولي من 8 إلى 15 رقماً، مع علامة + اختيارية؛ لا تُقبل الأرقام المحلية.
• opted_in: القيمة المنطقية true في JSON فقط؛ تُرفض false والنصوص والأرقام.
• occurred_at: وقت ISO 8601 بدقة الثواني مع المنطقة الزمنية كما في المثال أو +00:00. لا يجوز أن يكون مستقبلياً ولا تغيّره عند إعادة المحاولة.
• evidence_reference: من 1 إلى 191 محرفاً، يبدأ بحرف لاتيني أو رقم ويحتوي فقط على أحرف لاتينية وأرقام وشرطة سفلية ونقطة ونقطتين وشرطة. فريد لكل تاجر ولا يتضمن بيانات العميل.
• consent_text: النص الذي وافق عليه العميل حرفياً، من 1 إلى 4096 محرفاً.
• source_url: رابط النموذج ببروتوكول HTTP أو HTTPS، حتى 2048 محرفاً، دون بيانات حساسة في معاملات الرابط.
• Idempotency-Key: ترويسة مطلوبة من 8 إلى 255 محرفاً. احتفظ بمعرّف ثابت لكل إرسال للنموذج.

{
  "data": {
    "consent_event_id": 123,
    "created": true,
    "has_consent": true,
    "consent_revoked": false,
    "suppressed": false
  }
}

2. اطلب رسالة الترحيب

تابع فقط بعد نجاح تسجيل الموافقة وعودة has_consent بقيمة true وconsent_revoked وsuppressed بقيمة false. وفق إعدادات مهاد المذكورة، استخدم الحساب 9 والقالب 9 (orderas بالعربية). يستخرج نبّه اسم القالب ولغته من معرّفه. يفترض المثال عدم وجود متغيرات في نص القالب؛ أضف parameters بترتيب متغيرات القالب المعتمد عند الحاجة. إذا كان للحساب أكثر من رقم إرسال، حدّد phone_number_id صراحةً.

Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json
Accept: application/json
Idempotency-Key: mehad-lead-123-welcome

{
  "account_id": 9,
  "to": "+966500000001",
  "template_id": 9,
  "parameters": []
}

تعني HTTP 202 أن الرسالة في قائمة الإرسال، ولا تعني تسليمها. تعيد المحاولة المطابقة HTTP 200 وmessage_id نفسه مع created بقيمة false. تابع الحالة عبر GET /api/v1/whatsapp/messages/{message_id} بصلاحية الإرسال. تبقى فحوص اعتماد القالب وجاهزية الحساب وسياسة المستلم سارية عند الإرسال.

إعادة المحاولة وإلغاء الاشتراك والأخطاء

استخدم معرّفين ثابتين منفصلين للموافقة والترحيب. إذا فقدت الاستجابة، أعد الطلب نفسه بالمعرّف والبيانات نفسيهما؛ لا تنشئ وقت موافقة جديداً أو معرّف ترحيب جديداً. الطلبان منفصلان: إذا نجحت الموافقة وفشل الإرسال، أعد محاولة الإرسال. تُنفّذ طلبات الموافقة المتزامنة بالتتابع مع تحديثات السجل، وتمنع قيود قاعدة البيانات تكرار التسجيل.

تعيد محاولة الموافقة المطابقة معرّف الحدث الأصلي وحالة الموافقة والحظر الحالية. لا تمنح الموافقة مجدداً حتى بعد رسالة «إيقاف». لا يتجاوز طلب جديد سحب موافقة أو حظراً قائماً، حتى بوقت موافقة أحدث؛ تُراجع هذه الحالات عبر آلية مراجعة الموافقة الحالية لدى التاجر. لا تتيح هذه الواجهة إزالة الحظر. قد يمنع إلغاء الاشتراك أو الحظر اللاحق إرسال الرسالة، حتى بعد وضعها في قائمة الإرسال.

• 401: مفتاح مفقود أو غير صالح. 403: صلاحية مفقودة أو تاجر غير متاح. 404: الوصول إلى API معطّل.
• 422: دليل مفقود أو غير صالح أو موافقة ليست true. الرمز idempotency_key_required يعني ترويسة مفقودة أو غير صالحة.
• 409 idempotency_conflict: استخدام معرّف الموافقة نفسه مع دليل مختلف.
• 409 consent_evidence_conflict: مرجع الإرسال مسجّل بمعرّف آخر؛ استخدم المعرّف والبيانات الأصليين.
• 422 recipient_consent_revoked أو recipient_suppressed: رُفض التسجيل بسبب سحب موافقة أو حظر قائم.
• تبقى أخطاء الإرسال كما هي، ومنها 422 idempotency_conflict. لا تتجاوز إرسالاً مرفوضاً أو مجهول النتيجة بإنشاء معرّف ترحيب جديد.