ממשק API לשליחה למספרים מרובים

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

מערכת WbizTool יוצרת הודעה אחת לכל נמען ומחזירה msg_id לכל אחת, כך שאפשר לבדוק את הסטטוס שלהן בנפרד.

דוגמה מהירה#

curl -X POST https://wbiztool.com/api/v1/send_msg/multi/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210,9812345670,Sales Team Mumbai",
    "msg": "Our Diwali sale starts tomorrow. Get 20% off on all orders!"
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/send_msg/multi/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "whatsapp_client": 678,
        "msg_type": 0,
        "country_code": "91",
        "phone": ",".join(["9876543210", "9812345670", "Sales Team Mumbai"]),
        "msg": "Our Diwali sale starts tomorrow. Get 20% off on all orders!",
    },
    timeout=60,
)
result = response.json()  # read the body even when the HTTP code is 400

if result.get("status") == 1:
    for item in result["messages"]:
        print(item["contact"], "->", item["msg_id"])
else:
    print("Failed:", result.get("message", "no message in response"))

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/multi/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: 12345,
    api_key: "YOUR_API_KEY",
    whatsapp_client: 678,
    msg_type: 0,
    country_code: "91",
    phone: ["9876543210", "9812345670", "Sales Team Mumbai"].join(","),
    msg: "Our Diwali sale starts tomorrow. Get 20% off on all orders!",
  }),
});
const result = await response.json(); // read the body even when the HTTP code is 400

if (result.status === 1) {
  for (const item of result.messages) {
    console.log(item.contact, "->", item.msg_id);
  }
} else {
  console.error("Failed:", result.message ?? "no message in response");
}

<?php
$payload = [
    'client_id'       => 12345,
    'api_key'         => 'YOUR_API_KEY',
    'whatsapp_client' => 678,
    'msg_type'        => 0,
    'country_code'    => '91',
    'phone'           => implode(',', ['9876543210', '9812345670', 'Sales Team Mumbai']),
    'msg'             => 'Our Diwali sale starts tomorrow. Get 20% off on all orders!',
];

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

if (($result['status'] ?? 0) === 1) {
    foreach ($result['messages'] as $item) {
        echo $item['contact'] . ' -> ' . $item['msg_id'] . PHP_EOL;
    }
} else {
    echo 'Failed: ' . ($result['message'] ?? 'no message in response');
}

החליפו את 12345, YOUR_API_KEY ו-678 בערכים שלכם. בסעיף אימות מוסבר איפה למצוא אותם.

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

curl -X POST https://wbiztool.com/api/v1/send_msg/multi/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 1,
    "country_code": "91",
    "phone": "9876543210,9812345670",
    "img_url": "https://example.com/offers/diwali-sale.jpg",
    "msg": "Our Diwali sale starts tomorrow."
  }'

איך הנמענים מזוהים#

מערכת WbizTool מפצלת את phone לפי פסיקים, מסירה רווחים סביב כל פריט ואז מחליטה מה כל פריט:

• מספרי טלפון אפשר לכתוב כמו שהם אצלכם: ‎+91 98765 43210, ‏‎98765-43210, ‏‎(987) 654-3210, ‏‎0091 98765 43210 ו-‎+44 (0)20 7946 0018 עובדים כולם, וגם ערכים מגיליון כמו 919876543210.0 ו-9.19876543210E+11.
• country_code מתווספת אלא אם המספר כבר מתחיל בה או נכתב עם + או 00: ‎+44 20 7946 0018 עם country_code 91 נשאר 442079460018. לכן אפשר לערבב ברשימה אחת מספרים מכמה מדינות: כתבו את המספרים של המדינות האחרות עם +.
• מספר מקומי שנכתב עם ה-0 המוביל שלו עובד גם הוא: 09876543210 עם country_code 91 נשלח אל 919876543210, ו-0612345678 עם 39 (איטליה, שבה ה-0 הוא חלק מהמספר) נשלח אל 390612345678.
• אחרי הוספת קידומת המדינה, מספר חייב להיות באורך של 7 עד 15 ספרות.
• טקסט עם אותיות או סימנים אחרים, כמו Sales Team Mumbai או Family 2024, מטופל כשם של קבוצת WhatsApp, שמאותרת באותה דרך כמו ב-שליחה לקבוצה.
• שם קבוצה בלי אותיות, כמו ‎2024-2025, נקרא כמספר טלפון, אלא אם יש בו פחות מ-10 ספרות וסביבת העבודה שלכם כבר שלחה הודעה לקבוצה בדיוק בשם הזה (היא מופיעה תחת קבוצות באנשי קשר). שם קצר עם פחות מ-7 ספרות ועם מקף, נקודה או סוגריים, כמו ‎2024-25 או ‎(2024), הוא תמיד שם קבוצה. אי אפשר לשלוח מה-endpoint הזה לקבוצות ששמן מכיל פסיקים. לקבוצות כאלה השתמשו ב-שליחה לקבוצה.
• מחשבון Telegram, ‎@username, קישור t.me/username או tg:<id> הם אדם ולא שם של קבוצה, ומספר טלפון נשלח לאותו אדם ב-Telegram. ממספר WhatsApp, שמות משתמש, קישורי t.me ו-tg:<id> מדולגים.

