الإجابة المختصرة
WhatsApp API من سمارت ون جروب يعمل على الرابط https://sog.sog.eg/api/whatsapp، وكل طلب يحمل appkey وauthkey من تبويب «ربط API». تستخدم /send للنصوص والصور والملفات والقوالب، و/messages/{id} لمتابعة حالة الرسالة، إلى جانب روابط القوالب والجدولة والحملات والشات بوت والـ Webhook. كل رد بصيغة JSON، والأخطاء تحمل message وcode يحدد السبب.
في هذه الصفحة
- ما أساسيات استخدام الـ API؟
- كيف أرسل نصًا أو صورة أو ملفًا أو قالبًا؟
- كيف أعرف حالة رسالة أرسلتها؟
- كيف أستخدم القوالب؟
- كيف تعمل موافقة جهات الاتصال وإلغاء الاشتراك؟
- كيف أجدول رسالة لوقت لاحق؟
- كيف أرسل حملة لعدد من العملاء؟
- كيف أضبط الردود التلقائية وأقرأ صندوق الوارد؟
- ماذا تعني أكواد الأخطاء؟
- حسابي على منصة whatsapp.sog.eg القديمة، كيف أرسل؟
- أسئلة متكررة
ما أساسيات استخدام الـ 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 (الرقم المصري المحلي مقبول). |
type | text (الافتراضي) أو 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` | السبب والحل |
|---|---|---|
| 401 | invalid_keys | المفاتيح خطأ أو أُعيد توليدها. انسخها من تبويب ربط API. |
| 403 | subscription_inactive | اشتراك الباقة غير نشط أو منتهٍ. ادفع فاتورة التجديد. |
| 403 | terms_required | لم توافق على بنود ربط الرقم بعد. |
| 403 | feature_disabled | الميزة غير مشمولة في باقتك؛ الحقل feature يحدد أيها. |
| 403 | quota_exceeded | وصلت لحد الرسائل أو القوالب أو الحملات أو التطبيقات؛ قد يحمل الرد upgrade بباقة مقترحة. |
| 403 | device_limit / apps_limit | عدد الأجهزة أو التطبيقات النشطة أكبر من حد الباقة. |
| 403 | opted_out | المستلم طلب إيقاف الرسائل. |
| 403 | client_frozen / sending_disabled | الإرسال موقوف على حسابك أو مؤقتًا على المنصة. تواصل مع الدعم. |
| 404 | not_found | الرسالة أو القالب أو الحملة غير موجودة في حسابك. |
| 409 | device_offline | لا يوجد رقم بحالة متصل. أعد ربط الرقم. |
| 422 | invalid_phone وغيرها | حقل ناقص أو غير صحيح؛ أخطاء التحقق تأتي في errors لكل حقل. |
| 429 | rate_limited | أرسلت أسرع من أقل مدة بين الرسائل، أو تجاوزت 60 طلبًا في الدقيقة. انتظر وأعد المحاولة. |
| 502 | engine_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…"}}أسئلة متكررة
to.Idempotency-Key ثابت لكل رسالة، مثل رقم الطلب. إذا وصل الطلب مرتين ونجح الأول يرجع الرد نفسه ولا تُرسل نسخة ثانية.sent أو failed لكل رسالة من /messages/{id}، وتصلك رسالة message.sent عبر الـ Webhook. حالات التسليم والقراءة متاحة على منصة whatsapp.sog.eg القديمة فقط.جاهز تبدأ؟
مرجع WhatsApp API: كل الروابط والحقول وأكواد الأخطاء

