توثيق واجهة واتيلي البرمجية API للمطورين: واتساب والولاء تخطّي إلى المحتوى
REST API · الإصدار 1

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

أرسل رسائل واتساب، وأدر جهات الاتصال والحملات والمحادثات، وسجّل نقاط الولاء من الكاشير، واستقبل الأحداث لحظياً عبر ويبهوكات موقّعة. 48 نقطة وصول بمفاتيح مقيّدة بنطاقات ومواصفة 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، والقوالب والتفاعلات بالإيموجي على الخطوط الرسمية فقط، مع خيار احترام إلغاء الاشتراك (respect_opt_out).

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

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

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

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

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

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

أحداث لحظية

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

أمان بنطاقات

لكل مفتاح نطاقات محددة وعدّاد طلبات مستقل، ويرتبط بمتجر واحد، ويُلغى فوراً من اللوحة، ولا نحتفظ إلا ببصمته (hash) فلا يمكن استرجاعه.

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

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

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

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

أنشئ مفتاح API

من واتساب ثم التكاملات ثم تبويب مفاتيح API. اختر النطاقات المطلوبة فقط. يبدأ المفتاح بـ wtly_live_ ويظهر كاملاً مرة واحدة (حتى 10 مفاتيح فعّالة لكل شركة، وكل مفتاح مربوط بمتجر).

أرسل أول طلب

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

المصادقة — أي من الترويستين تكفي (وإن أُرسلتا معاً يُعتمد Bearer):

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

أخطاء شائعة

HTTPالمعنى
401invalid_api_key — مفتاح مفقود أو غير صحيح أو ملغى
403insufficient_scope / subscription_expired / quota_exceeded / store_forbidden / module_not_in_plan
402wallet_insufficient — رصيد الخط الرسمي لا يغطي الإرسال
409not_connected / line_banned / idempotency_in_flight / contact_exists / recipient_opted_out — الأخير فقط مع respect_opt_out=true
422invalid_phone — للرسائل من 10 إلى 15 خانة، ولجهات الاتصال 9 خانات على الأقل. أخطاء التحقق من الحقول تأتي بصيغة {message, errors} بلا code
429rate_limited — تجاوز حد الطلبات (انتظر Retry-After ثوانٍ) / governor_blocked — بلغ رقم الواتساب سقف الإرسال، أعد المحاولة لاحقاً
503send_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، وتُحفظ جهات الاتصال بالصيغة التي أُرسلت.

نقاط الوصول

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

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

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

الطريقةالمسارالنطاقالوصف
POST/messagesmessages:sendإرسال رسالة واتساب (نص، وسائط، مستند، صوت، فيديو، تفاعلي، موقع؛ والقالب والتفاعل بالإيموجي للخطوط الرسمية فقط)
POST/mediamessages:sendرفع ملف (حتى 16 ميغابايت، يُحذف بعد 7 أيام) لإرساله لاحقاً عبر media_id
GET/templatesmessages:sendقائمة قوالب ميتا المعتمدة (للإرسال على الخطوط الرسمية)

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

الطريقةالمسارالنطاقالوصف
GET/contactscontacts:readقائمة جهات الاتصال
GET/contacts/{phone}contacts:readجلب جهة اتصال بالرقم
GET/contacts/{phone}/existscontacts:readهل الرقم على واتساب (خطوط QR فقط؛ الخط الرسمي يرجع 501)
POST/contactscontacts:writeإنشاء جهة اتصال
PATCH/contacts/{phone}contacts:writeتعديل جهة اتصال
POST/contacts/importcontacts:writeاستيراد جماعي حتى 500 في الطلب
POST/contacts/{phone}/unsubscribecontacts:writeإلغاء اشتراك من الرسائل التسويقية
POST/contacts/{phone}/resubscribecontacts:writeإعادة الاشتراك
GET/segmentscontacts:readقائمة الشرائح
POST/segmentscontacts:writeإنشاء شريحة

الحملات

الطريقةالمسارالنطاقالوصف
POST/campaignscampaigns:writeإنشاء حملة (مسودة) بجمهور من أرقام (حتى 1000) أو segment_id
GET/campaigns/{campaign}campaigns:readتفاصيل حملة
POST/campaigns/{campaign}/startcampaigns:writeبدء الحملة (refresh_audience اختياري لإعادة حساب جمهور الشريحة)
POST/campaigns/{campaign}/pausecampaigns:writeإيقاف مؤقت
POST/campaigns/{campaign}/resumecampaigns:writeاستئناف

المحادثات والأرقام والتحليلات

