الموقع فى النسخه التجربيه الان
واتساب API والربط البرمجي

مرجع WhatsApp API: كل الروابط والحقول وأكواد الأخطاء

فريق دعم سمارت ون جروبآخر تحديث: 9 دقائق قراءة

الإجابة المختصرة

WhatsApp API من سمارت ون جروب يعمل على الرابط https://sog.sog.eg/api/whatsapp، وكل طلب يحمل appkey وauthkey من تبويب «ربط API». تستخدم /send للنصوص والصور والملفات والقوالب، و/messages/{id} لمتابعة حالة الرسالة، إلى جانب روابط القوالب والجدولة والحملات والشات بوت والـ Webhook. كل رد بصيغة JSON، والأخطاء تحمل message وcode يحدد السبب.

في هذه الصفحة

ما أساسيات استخدام الـ API؟

  • الرابط الأساسي: https://sog.sog.eg/api/whatsapp.
  • التوثيق: أرسل appkey وauthkey مع كل طلب؛ في جسم الطلب لطلبات POST، وفي رابط الطلب لطلبات GET.
  • الصيغة: الطلبات JSON أو form، والرد JSON دائمًا. أضف الهيدر Accept: application/json ليرجع خطأ التحقق من الحقول بصيغة JSON.
  • الحد: حتى 60 طلبًا في الدقيقة من نفس عنوان IP، إضافة إلى أقل مدة بين الرسائل في باقتك.
الطلبالرابطالاستخدام
POST/create-messageإرسال نص فقط (أبسط طريقة)
POST/sendإرسال نص أو صورة أو ملف أو قالب
GET/messages/{id}حالة رسالة أرسلتها
GET / POST/templatesعرض القوالب أو إنشاء قالب
POST/contactsحفظ جهة اتصال وحالة موافقتها
POST/scheduleجدولة رسالة لوقت لاحق
POST/campaignsإنشاء حملة (مسودة)
POST/campaigns/{id}/start|pause|cancelتشغيل الحملة أو إيقافها أو إلغاؤها
POST/chatbot/rulesقاعدة رد تلقائي
GET/inboxآخر 100 رسالة واردة
POST/webhooksتسجيل رابط Webhook
POST/sandboxمفاتيح تجربة لا ترسل فعليًا

كيف أرسل نصًا أو صورة أو ملفًا أو قالبًا؟

استخدم POST /send. الحقل الوحيد المطلوب دائمًا هو to، والباقي حسب نوع الرسالة:

الحقلالوصف
toرقم المستلم بالصيغة الدولية مثل 201012345678 (الرقم المصري المحلي مقبول).
typetext (الافتراضي) أو image أو video أو audio أو voice أو document.
messageنص الرسالة، أو تعليق الملف. حتى 4096 حرفًا.
captionتعليق الملف إن لم ترسل message. حتى 1000 حرف.
media_urlرابط عام مباشر للملف (بدون تحويل redirect)، حتى 16 ميجابايت.
fileرفع الملف مباشرة بطلب multipart، حتى 32 ميجابايت.
template_idرقم قالب من قوالبك؛ نص القالب يصبح نص الرسالة.
variablesقيم متغيرات القالب، مثل {"name": "Ahmed"} لتعويض {name}. أسماء المتغيرات حروف إنجليزية صغيرة وأرقام و_.
هيدر Idempotency-Keyمفتاح فريد لكل رسالة (حتى 80 حرفًا). إذا أعدت الطلب بنفس المفتاح بعد نجاحه يرجع الرد نفسه دون إرسال الرسالة مرة ثانية.
curl -X POST https://sog.sog.eg/api/whatsapp/send \
  -H "Accept: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
  -d to=201012345678 \
  -d message="Your order #1042 is confirmed ✅"

الصور والملفات تحتاج ميزة إرسال الملفات في باقتك، والقوالب تحتاج ميزة القوالب.

كيف أعرف حالة رسالة أرسلتها؟

استخدم GET /messages/{id} حيث id هو data.id من رد الإرسال. القيم الممكنة للحقل status:

