واتساب أعمال
إرسال نص ووسائط ومستندات ورسائل تفاعلية ومواقع على الخطوط الرسمية وخطوط QR، والقوالب والتفاعلات بالإيموجي على الخطوط الرسمية فقط، مع خيار احترام إلغاء الاشتراك (respect_opt_out).
أرسل رسائل واتساب، وأدر جهات الاتصال والحملات والمحادثات، وسجّل نقاط الولاء من الكاشير، واستقبل الأحداث لحظياً عبر ويبهوكات موقّعة. 48 نقطة وصول بمفاتيح مقيّدة بنطاقات ومواصفة OpenAPI ومجموعة Postman.
curl -X POST https://site.watily.com/api/v1/messages \
-H "Authorization: Bearer wtly_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"to": "966501234567",
"type": "text",
"message": "مرحباً! طلبك رقم 1042 جاهز للاستلام"
}'
إرسال نص ووسائط ومستندات ورسائل تفاعلية ومواقع على الخطوط الرسمية وخطوط QR، والقوالب والتفاعلات بالإيموجي على الخطوط الرسمية فقط، مع خيار احترام إلغاء الاشتراك (respect_opt_out).
استيراد حتى 500 جهة بطلب، شرائح، إنشاء حملات وبدؤها وإيقافها واستئنافها من نظامك.
اقرأ المحادثات ورسائلها، وأسندها لموظفيك، وأرشفها، ووسمها، وتابع الأرقام المتصلة والتحليلات.
طلب واحد من الكاشير يسجّل العميل ويضيف الختم أو النقاط بدون تكرار، مع عكس العمليات وإشعارات المحفظة.
12 حدثاً تصلك على رابطك: رسائل واردة، حالات التسليم، الحملات، الولاء، واتصال خطوط QR وانقطاعها.
لكل مفتاح نطاقات محددة وعدّاد طلبات مستقل، ويرتبط بمتجر واحد، ويُلغى فوراً من اللوحة، ولا نحتفظ إلا ببصمته (hash) فلا يمكن استرجاعه.
سجّل في واتيلي وصِل رقم واتساب رسمياً أو بالـ QR.
من واتساب ثم التكاملات ثم تبويب مفاتيح API. اختر النطاقات المطلوبة فقط. يبدأ المفتاح بـ wtly_live_ ويظهر كاملاً مرة واحدة (حتى 10 مفاتيح فعّالة لكل شركة، وكل مفتاح مربوط بمتجر).
استخدم المثال أعلاه أو استورد مجموعة Postman. العنوان الأساسي: https://site.watily.com/api/v1
المصادقة — أي من الترويستين تكفي (وإن أُرسلتا معاً يُعتمد Bearer):
Authorization: Bearer wtly_live_xxxxxxxx
# أو
X-Api-Key: wtly_live_xxxxxxxx
أخطاء شائعة
| HTTP | المعنى |
|---|---|
| 401 | invalid_api_key — مفتاح مفقود أو غير صحيح أو ملغى |
| 403 | insufficient_scope / subscription_expired / quota_exceeded / store_forbidden / module_not_in_plan |
| 402 | wallet_insufficient — رصيد الخط الرسمي لا يغطي الإرسال |
| 409 | not_connected / line_banned / idempotency_in_flight / contact_exists / recipient_opted_out — الأخير فقط مع respect_opt_out=true |
| 422 | invalid_phone — للرسائل من 10 إلى 15 خانة، ولجهات الاتصال 9 خانات على الأقل. أخطاء التحقق من الحقول تأتي بصيغة {message, errors} بلا code |
| 429 | rate_limited — تجاوز حد الطلبات (انتظر Retry-After ثوانٍ) / governor_blocked — بلغ رقم الواتساب سقف الإرسال، أعد المحاولة لاحقاً |
| 503 | send_unavailable / send_outcome_unknown — الثاني يعني أن الرسالة قد تكون وصلت: لا تعِد الإرسال قبل التحقق من حالتها |
الحدود لكل مفتاح: 120 طلباً/دقيقة لكل طلبات القراءة (GET) و60 طلباً/دقيقة لكل طلبات الكتابة والإرسال (POST وPATCH وDELETE)، وقد تختلف حسب الباقة. عند التجاوز يرجع 429 مع ترويسة Retry-After.
شكل الاستجابات: النجاح {"status":"success","data":{...}} (وبعض المسارات تضيف "ok": true)، والخطأ {"status":"error","code":"...","message":"..."} مع ok=false في أغلب المسارات، وأخطاء التحقق 422 بصيغة {"message","errors"}. أرقام الجوال تُوحَّد تلقائياً (يُفترض الرمز 966 ما لم يبدأ الرقم بمفتاح دولي معروف)، فالرقم 0501234567 يصبح 966501234567، وتُحفظ جهات الاتصال بالصيغة التي أُرسلت.
لكل مسار النطاق الذي يحتاجه مفتاحك. التفاصيل الكاملة للحقول والاستجابات في المرجع التفاعلي.
| الطريقة | المسار | النطاق | الوصف |
|---|---|---|---|
| POST | /messages | messages:send | إرسال رسالة واتساب (نص، وسائط، مستند، صوت، فيديو، تفاعلي، موقع؛ والقالب والتفاعل بالإيموجي للخطوط الرسمية فقط) |
| POST | /media | messages:send | رفع ملف (حتى 16 ميغابايت، يُحذف بعد 7 أيام) لإرساله لاحقاً عبر media_id |
| GET | /templates | messages:send | قائمة قوالب ميتا المعتمدة (للإرسال على الخطوط الرسمية) |
| الطريقة | المسار | النطاق | الوصف |
|---|---|---|---|
| GET | /contacts | contacts:read | قائمة جهات الاتصال |
| GET | /contacts/{phone} | contacts:read | جلب جهة اتصال بالرقم |
| GET | /contacts/{phone}/exists | contacts:read | هل الرقم على واتساب (خطوط QR فقط؛ الخط الرسمي يرجع 501) |
| POST | /contacts | contacts:write | إنشاء جهة اتصال |
| PATCH | /contacts/{phone} | contacts:write | تعديل جهة اتصال |
| POST | /contacts/import | contacts:write | استيراد جماعي حتى 500 في الطلب |
| POST | /contacts/{phone}/unsubscribe | contacts:write | إلغاء اشتراك من الرسائل التسويقية |
| POST | /contacts/{phone}/resubscribe | contacts:write | إعادة الاشتراك |
| GET | /segments | contacts:read | قائمة الشرائح |
| POST | /segments | contacts:write | إنشاء شريحة |
| الطريقة | المسار | النطاق | الوصف |
|---|---|---|---|
| POST | /campaigns | campaigns:write | إنشاء حملة (مسودة) بجمهور من أرقام (حتى 1000) أو segment_id |
| GET | /campaigns/{campaign} | campaigns:read | تفاصيل حملة |
| POST | /campaigns/{campaign}/start | campaigns:write | بدء الحملة (refresh_audience اختياري لإعادة حساب جمهور الشريحة) |
| POST | /campaigns/{campaign}/pause | campaigns:write | إيقاف مؤقت |
| POST | /campaigns/{campaign}/resume | campaigns:write | استئناف |
| الطريقة | المسار | النطاق | الوصف |
|---|---|---|---|
| GET | /conversations | conversations:read | قائمة محادثات صندوق الوارد |
| GET | /conversations/{id} | conversations:read | تفاصيل محادثة |
| GET | /conversations/{id}/messages | conversations:read | رسائل المحادثة |
| POST | /conversations/{id}/assign | conversations:write | إسناد لموظف أو إلغاء الإسناد |
| POST | /conversations/{id}/tags | conversations:write | استبدال الوسوم (مصفوفة فارغة تمسحها كلها) |
| POST | /conversations/{id}/archive | conversations:write | أرشفة |
| POST | /conversations/{id}/unarchive | conversations:write | إلغاء الأرشفة |
| POST | /conversations/{id}/read | conversations:write | تعليم كمقروءة |
| GET | /instances | conversations:read | أرقام واتساب وحالة اتصالها |
| GET | /analytics/summary | conversations:read | ملخص الاستخدام لفترة (آخر 30 يوماً افتراضياً) |
| الطريقة | المسار | النطاق | الوصف |
|---|---|---|---|
| POST | /loyalty/stamps | loyalty:write | مسار الكاشير: تسجيل عميل + بطاقة + ختم بطلب واحد |
| POST | /loyalty/stamps/reverse | loyalty:write | عكس ختم سُجّل عبر /loyalty/stamps بنفس idempotency_key |
| POST | /loyalty/points | loyalty:write | مسار الكاشير: تسجيل عميل + إضافة نقاط بطلب واحد |
| POST | /loyalty/points/reverse | loyalty:write | عكس إضافة نقاط |
| POST | /loyalty/members | loyalty:write | تسجيل عضو (أو إرجاع الموجود) مع بطاقة ختم اختيارية |
| POST | /loyalty/members/{phone}/points | loyalty:write | إضافة نقاط لعضو موجود (لا يسجّله تلقائياً) |
| POST | /loyalty/members/{phone}/stamps | loyalty:write | ختم لعضو موجود (المسار القديم، يُفضّل /loyalty/stamps) |
| GET | /loyalty/programs | loyalty:read | برامج الولاء الفعّالة |
| GET | /loyalty/members/{phone} | loyalty:read | بيانات العضو |
| GET | /loyalty/members/{phone}/points | loyalty:read | فحص سريع للرصيد والمستوى |
| GET | /loyalty/members/{phone}/transactions | loyalty:read | سجل العمليات |
| GET | /loyalty/members/{phone}/wallet-card | loyalty:read | روابط بطاقة آبل وقوقل محفظة |
| GET | /loyalty/cards/{cardNumber} | loyalty:read | بحث برقم البطاقة المطبوع أو الممسوح |
| POST | /loyalty/notifications | loyalty:notify | إشعار شاشة القفل في المحفظة لعملاء محددين أو لشريحة كاملة (جرّب dry_run أولاً) |
| GET | /loyalty/notifications | loyalty:read | سجل دفعات الإشعارات (آخر 10 دفعات خلال 30 يوماً) |
| الطريقة | المسار | النطاق | الوصف |
|---|---|---|---|
| GET | /webhooks | webhooks:manage | قائمة نقاط الاستقبال |
| POST | /webhooks | webhooks:manage | تسجيل نقطة استقبال (يُعاد السر مرة واحدة) |
| PATCH | /webhooks/{id} | webhooks:manage | تعديل (الرابط، الأحداث، التفعيل) |
| DELETE | /webhooks/{id} | webhooks:manage | حذف |
| POST | /webhooks/{id}/test | webhooks:manage | إرسال حدث message.incoming تجريبي (data.test = true) |
ملاحظة: واجهة «رحلات الأتمتة» أُزيلت، ويرد مسارها القديم بالرمز 410. استخدم أتمتة السلة المتروكة في محرك النمو بدلاً منها.
| النطاق | يسمح بـ |
|---|---|
| messages:send | إرسال الرسائل ورفع الوسائط وقراءة القوالب |
| contacts:read | قراءة جهات الاتصال والشرائح |
| contacts:write | إنشاء وتعديل جهات الاتصال والشرائح |
| campaigns:read | قراءة الحملات |
| campaigns:write | إنشاء الحملات والتحكم بها |
| conversations:read | قراءة المحادثات والأرقام والتحليلات |
| conversations:write | إسناد المحادثات وأرشفتها ووسمها وتعليمها كمقروءة |
| loyalty:read | قراءة الولاء |
| loyalty:write | تسجيل الأعضاء والأختام والنقاط وعكسها |
| loyalty:notify | إشعارات المحفظة (نطاق منفصل لحساسيته) |
| webhooks:manage | إدارة الويبهوكات |
مثال: نظام الكاشير يحتاج loyalty:write و loyalty:read فقط، فلو تسرّب مفتاحه لا يستطيع إرسال رسائل ولا قراءة محادثات.
الطلب نفسه يسجّل العميل ويصدر بطاقته ويضيف الختم (يمكن حذف program_id فقط إن كان للمتجر برنامج ختم فعّال واحد). أعد إرسال نفس idempotency_key لا يكرر العملية. تنبيه: إصدار بطاقة جديدة يرسل للعميل قالب واتساب مرة واحدة، فلا تعِد تشغيل طلبات قديمة بالجملة.
curl -X POST https://site.watily.com/api/v1/loyalty/stamps \
-H "X-Api-Key: wtly_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"phone": "966501234567",
"program_id": 12,
"idempotency_key": "pos-order-882",
"amount": 45.5,
"branch": "Main branch"
}'
الرابط يجب أن يكون HTTPS وعاماً. احفظ السر المُعاد في الرد (data.secret)، فلا يظهر إلا مرة. حذف حقل الأحداث (أو إرساله فارغاً) يشترك في الكل، والحد الأقصى 5 نقاط استقبال للشركة.
curl -X POST https://site.watily.com/api/v1/webhooks \
-H "Authorization: Bearer wtly_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/watily-hook",
"events": ["message.incoming", "message.status"]
}'
كل طلب يحمل الترويسات X-Watily-Event X-Watily-Delivery X-Watily-Signature. التوقيع هو sha256=HMAC_SHA256(raw_body, secret) (hex)، والسر هو السلسلة الكاملة بما فيها البادئة whsec_.
<?php
// $endpointSecret = the whole whsec_... string returned once by POST /webhooks
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_WATILY_SIGNATURE'] ?? '';
$calc = 'sha256=' . hash_hmac('sha256', $raw, $endpointSecret);
if (!hash_equals($calc, $sig)) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true); // $event['event'], $event['data']
// dedupe on $_SERVER['HTTP_X_WATILY_DELIVERY'] (stable across retries)
http_response_code(200);const crypto = require('crypto');
// ENDPOINT_SECRET = the whole whsec_... string returned once by POST /webhooks
app.post('/watily-hook', express.raw({ type: '*/*' }), (req, res) => {
const calc = 'sha256=' + crypto
.createHmac('sha256', ENDPOINT_SECRET)
.update(req.body).digest('hex');
const sig = req.get('X-Watily-Signature') || '';
if (sig.length !== calc.length ||
!crypto.timingSafeEqual(Buffer.from(calc), Buffer.from(sig))) {
return res.sendStatus(401);
}
const evt = JSON.parse(req.body); // evt.event, evt.data
// dedupe on req.get('X-Watily-Delivery') (stable across retries)
res.sendStatus(200);
});{
"event": "message.incoming",
"timestamp": "2026-08-14T10:00:00+03:00",
"company_id": 123,
"data": {
"phone": "966551234567",
"customer_name": "Ahmed",
"message_text": "Hello",
"instance_id": "abc123",
"raw_remote_jid": "966551234567@s.whatsapp.net",
"wa_message_id": "wamid.HBgL..."
}
}احسب التوقيع على الجسم الخام قبل أي تحويل JSON، وقارنه بدالة آمنة زمنياً (وتحقق من تساوي الطول أولاً)، وردّ بأي 2xx خلال 10 ثوانٍ. التحويلات 3xx لا تُتبع وتُعدّ فشلاً، وتُجرى حتى 4 محاولات إجمالاً (الإعادات بعد 30 ثانية ثم 5 دقائق ثم 30 دقيقة). التسليم مرة واحدة على الأقل وبلا ترتيب مضمون، فأزل التكرار بالترويسة X-Watily-Delivery (ثابتة عبر المحاولات). الحقل timestamp بتوقيت الرياض (+03:00).
من لوحة واتيلي: واتساب ثم التكاملات ثم تبويب مفاتيح API. أنشئ مفتاحاً واختر النطاقات التي يحتاجها تكاملك فقط، ويرتبط المفتاح بمتجر واحد (حتى 10 مفاتيح فعّالة لكل شركة). يظهر المفتاح كاملاً مرة واحدة عند إنشائه فاحفظه في مكان آمن لأننا لا نحتفظ إلا ببصمته، ويمكنك إلغاؤه في أي وقت فيتوقف فوراً.
العنوان الأساسي هو https://site.watily.com/api/v1. أرسل المفتاح في ترويسة Authorization بصيغة Bearer، أو في ترويسة X-Api-Key، والنتيجة واحدة (وإن أُرسلتا معاً يُعتمد Bearer).
نعم، لكل مفتاح 120 طلباً في الدقيقة تُشارَك بين كل طلبات القراءة (GET) و60 طلباً في الدقيقة تُشارَك بين كل طلبات الكتابة والإرسال (POST وPATCH وDELETE)، وقد تتغير حسب الباقة. عند تجاوز الحد يرجع الخطأ 429 مع ترويسة Retry-After تحدد عدد الثواني قبل المحاولة التالية.
نعم عبر الويبهوكات: سجّل رابط HTTPS عاماً (حتى 5 روابط لكل شركة) وحدد الأحداث (رسالة واردة، حالة الرسالة، اكتمال حملة، إلغاء اشتراك وإعادته، أحداث الولاء، واتصال خط QR أو انقطاعه). كل طلب موقّع بترويسة X-Watily-Signature وهي sha256= متبوعة بـ HMAC-SHA256 للجسم الخام باستخدام السر كاملاً بما فيه البادئة whsec_. اعتبر أي رد 2xx خلال 10 ثوانٍ نجاحاً؛ وغير ذلك يُعاد حتى 4 محاولات إجمالاً (بعد 30 ثانية ثم 5 دقائق ثم 30 دقيقة)، والتسليم مرة واحدة على الأقل، فأزل التكرار بالترويسة X-Watily-Delivery.
نعم. يوجد مسار من طلب واحد للكاشير وأنظمة ERP يسجّل العميل ويضيف الختم أو النقاط، ومفتاح idempotency_key يمنع التسجيل المكرر، مع مسارات للعكس والاستعلام عن الرصيد وبطاقة المحفظة وإشعارات شاشة القفل. انتبه أن إصدار بطاقة ختم جديدة يرسل للعميل رسالة واتساب (قالب) مرة واحدة، وأن أي ختم أو نقاط تحدّث بطاقة المحفظة المثبّتة.
نعم، المرجع الكامل (قابل للتصفح) ومواصفة OpenAPI 3 ومجموعة Postman جاهزة للتحميل من صفحة التوثيق، ونحدّثها مع تغييرات الـ API.
نفس الطلب يعمل على الخطوط الرسمية (Meta Cloud API) وخطوط QR، لكن القوالب والتفاعل بالإيموجي (reaction) للخطوط الرسمية فقط، والرسائل الحرة على الخط الرسمي لا تصل إلا ضمن نافذة الـ24 ساعة كما تحددها ميتا (خارجها استخدم قالباً). كل رسالة تُحتسب من حصة الباقة الشهرية، وعند استنفادها يرجع الخطأ 403 quota_exceeded، والخط الرسمي يحتاج أيضاً رصيداً في المحفظة وإلا رجع 402 wallet_insufficient.
أنشئ حسابك، واحصل على مفتاحك، وإن احتجت مساعدة في ربط نظامك فراسلنا على واتساب.