وثائق المطورين

مقدمة

واجهة برمجة واصل (WASEL API) تتيح لك إرسال رسائل عملائك إلى بوتك الذكي والحصول على ردّ جاهز بالدارجة الجزائرية — مبني حصرياً على بيانات متجرك أنت: منتجاتك وقاعدة بيانات الدعم الخاصة بك. نفس المحرك يخدم قنوات تيليجرام والويدجت والـAPI، فالجواب متطابق أينما جاء سؤال عميلك.

• Base URL: https://wasel.dz — كل الطلبات عبر HTTPS.
• الصيغة: JSON في الطلب والرد.
• المصادقة: مفتاح خاص لكل بوت (Bearer token).
• التقييد: حسب خطتك — انظر قسم «الحدود» أدناه.

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

ثلاث خطوات من الصفر إلى أول رد:

• أنشئ حساباً واختر خطة، ثم أضف بوتاً من لوحة التحكم.
• أدخل منتجاتك ومعلومات الدعم (التوصيل، الدفع، الضمان...) — البوت يجاوب فقط من هذه البيانات.
• اربط قناة: توكن تيليجرام من BotFather، أو الصق سطر الويدجت في موقعك، أو استعمل مفتاح wk_live_… مع الـAPI مباشرة.

المصادقة

لكل بوت مفتاحان: مفتاح عام (public key) يظهر في كود الويدجت، ومفتاح سري (wk_live_…) للمصادقة على الـAPI. كلاهما تلقاه من لوحة التحكم → البوت → API والويدجت.

يمكنك إعادة توليد المفتاح السري في أي وقت من نفس الصفحة؛ المفتاح القديم يُلغى فوراً.

Authorization: Bearer wk_live_xxxxxxxxxxxx

إرسال رسالة — POST /api/v1/chat

النقطة الوحيدة التي تحتاجها لجعل بوتك يجاوب: ترسل رسالة العميل، وترجع لك إجابة بالدارجة مع معلومات محادثة.

الرد يتضمن: reply (نص الإجابة)، conversation_id (استعمله لمتابعة المحادثة في لوحة التحكم)، needs_human (true إذا العميل طلب إنسان أو المعلومة غير موجودة — اعرضها على صاحب المتجر)، وmode (ai أو fallback).

عند بلوغ الحد اليومي للذكاء الاصطناعي يرجع الرد برسالة اعتذار و needs_human=true — البوت لا ينقطع أبداً، لكنه لا يخترع أجوبة.

POST /api/v1/chat HTTP/1.1
Host: wasel.dz
Authorization: Bearer wk_live_xxxxxxxxxxxx
Content-Type: application/json

{
  "message": "سلام، شحال السماعة JBL؟",
  "session_id": "customer-123",
  "customer_name": "كريم"
}

{
  "reply": "وعليكم السلام 🙏 السماعة JBL Tune 520BT بـ 8,900 دج...",
  "conversation_id": "cnv_xxxx",
  "session_id": "customer-123",
  "needs_human": false,
  "mode": "ai"
}

الأخطاء

كل الأخطاء ترجع بصيغة JSON موحدة تحتوي حقل error.

الحدود حسب الخطة

الحدود سارية على كل القنوات مجتمعة (تيليجرام + ويدجت + API) لكل بوتات حسابك.

أمثلة جاهزة

انسخ، بدّل المفتاح، وشغّل — الرد يرجع JSON في أقل من ثوانٍ.

curl -X POST https://wasel.dz/api/v1/chat \
  -H "Authorization: Bearer wk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message":"واش عندكم؟","session_id":"c-1"}'

import requests

r = requests.post(
    "https://wasel.dz/api/v1/chat",
    headers={"Authorization": "Bearer wk_live_xxxxxxxxxxxx"},
    json={"message": "واش عندكم؟", "session_id": "c-1"},
)
print(r.json()["reply"])

const r = await fetch("https://wasel.dz/api/v1/chat", {
  method: "POST",
  headers: {
    Authorization: "Bearer wk_live_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "واش عندكم؟", session_id: "c-1" }),
});
const { reply } = await r.json();

payload := []byte(`{"message":"واش عندكم؟","session_id":"c-1"}`)
req, _ := http.NewRequest("POST",
    "https://wasel.dz/api/v1/chat",
    bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer wk_live_xxxxxxxxxxxx")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

$r = wp_remote_post('https://wasel.dz/api/v1/chat', array(
  'timeout' => 60,
  'headers' => array(
    'Authorization' => 'Bearer wk_live_xxxxxxxxxxxx',
    'Content-Type'  => 'application/json',
  ),
  'body' => wp_json_encode(array('message' => 'واش عندكم؟')),
));
$data = json_decode(wp_remote_retrieve_body($r), true);
echo $data['reply'];

const axios = require("axios");

const { data } = await axios.post(
  "https://wasel.dz/api/v1/chat",
  { message: "واش عندكم؟", session_id: "c-1" },
  { headers: { Authorization: "Bearer wk_live_xxxxxxxxxxxx" } },
);
console.log(data.reply);

ويدجت الموقع — سطر واحد

سكريبت واحد يضيف دردشة مباشرة لموقعك (WordPress، Shopify، HTML خام، React...). البوت يظهر أسفل الصفحة ويتحدث بلغة زائرك.

<script src="https://wasel.dz/widget.js" data-wasel="PUBLIC_KEY" defer></script>

<!-- اختياري: غيّر اللغة واللون -->
<script src="https://wasel.dz/widget.js"
  data-wasel="PUBLIC_KEY"
  data-lang="ar"        /* ar | fr | en */
  data-color="#1d6ff2"
  defer></script>

تيليجرام — Polling أو Webhook

طريقتان لربط بوت تيليجرام — اختر الأنسب لحالتك:

• Long Polling (افتراضي): بمجرد إدخال التوكن في لوحة التحكم تبدأ المنصة بسحب الرسائل تلقائياً. لا يحتاج سيرفر عام ولا SSL — مثالي للبداية.
• Webhook (اختياري): في الإنتاج مع دومين عام، سجّل الرابط عبر setWebhook عند BotFather — نفس التوكن، وأداء فوري.

https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://wasel.dz/api/telegram/webhook/<PUBLIC_KEY>

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

أكثر أسئلة التقنيات اللي توصلنا — جواب سريع وواضح:

• هل يجاوب البوت على حاجات غير موجودة في بياناتي؟ لا. في الوضع الصارم يقول «ما عنديش هاد المعلومة» ويقترح تحويلك لصاحب المتجر.
• كيف نعرف أن العميل يحتاج إنسان؟ حقل needs_human=true في الرد، والمحادثة تظهر بوسم أصفر في صندوق الوارد.
• نفس المفتاح لعدة مواقع؟ نعم — الويدجت والـAPI والتيليجرام كلهم نفس البوت ونفس المحرك.
• الرد بالفرنسية أو الإنجليزية؟ البوت متخصص بالدارجة الجزائرية؛ بياناتك أنت تحدد المحتوى (أسعار، أسماء، عروض).

الأسئلة والتواصل

مشكل تقني في البوت؟ من لوحة التحكم → البوت → مختبر التجربة تشوف الخطأ والزمن مباشرة.

• حسابك وبياناتك: التفاصيل الكاملة في صفحة الخصوصية، والحذف الكامل عبر طلب من البريد المسجل.
• أي سؤال تجاري أو تقني: salam@wasel.dz — نجاوبو بالدارجة، الفرنسية ولا الإنجليزية.