ربط رقم WhatsApp ‏(API)

ابدأ ربط رقم WhatsApp بمساحة العمل الخاصة بك من تطبيقك. يفتح Wbiztool جلسة WhatsApp جديدة ويرسل رمز QR، أو رمزًا من 8 أحرف عند استخدام login_method=phone، إلى عنوان URL الخاص بالـ webhook لديك. اعرضه على صاحب الهاتف، فيمسح رمز QR أو يكتب الرمز في WhatsApp، ويصبح الرقم جاهزًا لإرسال الرسائل. مع رمز QR لا تحتاج إلى معرفة الرقم مسبقًا: يقرؤه Wbiztool من WhatsApp بعد المسح ويرسله إلى الـ webhook الخاص بك.

هل تربط رقمك بنفسك يدويًا؟ اتبع ربط رقم WhatsApp الخاص بك.

‏POST /api/v1/whatsapp-client/create/ اسم بديل مطابق: يشغّل الكود نفسه ويُرجع الاستجابات نفسها. يستمر المساران في العمل.

كيف يعمل الربط#

استدعاء API يبدأ الربط فقط. يصل رمز QR أو رمز الهاتف لاحقًا، إلى عنوان URL الخاص بالـ webhook لديك.

1. استدعِ API الربط

   أرسل webhook_url، إضافةً إلى whatsapp_number مع login_method=phone. لإعادة ربط رقم أضفته من قبل، أرسل أيضًا whatsapp_client_id الخاص به. تمنحك الاستجابة whatsapp_client_id. احفظه.

2. استلم رمز QR أو رمز الهاتف

   مع القيمة الافتراضية login_method=qr، يستقبل الـ webhook الخاص بك status=qr_generated مع صورة QR في qr_image. يُعاد إرسال رمز QR كل بضع ثوانٍ ما دام Wbiztool ينتظر المسح، لذا اعرض أحدث رمز دائمًا. أمام الشخص نحو دقيقتين للمسح.

   مع login_method=phone، يستقبل الـ webhook الخاص بك status=pairing_code مع رمز من 8 أحرف في pairing_code، مثل K5EWPGY5. يُرسَل مرة واحدة ويبقى صالحًا لنحو ثلاث دقائق.

   اعرض الصورة أو الرمز على صاحب الهاتف. إذا لم يُستخدم في الوقت المحدد، أو طلب WhatsApp إعادة تحميل الرمز، فستستقبل not_connected؛ استدعِ API مرة أخرى للحصول على رمز جديد.

3. اربط الهاتف

   على الهاتف، افتح WhatsApp ← الأجهزة المرتبطة (Linked devices) ← ربط جهاز (Link a device). امسح رمز QR، أو اضغط على الربط برقم الهاتف بدلًا من ذلك (Link with phone number instead) واكتب الرمز المكوّن من 8 أحرف.

4. احصل على النتيجة

   يستقبل الـ webhook الخاص بك status=connected مع الرقم المرتبط في whatsapp_number عند ربط الرقم، أو status=not_connected إذا لم يُمسح الرمز في الوقت المحدد أو فشل الاتصال. قد يصل الحدث connected قبل أن تُرجع حالة الاتصال القيمة Connected ببضع ثوانٍ. ردّ على الـ webhook أولًا، ثم استعلم من حالة الاتصال كل بضع ثوانٍ لمدة تصل إلى دقيقة. لا تتحقق منها مرة واحدة من داخل معالج الـ webhook.

مثال سريع#

curl -X POST https://wbiztool.com/api/v1/whatsapp/connect/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET"
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/whatsapp/connect/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
    },
    timeout=30,
)
result = response.json()  # read the body even when the HTTP code is 400 or 403

if result.get("status") == 1:
    print("Waiting for QR code, whatsapp_client_id", result["whatsapp_client_id"])
else:
    print("Failed:", result.get("message"))

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/whatsapp/connect/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: 12345,
    api_key: "YOUR_API_KEY",
    webhook_url: "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
  }),
});
const result = await response.json(); // read the body even when the HTTP code is 400 or 403

if (result.status === 1) {
  console.log("Waiting for QR code, whatsapp_client_id", result.whatsapp_client_id);
} else {
  console.error("Failed:", result.message);
}

<?php
$payload = [
    'client_id'       => 12345,
    'api_key'         => 'YOUR_API_KEY',
    'webhook_url'     => 'https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET',
];

$ch = curl_init('https://wbiztool.com/api/v1/whatsapp/connect/');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($result['status'] ?? 0) === 1) {
    echo 'Waiting for QR code, whatsapp_client_id ' . $result['whatsapp_client_id'];
} else {
    echo 'Failed: ' . ($result['message'] ?? 'no response');
}

استبدل 12345 وYOUR_API_KEY بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها. للحصول على رمز هاتف بدلًا من ذلك، أضف "login_method": "phone" و"whatsapp_number": "919876543210".

معاملات الطلب#

استخدام مكتبات العملاء الرسمية#

