REST API · الإصدار 1

ابنِ فوق واتساب والولاء بواجهة واتيلي البرمجية

أرسل رسائل واتساب، وأدر جهات الاتصال والحملات والمحادثات، وسجّل نقاط الولاء من الكاشير، واستقبل الأحداث لحظياً عبر ويبهوكات موقّعة. 45 نقطة وصول بمفاتيح مقيّدة بنطاقات ومواصفة OpenAPI ومجموعة Postman.

افتح المرجع التفاعلي أول طلب خلال دقيقتين

مصادقة Bearer أو X-Api-Key
ويبهوكات موقّعة HMAC
OpenAPI 3 و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 جاهز للاستلام"
  }'

ماذا يغطي الـ API

كل ما في لوحة واتيلي تقريباً متاح برمجياً

واتساب أعمال

إرسال نص ووسائط ومستندات وقوالب ورسائل تفاعلية ومواقع وتفاعلات، على الخطوط الرسمية وخطوط QR، مع خيار احترام إلغاء الاشتراك.

جهات الاتصال والحملات

استيراد حتى 500 جهة بطلب، شرائح، إنشاء حملات وبدؤها وإيقافها واستئنافها من نظامك.

صندوق المحادثات

اقرأ المحادثات ورسائلها، وأسندها لموظفيك، وأرشفها، ووسمها، وتابع الأرقام المتصلة والتحليلات.

الولاء ونقاط البيع

طلب واحد من الكاشير يسجّل العميل ويضيف الختم أو النقاط بدون تكرار، مع عكس العمليات وإشعارات المحفظة.

أحداث لحظية

12 حدثاً تصلك على رابطك: رسائل واردة، حالات التسليم، الحملات، الولاء، اتصال الأرقام وانقطاعها.

أمان بنطاقات

لكل مفتاح نطاقات محددة وحد طلبات خاص، ويُلغى فوراً من اللوحة، ويُخزَّن مشفراً عندنا.

البداية السريعة

من الحساب إلى أول رسالة في ثلاث خطوات

أنشئ حسابك وصِل رقمك

سجّل في واتيلي وصِل رقم واتساب رسمياً أو بالـ QR. التسجيل مجاني بفترة تجربة.

أنشئ مفتاح API

من واتساب ثم التكاملات ثم مفاتيح API. اختر النطاقات المطلوبة فقط. يبدأ المفتاح بـ wtly_live_ ويظهر كاملاً مرة واحدة.

أرسل أول طلب

استخدم المثال أعلاه أو استورد مجموعة Postman. العنوان الأساسي: https://site.watily.com/api/v1

المصادقة — أي من الترويستين تكفي:

Authorization: Bearer wtly_live_xxxxxxxx
# أو
X-Api-Key: wtly_live_xxxxxxxx

أخطاء شائعة

HTTP	المعنى
401	invalid_api_key — مفتاح ناقص أو ملغى
403	insufficient_scope / subscription_expired / quota_exceeded
402	wallet_insufficient — رصيد الخط الرسمي لا يغطي الإرسال
409	recipient_opted_out
422	invalid_phone — أرقام من 10 إلى 15 خانة
429	تجاوز حد الطلبات

الحدود لكل مفتاح: 120 طلباً/دقيقة للقراءة و60 طلباً/دقيقة للكتابة والإرسال، وقد تختلف حسب الباقة. أرقام الجوال تُوحَّد تلقائياً، فالرقم 0501234567 يصبح 966501234567.

نقاط الوصول

كل المسارات تحت /api/v1

لكل مسار النطاق الذي يحتاجه مفتاحك. التفاصيل الكاملة للحقول والاستجابات في المرجع التفاعلي.

الرسائل والوسائط

الطريقة	المسار	النطاق	الوصف
POST	/messages	messages:send	إرسال رسالة واتساب (نص، وسائط، قالب، تفاعلي، موقع)
POST	/media	messages:send	رفع وسائط لاستخدامها في رسالة لاحقة
GET	/templates	messages:send	قائمة القوالب المعتمدة

جهات الاتصال والشرائح

الطريقة	المسار	النطاق	الوصف
GET	/contacts	contacts:read	قائمة جهات الاتصال
GET	/contacts/{phone}	contacts:read	جلب جهة اتصال بالرقم
GET	/contacts/{phone}/exists	contacts:read	هل الرقم على واتساب (خطوط QR)
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	إنشاء حملة (مسودة)
GET	/campaigns/{campaign}	campaigns:read	تفاصيل حملة
POST	/campaigns/{campaign}/start	campaigns:write	بدء الحملة
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	أرشفة (وعكسها unarchive)
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	عكس ختم عبر idempotency_key
POST	/loyalty/points	loyalty:write	مسار الكاشير: تسجيل عميل + إضافة نقاط بطلب واحد
POST	/loyalty/points/reverse	loyalty:write	عكس إضافة نقاط
POST	/loyalty/members	loyalty:write	تسجيل عضو جديد
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	إشعار على شاشة القفل في المحفظة
GET	/loyalty/notifications	loyalty:read	سجل تسليم الإشعارات

الويبهوكات

