من تطبيقك، إلى محادثة حقيقية

دليل Whatsflow API.

اربط واتساب بتطبيقك، وأرسل رسائلك من مكان واحد.
كل ما تحتاجه لبدء التكامل، بأمثلة واضحة وجاهزة للتخصيص.

REST APIJSONAPI Key Auth

رسالة في وقتهانصوص، صور، ومستندات. ابقَ على اطلاعأحداث تصل إلى تطبيقك. اتصال تحت السيطرةاربط رقمك وتابع حالته.

الخطوة الأولى

من الصفر إلى أول رسالة

ابدأ بالبيانات المرسلة إليك عند تفعيل خدمة الـ API.

01
جهّز بيانات الربط
عنوان الخدمة BASE_URL، واسم الجلسة INSTANCE، ومفتاح API_KEY.
02
اربط رقمك
امسح رمز QR، ثم تأكد أن حالة الاتصال أصبحت open.
03
أرسل أول رسالة
استخدم مثال الإرسال مع رقم اختبار تملكه، ثم أضف الربط إلى تطبيقك.

عنوان الخدمة BASE URLhttps://connect.whats-flow.netHTTPS

استخدم عنوان الخدمة أعلاه مباشرة، واسم الجلسة والمفتاح المرسلين عند التفعيل. استبدل my-business باسم جلستك والقيم .example وYOUR_… ببياناتك. v1 هو إصدار الدليل؛ لا تضف /v1 أو /docs/v1 إلى مسارات الطلبات.

export BASE_URL="https://connect.whats-flow.net"
export INSTANCE="my-business"
export API_KEY="YOUR_API_KEY"

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

اتصال موثّق

مفتاح واحد لطلباتك

أرسل مفتاح جلستك في ترويسة apikey مع كل طلب. طلبات POST في هذا الدليل تستخدم JSON.

الترويسة	القيمة	الاستخدام
`apikey`	`YOUR_API_KEY`	مطلوبة لكل الطلبات
`Content-Type`	`application/json`	مع جسم الطلب JSON

مفتاحك يظل على الخادم.

نفّذ الطلبات من الخادم، ولا تضع المفتاح في كود المتصفح أو مستودع عام. اسم {instance} في المسارات هو اسم الجلسة المخصص لحسابك، وليس رقم الهاتف.

مرجع الطلباتAPI REFERENCE

الاتصال

ربط رقم واتساب#

اطلب رمز QR للجلسة التي تم تجهيزها لحسابك، ثم امسحه من واتساب ← الأجهزة المرتبطة ← ربط جهاز.

GET/instance/connect/{instance}API KEY

بيانات الطلب

instancepath · stringمطلوب

اسم الجلسة المستلم عند التفعيل؛ مثال: my-business.

هذا الطلب لا يحتاج إلى جسم (Body).

قيمة base64 تحتوي على صورة الرمز عند انتظار الربط. المثال مختصر ولا يحتوي على رمز صالح للمسح. إذا انتهت صلاحية الرمز، اطلب رمزًا جديدًا. إذا كانت الجلسة متصلة بالفعل، قد ترجع بيانات الاتصال بدلًا منه.

curl --request GET "${BASE_URL}/instance/connect/${INSTANCE}" \
  --header "apikey: ${API_KEY}"

مثال استجابة مختصر200

{
    "pairingCode": null,
    "code": "QR_CODE_CONTENT",
    "base64": "data:image/png;base64,QR_IMAGE_DATA",
    "count": 1
}

الاتصال

حالة الاتصال#

تحقق من جاهزية الجلسة قبل إرسال الرسائل. استخدم قيمة state داخل instance لمعرفة حالة الرقم.

GET/instance/connectionState/{instance}API KEY

بيانات الطلب

instancepath · stringمطلوب

اسم الجلسة المستلم عند التفعيل؛ مثال: my-business.

هذا الطلب لا يحتاج إلى جسم (Body).

open: متصل وجاهز للإرسال. connecting: جارٍ الاتصال. close: غير متصل؛ راجع الهاتف وأعد الربط عند الحاجة.

curl --request GET "${BASE_URL}/instance/connectionState/${INSTANCE}" \
  --header "apikey: ${API_KEY}"

مثال استجابة مختصر200

{
    "instance": {
        "instanceName": "my-business",
        "state": "open"
    }
}

الرسائل

إرسال رسالة نصية#

أرسل تأكيد طلب، تحديث شحنة، أو رسالة متابعة لعميلك. اكتب رقم المستلم بصيغة دولية، بأرقام فقط دون + أو مسافات.

POST/message/sendText/{instance}API KEY

بيانات الطلب

instancepath · stringمطلوب

اسم الجلسة المستلم عند التفعيل؛ مثال: my-business.

numberstringمطلوب

رقم المستلم مع كود الدولة، مثل 201000000000.

textstringمطلوب