דברים נוספים שכדאי לדעת:

• מספרים קצרים מדי או ארוכים מדי אחרי הוספת קידומת המדינה, ערכים מעוגלים מגיליון ופריטים שהם רק אפסים (0, 00) מדולגים בשקט. הם לא מופיעים בתגובה ולא מקבלים msg_id.
• כפילויות לא מוסרות. מספר שמופיע פעמיים מקבל שתי הודעות.
• אם מספר מקומי מתחיל במקרה באותן ספרות כמו country_code (למשל 9123456780 עם country_code 91), הקידומת לא מתווספת. שלחו מספרים כאלה כשקידומת המדינה כבר כלולה בהם (919123456780).
• כתובות URL של תמונות וקבצים לא נבדקות כשאתם קוראים ל-API. הן מורדות בזמן שליחת כל הודעה, כך שקישור שבור גורם להודעות להיכשל מאוחר יותר, ולא לבקשה עצמה. חלים אותם כללים של זמן שליחה כמו בשליחת הודעה: תמונות מעל 16 MB וסרטונים מעל 64 MB נכשלים, אי אפשר לשלוח אודיו WAV ו-OGG כתמונה (msg_type 1), ולקבצים (msg_type 2) בלי סיומת, או עם סיומת שלא נתמכת, מתווסף ‎.pdf. ראו שליחת תמונות וקבצים.

מגבלות הודעות#

לפני שנוצר משהו, כל האצווה נבדקת, כך שרשימה אף פעם לא נשלחת באופן חלקי. כל פריט לא ריק ב-phone נספר, כולל פריטים שמדולגים בהמשך, וגם הודעות שנמצאות בתור אבל עוד לא נשלחו נספרות.

• כל תוכנית: האצווה חייבת להיכנס במגבלת השימוש ההוגן היומית של המספר השולח – 1,000 הודעות בכל 24 שעות. אחרת לא נוצרת אף הודעה ומתקבלת התגובה:

{
  "message": "Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow. 1200 messages requested, 640 more can go out from this number in the next 24 hours.",
  "code": "daily_limit_reached",
  "status": 0
}

• תוכנית חינמית: האצווה חייבת להיכנס גם בהודעות החינמיות שנותרו לסביבת העבודה (50 בכל 30 יום). אחרת מתקבלת התגובה:

{
  "message": "Not enough credits: 120 messages requested, 35 credits remaining",
  "status": 0
}

פצלו רשימות גדולות על פני כמה מספרים או ימים. לקמפיינים גדולים, העלו במקום זאת גיליון אלקטרוני מהדף Campaigns (קמפיינים).

תגובה#

בקשה מוצלחת מחזירה HTTP 200:

{
  "msg_ids": [9817263, 9817264, 9817265],
  "messages": [
    { "msg_id": 9817263, "contact": "919876543210", "is_group": false },
    { "msg_id": 9817264, "contact": "919812345670", "is_group": false },
    { "msg_id": 9817265, "contact": "Sales Team Mumbai", "is_group": true }
  ],
  "message": "Successfully created 3 messages",
  "status": 1
}

השוו את messages לרשימה ששלחתם כדי למצוא מספרים שדולגו, ובדקו שהערך של is_group הוא false בכל פריט שהתכוונתם אליו כמספר טלפון.

שגיאות#

רוב השגיאות מחזירות HTTP 200 עם status שמוגדר ל-0, לכן תמיד בדקו את status בגוף התגובה. מלבד שגיאות HTTP 400 ו-403, התגובות (כולל תגובות מוצלחות) הן JSON שנשלח עם Content-Type: text/html, לכן פענחו את הגוף בעצמכם ואל תסתמכו על זיהוי JSON אוטומטי (למשל בכלי no-code):

{ "message": "Invalid whatsapp client", "status": 0 }

טיפים#

• שלחו את phone כמחרוזת: חברו את הרשימה שלכם בפסיקים. מערך JSON מחזיר {}.
• אל תשתמשו כרגע ב-send_bulk_messages של לקוח ה-Python: הוא שולח את הרשימה בתור phones, וה-endpoint הזה מתעלם מזה. קראו ל-endpoint ישירות, כמו בדוגמאות שלמעלה.
• עקבו אחרי כל הודעה: שמרו כל msg_id מתוך messages, או העבירו webhook כדי לקבל התראה כשכל הודעה נשלחת, נכשלת, מבוטלת או פגה.
• השאירו את המספר מחובר: כל הודעה נשלחת ממספר ה-WhatsApp שלכם, ולכן הוא חייב להישאר מחובר בהגדרות WhatsApp עד שכל האצווה יוצאת.
• טקסט שונה לכל אדם: ה-endpoint הזה שולח את אותו msg לכולם. כדי להתאים אישית כל הודעה, קראו ל-שליחת הודעה פעם אחת לכל נמען.