חיבור מספר WhatsApp ‏(API)

התחילו לחבר מספר WhatsApp לסביבת העבודה שלכם מתוך האפליקציה שלכם. מערכת WbizTool פותחת סשן WhatsApp חדש ושולחת לכתובת ה-webhook שלכם קוד QR, או עם login_method=phone קוד בן 8 תווים. הציגו אותו לבעלים של הטלפון, הם סורקים את קוד ה-QR או מקלידים את הקוד ב-WhatsApp, והמספר מוכן לשליחת הודעות. עם קוד QR לא צריך לדעת את המספר מראש: WbizTool קורא אותו מ-WhatsApp אחרי הסריקה ושולח אותו ל-webhook שלכם.

מקשרים את המספר שלכם ידנית? עקבו אחרי חיבור מספר ה-WhatsApp שלכם.

הנתיב POST /api/v1/whatsapp-client/create/ הוא כינוי זהה: הוא מריץ את אותו קוד ומחזיר את אותן תגובות. שני הנתיבים ממשיכים לעבוד.

איך החיבור עובד#

קריאת ה-API רק מתחילה את החיבור. קוד ה-QR או קוד הטלפון מגיע מאוחר יותר, לכתובת ה-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, ואז בדקו את סטטוס החיבור כל כמה שניות, עד דקה. אל תבדקו אותו פעם אחת מתוך ה-handler של ה-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 מוכן (נשלח שוב כל כמה שניות בזמן ההמתנה לסריקה, לרוב עם אותה תמונה):

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

הכתובת שלכם חייבת להיות נגישה לציבור וצריכה לענות תוך כמה שניות. ‏WbizTool ממתינה לתשובה שלכם עד 10 שניות; אם השרת שלכם איטי או שאי אפשר להגיע אליו, האירוע הזה הולך לאיבוד, אבל ניסיון החיבור ממשיך. כל קוד סטטוס HTTP מתקבל. על משלוחים שנכשלו לא מתבצע ניסיון חוזר, ולא נשלח דבר אם המספר מתנתק מאוחר יותר. כדי לעקוב אחרי מספר אחרי שהוא מחובר, בדקו שוב ושוב את סטטוס החיבור.

בדיקה חוזרת (polling) במקום webhooks#

אם השרת שלכם לא יכול לקבל webhooks, אתם עדיין צריכים את ה-webhook כדי לקבל את קוד ה-QR, אבל לא חייבים להסתמך עליו לקבלת התוצאה. אחרי שקוד ה-QR נסרק, קראו ל-סטטוס חיבור עם ה-whatsapp_client_id כל כמה שניות, עד שהוא מחזיר Connected. רשימת חשבונות מציגה את אותו מידע עבור כל המספרים שלכם.

טיפים#

• טפלו באירועים כפולים: ודאו שהריצה של ה-handler שלכם יותר מפעם אחת בטוחה, למקרה שאירוע יישלח פעמיים.
• הציגו את קוד ה-QR החדש ביותר: החליפו את התמונה בכל פעם שמגיע אירוע qr_generated חדש, והוסיפו query למניעת שימוש במטמון לכתובת https. קודים ישנים מפסיקים לעבוד.
• סרקו תוך כשתי דקות: אחרי זה תקבלו not_connected. קראו שוב ל-API כדי לקבל קוד חדש.
• בדקו את המספר אחרי סריקת QR: ה-whatsapp_number של האירוע connected הוא המספר שקושר בפועל, והוא עשוי להיות שונה מזה שציפיתם לו.
• הזינו את קוד הטלפון תוך כשלוש דקות: כל ניסיון נותן קוד אחד. אם הוא פג, תקבלו not_connected; קראו שוב ל-API.
• אין קוד QR או קוד טלפון אחרי 10 דקות? הבקשה פגה. קראו שוב ל-API.
• חיבור מלוח הבקרה פשוט יותר כשאתם מקשרים את המספר שלכם. השתמשו בדף הגדרות WhatsApp וסרקו את הקוד שם.