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

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

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

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

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

קריאת ה-API רק מתחילה את החיבור. קוד ה-QR מגיע מאוחר יותר, לכתובת ה-webhook שלכם.

1. קראו ל-API החיבור

   שלחו את מספר הטלפון ואת ה-webhook_url שלכם. התגובה מחזירה whatsapp_client_id. שמרו אותו.

2. קבלו את קוד ה-QR

   ה-webhook שלכם מקבל status=qr_generated עם תמונת ה-QR בשדה qr_image. הציגו את התמונה הזו לאדם שהטלפון שייך לו. קוד ה-QR נשלח שוב כל כמה שניות בזמן ש-Wbiztool ממתינה לסריקה, לכן הציגו תמיד את האחרון. לאדם יש כשתי דקות לסרוק. אחרי זה, או אם WhatsApp מבקש לטעון מחדש את הקוד, תקבלו not_connected; קראו שוב ל-API כדי לקבל קוד חדש.

3. סרקו אותו מתוך WhatsApp

   בטלפון, פתחו את WhatsApp ← מכשירים מקושרים (Linked devices) ← קישור מכשיר (Link a device) וסרקו את הקוד.

4. קבלו את התוצאה

   ה-webhook שלכם מקבל status=connected כשהמספר מקושר, או 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",
    "whatsapp_number": "919876543210",
    "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",
        "whatsapp_number": "919876543210",
        "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",
    whatsapp_number: "919876543210",
    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',
    'whatsapp_number' => '919876543210',
    '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 בערכים שלכם. בסעיף אימות מוסבר איפה למצוא אותם.

פרמטרי הבקשה#

שימוש בלקוחות הרשמיים#

לקוח ה-Python קורא ל-/api/v1/whatsapp-client/create/ בשבילכם.

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,
  "status": 1
}

הערך "status": 1 אומר שהבקשה נוצרה, ולא שהמספר מחובר. אם תקראו שוב ל-API עבור מספר שכבר נוסף בעבר אבל אינו מחובר, תקבלו בחזרה את אותו whatsapp_client_id וניסיון חיבור חדש יתחיל.

שגיאות#

בקשה שאינה POST מחזירה אובייקט ריק {} עם HTTP 200.

אם אותו בעל חשבון כבר הוסיף את המספר הזה בסביבת עבודה אחרת, הבקשה עלולה להיכשל עם HTTP 500. חברו את המספר מהדף הגדרות WhatsApp בסביבת העבודה הרצויה, או פנו לתמיכה.

אירועי Webhook#

מערכת Wbiztool שולחת בקשת POST ל-webhook_url שלכם בכל שלב. הגוף מקודד כטופס (application/x-www-form-urlencoded), ולא כ-JSON.

קוד ה-QR מוכן (נשלח שוב כל כמה שניות בזמן ההמתנה לסריקה, לרוב עם אותה כתובת URL):

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

המספר מחובר (יכול להישלח יותר מפעם אחת עבור אותו חיבור):

status=connected&whatsapp_client_id=678

החיבור נכשל, למשל כי קוד ה-QR לא נסרק בזמן:

status=not_connected&whatsapp_client_id=678

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

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

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

טיפים#

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