نص الرسالة المراد إرساله.

linkPreviewbooleanاختياري

تفعيل معاينة الروابط داخل الرسالة.

delayintegerاختياري

تأخير قبل الإرسال بالمللي ثانية.

الاستجابة مختصرة. احتفظ بقيمة key.id لتتبع الرسالة. قبول الطلب أو ظهور PENDING لا يعني وصولها؛ تابع تحديثات الرسالة عبر Webhooks.

curl --request POST "${BASE_URL}/message/sendText/${INSTANCE}" \
  --header "apikey: ${API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "number": "201000000000",
    "text": "مرحبًا أحمد، تم تأكيد طلبك #1042. شكرًا لاختيارك لنا!",
    "linkPreview": false
}'

// Node.js 18+ · server-side
const baseUrl = process.env.BASE_URL.replace(/\/$/, "");
const instance = encodeURIComponent(process.env.INSTANCE);

const response = await fetch(`${baseUrl}/message/sendText/${instance}`, {
  method: "POST",
  headers: {
    apikey: process.env.API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "201000000000",
    text: "مرحبًا أحمد، تم تأكيد طلبك #1042.",
    linkPreview: false
  })
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}
const message = await response.json();
console.log(message.key.id);

استخدم متغيرات البيئة الموضحة في البداية السريعة. المثال يعمل على الخادم.

use Illuminate\Support\Facades\Http;

// Read credentials from your server configuration.
$baseUrl = rtrim(config('services.whatsflow.url'), '/');
$instance = rawurlencode(config('services.whatsflow.instance'));

$message = Http::withHeaders([
    'apikey' => config('services.whatsflow.key'),
])->timeout(30)->post(
    "{$baseUrl}/message/sendText/{$instance}",
    [
        'number' => '201000000000',
        'text' => 'مرحبًا أحمد، تم تأكيد طلبك #1042.',
        'linkPreview' => false,
    ]
)->throw()->json();

$messageId = $message['key']['id'];

أضف url وinstance وkey داخل services.whatsflow في config/services.php، واقرأ قيمها من متغيرات البيئة.

مثال استجابة مختصر201

{
    "key": {
        "remoteJid": "201000000000@s.whatsapp.net",
        "fromMe": true,
        "id": "EXAMPLE_MESSAGE_ID"
    },
    "status": "PENDING"
}

الرسائل

إرسال الصور والملفات#

شارك صورة منتج، فيديو، أو مستندًا مثل فاتورة PDF من رابط مباشر يمكن للخدمة الوصول إليه.

POST/message/sendMedia/{instance}API KEY

بيانات الطلب

instancepath · stringمطلوب

اسم الجلسة المستلم عند التفعيل؛ مثال: my-business.

numberstringمطلوب

رقم المستلم بالصيغة الدولية.

mediatypestringمطلوب

نوع المحتوى: image أو video أو document.

mediastringمطلوب

رابط مباشر للملف، أو محتواه بصيغة Base64.

mimetypestringاختياري

نوع MIME المطابق للملف، مثل application/pdf.

fileNamestringاختياري

اسم الملف الظاهر للمستلم، خصوصًا للمستندات.

captionstringاختياري

وصف أو نص مرافق للملف.

استبدل رابط الملف التوضيحي برابط حقيقي. استخدم رابطًا يعيد الملف نفسه دون صفحة تسجيل دخول، واضبط mediatype وmimetype بما يناسبه. حدود الحجم والإرسال تعتمد على إعدادات حسابك.

curl --request POST "${BASE_URL}/message/sendMedia/${INSTANCE}" \
  --header "apikey: ${API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "number": "201000000000",
    "mediatype": "document",
    "mimetype": "application/pdf",
    "media": "https://your-store.example/invoices/1042.pdf",
    "fileName": "invoice-1042.pdf",
    "caption": "فاتورة طلبك #1042"
}'

مثال استجابة مختصر201

{
    "key": {
        "id": "EXAMPLE_MEDIA_MESSAGE_ID",
        "fromMe": true
    },
    "status": "PENDING"
}

الأحداث

استقبال الأحداث · Webhooks#

استقبل الرسائل وتغييرات الاتصال على خادمك تلقائيًا. جهّز مسار HTTPS يقبل POST وJSON، ثم سجّله للجلسة.

POST/webhook/set/{instance}API KEY

بيانات الطلب

instancepath · stringمطلوب

اسم الجلسة المستلم عند التفعيل؛ مثال: my-business.

webhook.enabledbooleanمطلوب

تفعيل استقبال الأحداث أو إيقافه.

webhook.urlstringمطلوب

عنوان HTTPS الذي سيستقبل الأحداث على خادمك.

webhook.eventsarrayاختياري

الأحداث التي ترغب في الاشتراك بها؛ حددها كما في المثال.

webhook.byEventsbooleanاختياري