الحالةالمعنى
queuedالرسالة في الطريق للخروج من رقمك.
sentخرجت من رقمك واستلمها واتساب.
failedلم تُرسل؛ الحقل code يوضح السبب.
sandboxرسالة تجربة بمفاتيح Sandbox ولم تُرسل فعليًا.
curl -G https://sog.sog.eg/api/whatsapp/messages/4182 \
  -H "Accept: application/json" \
  --data-urlencode appkey=YOUR_API_KEY \
  --data-urlencode authkey=YOUR_SECRET_KEY

كيف أستخدم القوالب؟

القالب نص محفوظ فيه متغيرات بين أقواس مثل {name}. أنشئه مرة بـ POST /templates، ثم أرسله بـ template_id وvariables في /send. عدد القوالب حسب حد القوالب في باقتك.

curl -X POST https://sog.sog.eg/api/whatsapp/templates \
  -H "Accept: application/json" \
  -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
  -d name="Order confirmed" \
  -d body="Hi {name}, your order #{order_id} is confirmed."

# → 201 {"data":{"id":7,"name":"Order confirmed"}}

إذا ردّ أي مستلم بكلمة STOP أو إيقاف يُسجَّل رقمه تلقائيًا كرافض للرسائل، وأي إرسال له بعدها يرجع 403 بالكود opted_out. إذا عاد ووافق، سجّله من جديد بـ POST /contacts مع opted_in=1.

curl -X POST https://sog.sog.eg/api/whatsapp/contacts \
  -H "Accept: application/json" \
  -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
  -d phone=201012345678 -d name="Ahmed" -d opted_in=1

# → 200 {"data":{"phone":"201012345678","opted_in":true}}

كيف أجدول رسالة لوقت لاحق؟

أرسل POST /schedule بالحقول to وmessage وsend_at. اكتب الوقت بصيغة ISO 8601 ومعه فرق التوقيت مثل +02:00؛ الوقت بدون فرق توقيت يُفهم بتوقيت UTC. الرسائل المستحقة تُرسل كل دقيقة من أول تطبيق نشط عندك.

curl -X POST https://sog.sog.eg/api/whatsapp/schedule \
  -H "Accept: application/json" \
  -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
  -d to=201012345678 \
  -d message="Reminder: your appointment is tomorrow at 10:00" \
  --data-urlencode send_at=2026-11-20T09:00:00+02:00

# → 201 {"data":{"id":31,"send_at":"2026-11-20T07:00:00+00:00"}}

كيف أرسل حملة لعدد من العملاء؟

أنشئ الحملة بـ POST /campaigns (حتى 500 رقم في الطلب) فتُحفظ مسودة، ثم شغّلها بـ /campaigns/{id}/start. ترسل consent: true لتؤكد أن هذه الأرقام وافقت على رسائلك؛ بدونه تُتخطى الأرقام غير المسجلة كموافقة وتظهر في skipped.

الحملة تُرسل بالتدريج، رسالة كل دقيقة تقريبًا لكل حملة، وتتوقف أثناء الساعات الهادئة بين quiet_start وquiet_end (بتوقيت UTC). تتابع الحالة وتشغّل أو توقف الحملة أيضًا من تبويب الحملات في البوابة.

POST https://sog.sog.eg/api/whatsapp/campaigns
Accept: application/json
Content-Type: application/json

{
  "appkey": "YOUR_API_KEY",
  "authkey": "YOUR_SECRET_KEY",
  "name": "Black Friday",
  "body": "Black Friday: 30% off all plans until Sunday. Reply STOP to opt out.",
  "phones": ["201012345678", "201112345678"],
  "consent": true,
  "quiet_start": "20:00",
  "quiet_end": "07:00"
}

→ 201 {"data":{"id":12,"queued":2,"skipped":[]}}

كيف أضبط الردود التلقائية وأقرأ صندوق الوارد؟

القاعدة كلمة ورد: match=contains (الافتراضي) يرد إذا احتوت الرسالة على الكلمة، وmatch=exact يرد إذا طابقتها تمامًا. hands_off=1 يعلّم المحادثة بانتظار موظف في صندوق الوارد. القواعد تظهر أيضًا في تبويب الشات بوت، والرسائل الواردة في صندوق الوارد.

curl -X POST https://sog.sog.eg/api/whatsapp/chatbot/rules \
  -H "Accept: application/json" \
  -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
  -d keyword="price" -d match=contains \
  -d reply="Our plans start at 60 USD a year: https://sog.eg/pricing" \
  -d hands_off=0

