واجهة المطوّرين: أرسل WhatsApp من نظامك

واجهة المطوّرين (API) تتيح لبرنامجك الخاص، مثل متجرك الإلكتروني أو نظام إدارة العملاء أو نظام الحجوزات، أن يرسل رسائل WhatsApp عبر الرقم الذي ربطته بـ Agentech، وتخبر خادمك عندما يراسلك عميل أو عندما تُسلَّم رسالة أرسلتها أو تُقرأ أو يفشل إرسالها. هي موجهة لمطوّرك: تحتاج شخصًا يستطيع إرسال طلبات HTTPS وتشغيل خادم ويب. لا تحتاجها لاستخدام Agentech، فلوحة التحكم تفعل كل ما تفعله الواجهة.

كل شيء يُضبط من صفحة واجهة المطوّرين في لوحة التحكم.

من يفعل ماذا

ما تحتاجه أولًا

• WhatsApp متصل: راجع ربط WhatsApp.
• رسائل API في حسابك. هي التي تفتح الواجهة وتتيح لك إنشاء مفتاح سري. وبدونها، يُرفض إنشاء المفتاح برسالة "تحتاج مفاتيح الـ API إلى رسائل API ضمن باقتك. تواصل معنا لإضافتها." رسائل الحملات لا تفتح الواجهة: هما رصيدان منفصلان.
• لرسائل القوالب: قالب معتمد واحد على الأقل (راجع قوالب WhatsApp).

كل ما يرسله نظامك عبر الواجهة يستهلك رسائل API، ويُحتسب حسب فئة Meta:

• القالب التسويقي يُحسب بـ 5.
• القالب الخدمي أو قالب التحقق (رمز التحقق) يُحسب بـ 1.
• الرسالة النصية الحرة (خدمة العملاء) خلال نافذة الـ 24 ساعة تُحسب بـ 1.

إذن 1,000 من رسائل API تساوي 1,000 رمز تحقق أو تحديث طلب، أو 200 رسالة تسويقية، أو أي مزيج بينها. وإذا احتسبت Meta رسالة تحت فئة غير فئة قالبها، ينتقل الفرق داخل رسائل API نفسها (الرسالة التسويقية التي احتسبتها Meta خدمية تعيد إليك 4). والرسالة التي تقبلها Meta ثم تفشل تُعاد إليك. ورسوم Meta الخاصة على كل رسالة تُحتسب على حساب واتساب للأعمال الخاص بك، بمعزل عن هذا. رسائل API لا تستعير أبدًا من رسائل الحملات، ولا العكس، وكلاهما يظهر في صفحة الاستخدام.

أعلى الصفحة

• أي رقم: اختيار الرقم في الأعلى (يظهر حتى مع رقم واحد) يحدد الرقم الذي يعرضه سجل الرسائل والذي يرسل منه إرسال تجريبي. نظامك يحدد الرقم بـ numberId، أما المفاتيح السرية والويب هوك فتتبع مساحة العمل كلها، وليس رقمًا واحدًا.
• "لا يوجد رقم واتساب متصل." تظهر عندما لا يكون هناك رقم متصل. الحل: اربط رقمًا من واتساب ← الاتصال. وحتى ذلك الحين يبقى إرسال تجريبي معطلًا ويُرفض كل إرسال عبر الواجهة.
• رسائل API: عدّاد في الأعلى، "رسائل API: استُخدمت 4,120 من 5,000"، وتحته القاعدة: "الرسالة التسويقية تُحسب بـ 5، والخدمية ورسالة التحقق ورسالة خدمة العملاء بـ 1. تُحتسب رسوم Meta الخاصة على حساب واتساب للأعمال الخاص بك."
• رصيد على وشك النفاد، أو نفد، أو سينتهي قريبًا: تنبيه في الأعلى يذكر الرصيد ("تبقّى 150 فقط من رسائل API. اشحن رصيدك قبل أن تنفد."، "نفدت … لهذا الشهر…"، "تنتهي … خلال 3 أيام.") مع زر اشحن الرصيد أو جدّد يفتح الدعم ← تواصل معنا.
• بدون رسائل API تقول الصفحة "ترسل واجهة المطورين (API) من رسائل API: كل ما يرسله نظامك. بدونها في باقتك، لا يمكنك إنشاء مفاتيح أو الإرسال."، مع زر اطلب الوصول، ويكون إنشاء المفاتيح والإرسال التجريبي معطلين.

المفاتيح السرية