false لإرسال كل الأحداث إلى الرابط نفسه.

webhook.base64booleanاختياري

تضمين الوسائط بصيغة Base64 عند تفعيلها.

webhook.headersobjectاختياري

ترويسات مخصصة للتحقق من الطلب في خادمك.

تحقق من X-Webhook-Secret قبل معالجة الطلب، ثم أعد استجابة 200 بسرعة وعالج المهام الطويلة في الخلفية. تجنب معالجة الحدث المكرر باستخدام معرّف الرسالة ونوع الحدث وحالة التحديث. لا تسجل مفاتيح الاتصال أو كامل بيانات الأحداث في سجلات عامة.

curl --request POST "${BASE_URL}/webhook/set/${INSTANCE}" \
  --header "apikey: ${API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "webhook": {
        "enabled": true,
        "url": "https://your-app.example/webhooks/whatsflow",
        "byEvents": false,
        "base64": false,
        "headers": {
            "X-Webhook-Secret": "YOUR_WEBHOOK_SECRET"
        },
        "events": [
            "MESSAGES_UPSERT",
            "MESSAGES_UPDATE",
            "CONNECTION_UPDATE"
        ]
    }
}'

مثال استجابة مختصر201

{
    "enabled": true,
    "url": "https://your-app.example/webhooks/whatsflow",
    "events": [
        "MESSAGES_UPSERT",
        "MESSAGES_UPDATE",
        "CONNECTION_UPDATE"
    ]
}

أهم الأحداث

الحدث عند الاشتراك	متى يصل؟
`MESSAGES_UPSERT`	عند إضافة رسالة؛ افحص `data.key.fromMe` لتمييز الوارد عن الصادر.
`MESSAGES_UPDATE`	عند تحديث الرسالة، مثل تغيّر حالة التسليم أو القراءة إذا كانت متاحة.
`CONNECTION_UPDATE`	عند تغيّر حالة اتصال الجلسة.

كيف يبدو حدث رسالة واردة؟

مثال مختصر لرسالة نصية. داخل الطلب الوارد، اسم الحدث يكون مثل messages.upsert، وبنية data تختلف حسب الحدث ونوع الرسالة.

{
    "event": "messages.upsert",
    "instance": "my-business",
    "data": {
        "key": {
            "remoteJid": "201000000000@s.whatsapp.net",
            "fromMe": false,
            "id": "EXAMPLE_INCOMING_ID"
        },
        "pushName": "Ahmed",
        "message": {
            "conversation": "متى يصل طلبي؟"
        },
        "messageType": "conversation"
    }
}

لربط أكثر استقرارًا

افهم الاستجابة، وحدد خطوتك التالية

افحص رمز HTTP ونص الخطأ معًا. قد تختلف تفاصيل الخطأ بحسب الطلب وإعدادات الخدمة.

الرمز	المعنى	ما الذي تراجعه؟
`200 / 201`	نجاح الطلب	اقرأ البيانات؛ نجاح طلب إرسال لا يؤكد التسليم.
`400`	بيانات غير صحيحة	راجع الحقول المطلوبة وصيغة الرقم ونوع الملف.
`401`	فشل المصادقة	تأكد من قيمة ترويسة `apikey`.
`403`	وصول غير مسموح	راجع صلاحية المفتاح للجلسة المطلوبة.
`404`	المورد غير موجود	تحقق من عنوان الخدمة، المسار، واسم الجلسة.
`429`	تجاوز معدل الطلبات، إن كان مفعّلًا	قلّل المعدل واحترم `Retry-After` إذا أعادته الخدمة.
`5xx`	خطأ في الخدمة	تحقق من الاتصال، واحتفظ بتفاصيل الطلب لإرسالها للدعم دون مفاتيح سرية.

إرسال منظم

استخدم طابورًا للرسائل والتزم بحدود حسابك. لا تكرر طلب إرسال تلقائيًا بعد انقطاع الرد؛ تحقق أولًا لتجنب إرسال الرسالة مرتين.

محادثات متوقعة

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

لنبدأ الربط

تطبيقك جاهز للخطوة التالية؟

تواصل معنا للحصول على بيانات الـ API أو مساعدة في التكامل.

تحدث مع فريق Whatsflow

دليل Whatsflow API.

من الصفر إلى أول رسالة

جهّز بيانات الربط

اربط رقمك

أرسل أول رسالة

مفتاح واحد لطلباتك

ربط رقم واتساب#

بيانات الطلب

حالة الاتصال#

بيانات الطلب

إرسال رسالة نصية#

بيانات الطلب

إرسال الصور والملفات#

بيانات الطلب

استقبال الأحداث · Webhooks#

بيانات الطلب

أهم الأحداث

افهم الاستجابة، وحدد خطوتك التالية

إرسال منظم

محادثات متوقعة

تطبيقك جاهز للخطوة التالية؟