تستدعي مكتبة Python المسار /api/v1/whatsapp-client/create/ نيابةً عنك. وهي تطلب whatsapp_number؛ ومع رمز QR تُتجاهل القيمة.

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.create_whatsapp_client(
    whatsapp_number="919876543210",
    webhook_url="https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
)
print(result)

تُطلق مكتبة Python الاستثناء requests.exceptions.HTTPError عندما يُرجع API رمز HTTP 400 أو 403، لذا ضع الاستدعاء داخل try/except.

الاستجابة#

عند إنشاء طلب الربط، يُرجع API رمز HTTP 200:

{
  "message": "Whatsapp Client Created",
  "whatsapp_client_id": 678,
  "login_method": "qr",
  "status": 1
}

تعني "status": 1 أن الطلب أُنشئ، لا أن الرقم متصل. واستدعاء API مرة أخرى لا يراكم الأرقام:

• مع رمز QR وبدون whatsapp_client_id، تحصل على whatsapp_client_id نفسه حتى يُمسح أحد رموز QR الخاصة به.
• مع login_method=phone، يحصل الرقم الذي أُضيف من قبل لكنه غير متصل على whatsapp_client_id الحالي الخاص به.
• مع whatsapp_client_id، يُعاد ربط ذلك الرقم.

حتى يُمسح أول رمز QR له، لا يكون للرقم رقم هاتف بعد: يُرجع عرض الأرقام المتصلة وحالة الاتصال رقمًا فارغًا له.

الأخطاء#

الطلب الذي ليس POST يُرجع كائنًا فارغًا {} مع HTTP 200.

أحداث Webhook#

يرسل Wbiztool طلب POST إلى webhook_url الخاص بك في كل خطوة. يكون الجسم مرمّزًا كنموذج (application/x-www-form-urlencoded)، وليس JSON.

رمز QR جاهز (يُعاد إرساله كل بضع ثوانٍ أثناء انتظار المسح، وغالبًا بعنوان URL نفسه):

status=qr_generated&whatsapp_client_id=678&qr_image=...

رمز الهاتف جاهز (مع login_method=phone، يُرسَل مرة واحدة):

status=pairing_code&whatsapp_client_id=678&pairing_code=K5EWPGY5

الرقم متصل، مع الرقم الذي سُجّل الدخول به، كما يُبلغ عنه WhatsApp:

status=connected&whatsapp_client_id=678&whatsapp_number=919876543210

فشل الاتصال، مثلًا لأن رمز QR لم يُمسح أو لم يُدخَل رمز الهاتف في الوقت المحدد:

status=not_connected&whatsapp_client_id=678

يجب أن يكون عنوان URL الخاص بك قابلًا للوصول من الإنترنت، وأن يستجيب خلال بضع ثوانٍ. ينتظر Wbiztool ردّك حتى 10 ثوانٍ؛ وإذا كان خادمك بطيئًا أو تعذّر الوصول إليه، يضيع ذلك الحدث لكن محاولة الربط تستمر. يُقبل أي رمز حالة HTTP. لا يُعاد إرسال الأحداث التي فشل تسليمها، ولا يُرسَل أي شيء إذا انقطع اتصال الرقم لاحقًا. لمتابعة رقم بعد اتصاله، استعلم من حالة الاتصال.

الاستعلام المتكرر بدلًا من webhooks#

إذا كان خادمك لا يستطيع استقبال webhooks، فستظل بحاجة إلى الـ webhook للحصول على رمز QR، لكن لا داعي للاعتماد عليه لمعرفة النتيجة. بعد مسح رمز QR، استدعِ حالة الاتصال مع whatsapp_client_id كل بضع ثوانٍ حتى تُرجع Connected. ويعرض عرض الحسابات الشيء نفسه لكل أرقامك.

نصائح#

• تعامل مع الأحداث المكررة: اجعل المعالج لديك آمنًا للتشغيل أكثر من مرة، في حال وصل حدث مرتين.
• اعرض أحدث رمز QR: استبدل الصورة في كل مرة يصل فيها حدث qr_generated جديد، مع إضافة استعلام لتجاوز التخزين المؤقت إلى عنوان https URL. تتوقف الرموز الأقدم عن العمل.
• امسح الرمز خلال دقيقتين تقريبًا: بعد ذلك ستحصل على not_connected. استدعِ API مرة أخرى للحصول على رمز جديد.
• تحقّق من الرقم بعد مسح رمز QR: قيمة whatsapp_number في الحدث connected هي الرقم الذي رُبط فعلًا، وقد تختلف عن الرقم الذي كنت تتوقعه.
• أدخل رمز الهاتف خلال ثلاث دقائق تقريبًا: كل محاولة تعطي رمزًا واحدًا. إذا انتهت صلاحيته فستحصل على not_connected؛ استدعِ API مرة أخرى.
• لم يصل رمز QR أو رمز الهاتف بعد 10 دقائق؟ انتهت صلاحية الطلب. استدعِ API مرة أخرى.
• الربط من لوحة التحكم أبسط عندما تربط رقمك الخاص. استخدم إعدادات WhatsApp وامسح الرمز هناك.