في واجهة المطوّرين ← المفاتيح السرية، اضغط أنشئ مفتاحًا وأعطه اسمًا (مثلًا "المتجر"). المفتاح الكامل، الذي يبدأ بـ sk_، يظهر مرة واحدة فقط، فانسخه عندها. بعد ذلك لا تعرض الصفحة إلا أحرفه الأولى، ومتى أُنشئ، ومتى استُخدم آخر مرة.

• حافظ على سريته. أي شخص يملك المفتاح يستطيع إرسال رسائل WhatsApp من رقمك. لا تضعه أبدًا في صفحة موقع أو تطبيق جوال، بل على خادمك فقط.
• هذا ليس مفتاح أداة الدردشة الموجود في صفحة مفاتيح API. مفتاح الأداة عام بطبيعته ولا يستطيع إرسال WhatsApp، والمفتاح السري لا يستطيع تشغيل الأداة.
• اضغط إلغاء على المفتاح فور أن تشك في أنه تسرّب. يتوقف عن العمل فورًا، وأنشئ مفتاحًا جديدًا لمطوّرك.

إرسال رسالة

كل طلب يرسل المفتاح في ترويسة Authorization:

Authorization: Bearer sk_your_key

العنوان الأساسي: https://api.assistant.agentech.tech.

رسالة قالب (في أي وقت)

POST /api/v1/whatsapp/messages
{
  "to": "+201001234567",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": "en_US",
    "variables": { "1": "Sara", "2": "#1042" }
  }
}

• name وlanguage يجب أن يكونا تمامًا كما يعرضهما GET /api/v1/whatsapp/templates (مثلًا en_US، وليس en).
• variables تملأ {{1}} و{{2}}… في القالب بالترتيب، وهي نفس الفراغات التي في جدول مستلمي الحملة.
• القالب الذي له ترويسة نصية يأخذ "header": { "text": "…" }، والقالب الذي له ترويسة صورة أو فيديو أو مستند يأخذ "header": { "mediaUrl": "https://…" }.
• الزر الذي يحتاج قيمة (مثلًا رابط ينتهي برمز تتبع) يأخذ "buttons": { "0": "track/1042" }، مرتبًا بموضع الزر بدءًا من 0.

رسالة نصية حرة (خلال 24 ساعة فقط)

POST /api/v1/whatsapp/messages
{ "to": "+201001234567", "type": "text", "text": { "body": "Your order has shipped." } }

WhatsApp لا يسمح بالنص الحر إلا خلال 24 ساعة من آخر رسالة أرسلها إليك العميل. خارج هذه النافذة، أرسل قالبًا. الرسالة النصية الحرة المرسلة عبر الواجهة تظهر أيضًا في محادثة ذلك العميل في صندوق الوارد، حتى يراها فريقك. ولا توقف مساعدك.

أي رقم يرسل

إذا كان لديك رقم WhatsApp واحد، لا تحتاج إلى تحديده. وإذا كان لديك أكثر من رقم، أضف "numberId"، والقائمة تأتي من GET /api/v1/whatsapp/numbers. يجب أن يكون القالب تابعًا لحساب WhatsApp للأعمال الخاص بذلك الرقم.

ما يعود إليك

201 { "id": 881, "wamid": "wamid.HBg…", "status": "sent", "to": "+201001234567" }

"sent" تعني أن Meta قبلتها، لا أنها وصلت. تابعها بـ GET /api/v1/whatsapp/messages/881، أو انتظر حدث message.status على الويب هوك.

استدعاءات أخرى

تسمح الواجهة بـ 60 طلبًا في الدقيقة لكل مفتاح كحد أقصى، الإرسال والاستعلام معًا.

إرسال نفس الرسالة مرتين بالخطأ

أضف ترويسة Idempotency-Key (أي نص فريد حتى 255 حرفًا، مثلًا رقم طلبك) إلى POST /api/v1/whatsapp/messages. إذا أعاد نظامك نفس الطلب بنفس المفتاح خلال 24 ساعة، تحصل على رد الرسالة الأولى: لا يُرسل شيء مرة أخرى ولا يُحتسب شيء مرة أخرى. وإعادة استخدام المفتاح مع طلب مختلف تُرفض بـ idempotency_key_reused.

سجل الرسائل

تعرض صفحة واجهة المطوّرين سجل الرسائل: الرسائل المرسلة عبر الواجهة والرسائل التي أرسلها عملاؤك إلى أرقامك، مع الوقت، والاتجاه، والرقم، وهاتف العميل، والقالب أو النص، والحالة (وسبب Meta إذا فشلت رسالة). صفِّ حسب الرقم (إذا كان لديك رقمان أو أكثر)، والاتجاه، والحالة، والتواريخ. "يُحتفظ بآخر 90 يومًا فقط، وأكواد التحقق داخل قوالب المصادقة تكون مخفية دائمًا."