الطريقة	المسار	النطاق	الوصف
GET	/webhooks	webhooks:manage	قائمة نقاط الاستقبال
POST	/webhooks	webhooks:manage	تسجيل نقطة استقبال (يُعاد السر مرة واحدة)
PATCH	/webhooks/{id}	webhooks:manage	تعديل
DELETE	/webhooks/{id}	webhooks:manage	حذف
POST	/webhooks/{id}/test	webhooks:manage	إرسال تجربة

ملاحظة: واجهة «رحلات الأتمتة» أُزيلت، ويرد مسارها القديم بالرمز 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 فقط، فلو تسرّب مفتاحه لا يستطيع إرسال رسائل ولا قراءة محادثات.

وصفات جاهزة

أكثر ما يطلبه المطورون

تسجيل ختم من الكاشير

الطلب نفسه يسجّل العميل ويصدر بطاقته ويضيف الختم. أعد إرسال نفس 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",
    "idempotency_key": "pos-order-882",
    "amount": 45.5,
    "branch": "Main branch"
  }'

تسجيل ويبهوك

الرابط يجب أن يكون HTTPS وعاماً. احفظ السر المُعاد في الرد، فلا يظهر إلا مرة. حذف حقل الأحداث يشترك في الكل.

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).

message.incomingmessage.statuscampaign.completedcontact.unsubscribedcontact.resubscribedloyalty.visit.recordedloyalty.reward.unlockedloyalty.visit.reversedloyalty.points.awardedloyalty.points.reversedinstance.connectedinstance.disconnected

<?php
$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']
http_response_code(200);

const crypto = require('crypto');

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
  res.sendStatus(200);
});

{
  "event": "message.incoming",
  "timestamp": "2026-08-14T10:00:00Z",
  "company_id": 123,
  "data": { "phone": "9665xxxxxxx", "message_text": "Hello" }
}

احسب التوقيع على الجسم الخام قبل أي تحويل JSON، وقارنه بدالة آمنة زمنياً، وردّ بـ 200 بسرعة.

الأدوات

المرجع الكامل والملفات الجاهزة

المرجع التفاعلي

كل الحقول والاستجابات والأمثلة مع إمكانية التجربة.

مواصفة OpenAPI 3

ملف YAML لتوليد العملاء (SDK) وأدوات الاختبار.

مجموعة Postman

استوردها وضع مفتاحك وابدأ التجربة فوراً.

أسئلة شائعة

أسئلة المطورين

كيف أحصل على مفتاح API؟

من لوحة واتيلي: واتساب ثم التكاملات ثم مفاتيح API. أنشئ مفتاحاً واختر النطاقات التي يحتاجها تكاملك فقط. يظهر المفتاح كاملاً مرة واحدة عند إنشائه فاحفظه في مكان آمن، ويمكنك إلغاؤه في أي وقت.

ما عنوان الـ API وكيف أصادق الطلبات؟

العنوان الأساسي هو https://site.watily.com/api/v1. أرسل المفتاح في ترويسة Authorization بصيغة Bearer، أو في ترويسة X-Api-Key، والنتيجة واحدة.

هل يوجد حد لعدد الطلبات؟

نعم، لكل مفتاح 120 طلباً في الدقيقة للقراءة و60 طلباً في الدقيقة للكتابة والإرسال، وقد تتغير حسب الباقة. عند تجاوز الحد يرجع الخطأ 429، فأعد المحاولة بعد قليل.

هل أستطيع استقبال الرسائل الواردة والتحديثات لحظياً؟

نعم عبر الويبهوكات: سجّل رابط HTTPS وحدد الأحداث (رسالة واردة، حالة الرسالة، اكتمال حملة، إلغاء اشتراك، أحداث الولاء، اتصال الرقم أو انقطاعه). كل طلب موقّع بترويسة X-Watily-Signature لتتحقق منه بـ HMAC SHA-256.

هل يدعم الـ API نظام الولاء ونقاط البيع؟

نعم. يوجد مسار من طلب واحد للكاشير وأنظمة ERP يسجّل العميل ويضيف الختم أو النقاط، ومفتاح idempotency_key يمنع التسجيل المكرر، مع مسارات للعكس والاستعلام عن الرصيد وبطاقة المحفظة وإشعارات شاشة القفل.

هل توجد مجموعة Postman أو مواصفة OpenAPI؟

نعم، التوثيق التفاعلي الكامل ومواصفة OpenAPI 3 ومجموعة Postman جاهزة للتحميل من صفحة التوثيق، وتتحدث تلقائياً مع كل تغيير في الـ API.

هل الإرسال عبر الـ API يختلف حسب نوع الاتصال؟

نفس الطلب يعمل على الخطوط الرسمية (Meta Cloud API) وخطوط QR، لكن الرسائل القالبية والرصيد وسياسة نافذة الـ24 ساعة تنطبق على الخط الرسمي كما تحددها ميتا، ويُحتسب خارج الحصة بسعر ميتا المباشر.

جاهز تبدأ التكامل؟

أنشئ حسابك، واحصل على مفتاحك، وإن احتجت مساعدة في ربط نظامك فراسلنا على واتساب.

أنشئ حسابك في واتيلي تحدث معنا على واتساب

واتساب أعمال API بطاقات الولاء كاشير برو الباقات