ماذا تعني أكواد الأخطاء؟

كل خطأ يرجع message يشرحه، ومعه غالبًا code ثابت تبني عليه منطق تطبيقك:

HTTP`code`السبب والحل
401invalid_keysالمفاتيح خطأ أو أُعيد توليدها. انسخها من تبويب ربط API.
403subscription_inactiveاشتراك الباقة غير نشط أو منتهٍ. ادفع فاتورة التجديد.
403terms_requiredلم توافق على بنود ربط الرقم بعد.
403feature_disabledالميزة غير مشمولة في باقتك؛ الحقل feature يحدد أيها.
403quota_exceededوصلت لحد الرسائل أو القوالب أو الحملات أو التطبيقات؛ قد يحمل الرد upgrade بباقة مقترحة.
403device_limit / apps_limitعدد الأجهزة أو التطبيقات النشطة أكبر من حد الباقة.
403opted_outالمستلم طلب إيقاف الرسائل.
403client_frozen / sending_disabledالإرسال موقوف على حسابك أو مؤقتًا على المنصة. تواصل مع الدعم.
404not_foundالرسالة أو القالب أو الحملة غير موجودة في حسابك.
409device_offlineلا يوجد رقم بحالة متصل. أعد ربط الرقم.
422invalid_phone وغيرهاحقل ناقص أو غير صحيح؛ أخطاء التحقق تأتي في errors لكل حقل.
429rate_limitedأرسلت أسرع من أقل مدة بين الرسائل، أو تجاوزت 60 طلبًا في الدقيقة. انتظر وأعد المحاولة.
502engine_unavailableخلل مؤقت في الإرسال. أعد المحاولة بعد قليل بنفس Idempotency-Key.
{
  "message": "Message limit reached.",
  "code": "quota_exceeded",
  "upgrade": { "…": "suggested package" }
}

حسابي على منصة whatsapp.sog.eg القديمة، كيف أرسل؟

العملاء الحاليون على منصة whatsapp.sog.eg يبقون عليها حتى يُنقلوا تدريجيًا إلى البوابة، وروابطها مختلفة. استخدم مفتاح الحساب Auth Key ومفتاح التطبيق App Key من لوحة المنصة، وأرسل إلى https://whatsapp.sog.eg/api/create-message.

  • الحقول: authkey وappkey وto (أرقام فقط حتى 13 رقمًا) وmessage (حتى 1000 حرف)، أو template_id مع variables بأسماء المتغيرات كما في القالب مثل {name}.
  • الملفات: file رابط عام لملف jpg أو png أو webp أو pdf أو docx أو xlsx أو csv أو txt.
  • الحالة: POST /api/message-status بـ message_id ترجع pending أو sent أو delivered أو read أو error.
  • الـ Webhook: تضبط رابطه في إعدادات الجهاز، ويصلك خلال دقيقة تقريبًا بالحقول payload وsender وreceiver، ويُعد ناجحًا فقط إذا رد سيرفرك بـ 200.
curl -X POST https://whatsapp.sog.eg/api/create-message \
  -H "Accept: application/json" \
  -d authkey=YOUR_AUTH_KEY \
  -d appkey=YOUR_APP_KEY \
  -d to=201012345678 \
  -d message="Hello from Example Store" \
  -d file=https://example.com/files/menu.pdf

# → 200 {"message_status":"Success","data":{"from":"2010…","to":"201012345678",
#        "status_code":200,"message_id":"3EB0…"}}

أسئلة متكررة

روابط الـ API في البوابة ترسل لأرقام الأفراد فقط عبر الحقل to.

أرسل هيدر Idempotency-Key ثابت لكل رسالة، مثل رقم الطلب. إذا وصل الطلب مرتين ونجح الأول يرجع الرد نفسه ولا تُرسل نسخة ثانية.

في البوابة تتابع sent أو failed لكل رسالة من /messages/{id}، وتصلك رسالة message.sent عبر الـ Webhook. حالات التسليم والقراءة متاحة على منصة whatsapp.sog.eg القديمة فقط.

جاهز تبدأ؟

مرجع WhatsApp API: كل الروابط والحقول وأكواد الأخطاء

افتح مفاتيح الـ API