الإرسال التجريبي

مربع إرسال تجريبي في نفس الصفحة يرسل رسالة واحدة عبر الواجهة من لوحة التحكم، دون كتابة أي كود: اختر الرقم (إذا كان لديك رقمان أو أكثر)، واكتب رقم هاتف، ثم اكتب نصًا حرًا أو اختر قالبًا معتمدًا واملأ متغيراته. يستهلك من رسائل API مثل أي إرسال آخر. الرسائل التي قد يعرضها:

"لم يراسلك هذا العميل على رقم واتساب خلال آخر 24 ساعة، لذا لا يمكن إرسال رسالة نصية مباشرة. اطلب منه مراسلتك أولًا، أو أرسل قالبًا معتمدًا بدلًا من ذلك."

الحل: راسل رقم WhatsApp الخاص بك من ذلك الهاتف أولًا، ثم حاول مرة أخرى، أو استخدم قالبًا.

"يحتاج هذا إلى رسائل API ضمن باقتك. تواصل معنا لإضافتها."

الحل: في صفحة الاستخدام، اضغط اطلب الوصول بجانب رسائل API، أو راسلنا بالبريد.

"لقد استهلكت رسائل API لهذا الشهر. تواصل معنا لإعادة التعبئة."

الحل: اشحن رصيدك، أو انتظر رصيد الشهر القادم. القالب التسويقي يحتاج 5 متبقية، والخدمي أو قالب التحقق أو الرسالة الحرة 1.

"تعذّر إرسال الرسالة ([code])."

الحل: ابحث عن الرمز تحت الأخطاء بالأسفل.

الويب هوك: استقبال الأحداث

في واجهة المطوّرين ← الويب هوك (Webhook)، أدخل رابط https على خادمك، وفعّل الإرسال واحفظ. بعدها نرسل إليه:

كل حدث طلب POST بمحتوى JSON:

{ "id": "3f1c…", "type": "message.received", "createdAt": "2026-09-24T10:15:00Z",
  "data": { "numberId": 12, "from": "+201001234567", "wamid": "wamid…",
            "messageType": "text", "text": "Is it in stock?", "timestamp": "…",
            "userId": "EG.2123983504836150",
            "customer": { "name": "Ahmed Hassan", "username": null } } }

messageType هو نوع WhatsApp نفسه (text أو image أو audio أو video أو document أو sticker)، وtext لا يُملأ إلا لرسالة من نوع text. المواقع وبطاقات جهات الاتصال والتفاعلات وردود الأزرار لا تُرسل بعد. وcustomer.name هو الاسم الذي وضعه العميل في WhatsApp كما كتبه، ويكون null إذا لم يرسل WhatsApp اسمًا.

قد يكون from بقيمة null. يتيح WhatsApp للأشخاص استخدام اسم مستخدم بدلًا من إظهار أرقامهم. عندما يكتب لك عميل كهذا لأول مرة، لا يعطينا WhatsApp رقمه: يكون from بقيمة null، ويُملأ userId (معرّف WhatsApp الخاص بهذا العميل، وهو نفسه في كل مرة يكتب لك)، ويكون customer.username اسم المستخدم @ الخاص به على WhatsApp. إذا كان نظامك يميّز العملاء بـ from، فميّزهم بـ userId عندما يكون from بقيمة null. أما العملاء الذين كتبوا لك من قبل فيصلون برقمهم كالمعتاد.

بيانات message.status: id (معرّف الرسالة في الواجهة)، وwamid، وto، وstatus، وerrorCode، وerrorTitle.

تحقق من التوقيع. كل حدث يحمل X-Agentech-Signature: t=1727172900,v1=5e8f…. احسب HMAC-SHA256 للنص "<t>.<raw body>" باستخدام مفتاح التوقيع الظاهر في الصفحة، وقارنه بـ v1. ارفض الأحداث التي لا تتطابق أو التي مضى على t فيها أكثر من 5 دقائق. اضغط تغيير لتغيير المفتاح إذا تسرّب، والمفتاح القديم يتوقف عن العمل فورًا.