الطريقةالمسارالنطاقالوصف
GET/conversationsconversations:readقائمة محادثات صندوق الوارد
GET/conversations/{id}conversations:readتفاصيل محادثة
GET/conversations/{id}/messagesconversations:readرسائل المحادثة
POST/conversations/{id}/assignconversations:writeإسناد لموظف أو إلغاء الإسناد
POST/conversations/{id}/tagsconversations:writeاستبدال الوسوم (مصفوفة فارغة تمسحها كلها)
POST/conversations/{id}/archiveconversations:writeأرشفة
POST/conversations/{id}/unarchiveconversations:writeإلغاء الأرشفة
POST/conversations/{id}/readconversations:writeتعليم كمقروءة
GET/instancesconversations:readأرقام واتساب وحالة اتصالها
GET/analytics/summaryconversations:readملخص الاستخدام لفترة (آخر 30 يوماً افتراضياً)

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

الطريقةالمسارالنطاقالوصف
POST/loyalty/stampsloyalty:writeمسار الكاشير: تسجيل عميل + بطاقة + ختم بطلب واحد
POST/loyalty/stamps/reverseloyalty:writeعكس ختم سُجّل عبر /loyalty/stamps بنفس idempotency_key
POST/loyalty/pointsloyalty:writeمسار الكاشير: تسجيل عميل + إضافة نقاط بطلب واحد
POST/loyalty/points/reverseloyalty:writeعكس إضافة نقاط
POST/loyalty/membersloyalty:writeتسجيل عضو (أو إرجاع الموجود) مع بطاقة ختم اختيارية
POST/loyalty/members/{phone}/pointsloyalty:writeإضافة نقاط لعضو موجود (لا يسجّله تلقائياً)
POST/loyalty/members/{phone}/stampsloyalty:writeختم لعضو موجود (المسار القديم، يُفضّل /loyalty/stamps)
GET/loyalty/programsloyalty:readبرامج الولاء الفعّالة
GET/loyalty/members/{phone}loyalty:readبيانات العضو
GET/loyalty/members/{phone}/pointsloyalty:readفحص سريع للرصيد والمستوى
GET/loyalty/members/{phone}/transactionsloyalty:readسجل العمليات
GET/loyalty/members/{phone}/wallet-cardloyalty:readروابط بطاقة آبل وقوقل محفظة
GET/loyalty/cards/{cardNumber}loyalty:readبحث برقم البطاقة المطبوع أو الممسوح
POST/loyalty/notificationsloyalty:notifyإشعار شاشة القفل في المحفظة لعملاء محددين أو لشريحة كاملة (جرّب dry_run أولاً)
GET/loyalty/notificationsloyalty:readسجل دفعات الإشعارات (آخر 10 دفعات خلال 30 يوماً)

الويبهوكات

الطريقةالمسارالنطاقالوصف
GET/webhookswebhooks:manageقائمة نقاط الاستقبال
POST/webhookswebhooks:manageتسجيل نقطة استقبال (يُعاد السر مرة واحدة)
PATCH/webhooks/{id}webhooks:manageتعديل (الرابط، الأحداث، التفعيل)
DELETE/webhooks/{id}webhooks:manageحذف
POST/webhooks/{id}/testwebhooks: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_.

message.incomingmessage.statuscampaign.completedcontact.unsubscribedcontact.resubscribedloyalty.visit.recordedloyalty.reward.unlockedloyalty.visit.reversedloyalty.points.awardedloyalty.points.reversedinstance.connectedinstance.disconnected
<?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);

احسب التوقيع على الجسم الخام قبل أي تحويل JSON، وقارنه بدالة آمنة زمنياً (وتحقق من تساوي الطول أولاً)، وردّ بأي 2xx خلال 10 ثوانٍ. التحويلات 3xx لا تُتبع وتُعدّ فشلاً، وتُجرى حتى 4 محاولات إجمالاً (الإعادات بعد 30 ثانية ثم 5 دقائق ثم 30 دقيقة). التسليم مرة واحدة على الأقل وبلا ترتيب مضمون، فأزل التكرار بالترويسة X-Watily-Delivery (ثابتة عبر المحاولات). الحقل timestamp بتوقيت الرياض (+03:00).

أسئلة شائعة

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

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

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

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

العنوان الأساسي هو 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.

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

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

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

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

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

نفس الطلب يعمل على الخطوط الرسمية (Meta Cloud API) وخطوط QR، لكن القوالب والتفاعل بالإيموجي (reaction) للخطوط الرسمية فقط، والرسائل الحرة على الخط الرسمي لا تصل إلا ضمن نافذة الـ24 ساعة كما تحددها ميتا (خارجها استخدم قالباً). كل رسالة تُحتسب من حصة الباقة الشهرية، وعند استنفادها يرجع الخطأ 403 quota_exceeded، والخط الرسمي يحتاج أيضاً رصيداً في المحفظة وإلا رجع 402 wallet_insufficient.

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

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

واتساب ابدأ الآن