رد بأي 2xx بسرعة. أي رد آخر، أو عدم الرد خلال 10 ثوانٍ، تُعاد محاولته بعد دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين، ثم 6 ساعات، ثم يُعلَّم فشل. تعرض الصفحة آخر عمليات الإرسال مع الحالة التي أعادها خادمك. وقد يصل نفس الحدث مرتين، فاستخدم id الخاص به لتجاهل التكرار.

الأخطاء

كل خطأ يعود بالشكل { "error": { "code": "…", "message": "…" } }. يجب أن يعتمد مطوّرك على code، أما message فتلميح بالإنجليزية.

unauthorized

المفتاح غير موجود، أو مكتوب خطأ، أو ملغى، أو هو مفتاح أداة الدردشة. الحل: أرسل Authorization: Bearer sk_… مع مفتاح سري فعّال من واجهة المطوّرين.

module_not_active

حسابك لا يملك رسائل API، أو انتهت. كل إرسال عبر الواجهة يستهلكها، أيًّا كانت فئة القالب. الحل: في صفحة الاستخدام، اضغط اطلب الوصول بجانب رسائل API، أو راسلنا بالبريد.

quota_exhausted

نفدت رسائل API لهذا الشهر، ومعها أي شحن إضافي (القالب التسويقي يحتاج 5 متبقية، وأي رسالة أخرى 1). ولا تستعير أبدًا من رسائل الحملات. الحل: شحن إضافي أو رصيد الشهر القادم. راجع الاستخدام والباقات.

window_closed

رسالة نصية حرة إلى عميل آخر رسالة منه كانت قبل أكثر من 24 ساعة (أو لم يراسلك أبدًا). يتضمن الرد وقت إغلاق النافذة. الحل: أرسل قالبًا بدلًا منها.

message_not_found

لم تُرسل أي رسالة بهذا id عبر الواجهة من حسابك. الحل: استخدم id الموجود في رد الإرسال.

number_required

لديك أكثر من رقم WhatsApp ولم تحدد أيها. الحل: أضف numberId.

number_not_found / number_disconnected

numberId هذا ليس من أرقامك، أو أنه غير متصل. الحل: راجع GET /api/v1/whatsapp/numbers، وأعد ربط الرقم من صفحة القنوات إذا انقطع.

template_not_found / template_not_approved

لا يوجد قالب بهذا الاسم وهذه اللغة على ذلك الرقم، أو لم تعتمده Meta (أو أوقفته). الحل: راجع GET /api/v1/whatsapp/templates، أو صفحة القوالب واضغط زامن من Meta.

template_variables_mismatch

المتغيرات أو قيم الترويسة أو الأزرار لا تطابق القالب. الحل: أرسل متغيرات القالب بالضبط، مرقمة بدءًا من "1".

idempotency_key_reused

قيمة Idempotency-Key التي أرسلتها استُخدمت خلال آخر 24 ساعة مع طلب مختلف. الحل: استخدم مفتاحًا جديدًا لكل رسالة جديدة.

validation_failed

شيء في الطلب ناقص أو بصيغة خاطئة، وغالبًا to ليس بالصيغة الدولية (+ ورمز الدولة). الحل: message يذكر الحقل المقصود.

rate_limited

أكثر من 60 طلبًا في دقيقة واحدة على مفتاح واحد (الاستعلام عن حالة رسالة يُحتسب أيضًا). الحل: خفّف السرعة وأعد المحاولة بعد دقيقة.

meta_rejected

رفضت Meta الرسالة. يتضمن الخطأ metaCode وmetaTitle الخاصين بـ Meta. الأكثر شيوعًا منها معناها نفس معناها في الحملات. راجع لماذا فشل إرسال مستلم؟. لا تُحاسب على رسالة رفضتها Meta، ورسالة القالب التي تقبلها Meta ثم تفشل يُعاد رصيدها تلقائيًا.

الويب هوك يعرض "فشل"

خادمك لم يرد بـ 2xx خلال 10 ثوانٍ، في خمس محاولات متتالية. الحل: راجع حالة HTTP الظاهرة على عملية الإرسال، وتأكد أن الرابط يمكن الوصول إليه من الإنترنت عبر https، ثم اضغط أرسل حدثًا تجريبيًا. الأحداث التي فشلت بالفعل لا يُعاد إرسالها.

متى تراسلنا

إذا لم يوضح أي رمز أعلاه ما تراه، راسلنا على admin@agentech.tech أو استخدم الدعم ← تواصل معنا في لوحة التحكم. اذكر id الرسالة أو وقت الطلب، والرقم الذي أرسلت إليه، ونص الخطأ كاملًا. لا ترسل لنا مفتاحك السري أبدًا، فنحن لا نحتاجه.