דלגו לתוכן
Wbiztool

מדריכי מוצר

Webhooks להודעות נכנסות (מאזינים)

מאזין (listener) מחבר את אחד ממספרי ה-WhatsApp שלכם ל-Unibox ויכול לשלוח לשרת שלכם Webhook על הודעות נכנסות. במרכז הבקרה מנהלים את המאזינים בדף Incoming Triggers (טריגרים נכנסים). ברגע שמספר הופך למאזין, הצ'אטים שלו מסונכרנים אל תיבת הדואר הנכנס של Unibox, ואם תוסיפו כתובת Webhook, המערכת של Wbiztool תשלח כל הודעה חדשה לשרת שלכם. השתמשו ב-Webhooks כדי לתעד שיחות במערכת CRM, להתריע לצוות או לבנות מענה אוטומטי.

לפני שמתחילים#

  • חבילת התוספת Unibox. היא עולה 20$ לחודש או 200$ לשנה לכל מספר WhatsApp, ומספר המאזינים שאפשר להגדיר שווה לכמות של חבילת התוספת. רכשו אותה תחת Available Add-ons (חבילות תוספת זמינות) בדף Billing & Plans (חיובים ותוכניות) בתוך מרכז הבקרה. בלעדיה, הדף Incoming Triggers עדיין נפתח, אבל לחיצה על Add New Listener (הוספת מאזין חדש) מציגה Unibox Add-on Required (נדרשת חבילת התוספת Unibox) עם הכפתור Subscribe to Unibox Add-on (הרשמה לחבילת התוספת Unibox).
  • מספר WhatsApp מחובר בדף WhatsApp settings (הגדרות WhatsApp). אפשר להוסיף רק מספרים מחוברים שעדיין אינם מאזינים.
  • עליכם להיות בעלים או עורכים בסביבת העבודה.
  • עבור Webhooks: כתובת URL ציבורית (השתמשו ב-https) באורך של 100 תווים לכל היותר, שמקבלת בקשות POST עם גוף JSON.

הוספת מאזין#

  1. פתיחת Incoming Triggers

    בסרגל הצד פתחו את Unibox ולחצו על Incoming Triggers, או עברו אל Incoming Triggers.

  2. התחלת מאזין חדש

    לחצו על הכרטיס Add New Listener.

  3. בחירת המספר

    בחרו אותו ב-Select WhatsApp Number (בחירת מספר WhatsApp). אם ברשימה מופיע No available WhatsApp numbers (אין מספרי WhatsApp זמינים), כל מספר מחובר כבר משמש כמאזין, או שאין אף מספר מחובר.

  4. הוספת Webhook (אופציונלי)

    הזינו את Webhook URL (Optional) (כתובת Webhook, אופציונלי). אחרי שמקלידים כתובת, מופיע Webhook Events (אירועי Webhook): השאירו מסומנים את Incoming Messages (הודעות נכנסות), את Outgoing Messages (הודעות יוצאות) או את שניהם. אפשר להוסיף או לשנות את הכתובת מאוחר יותר.

  5. שמירה

    לחצו על Add Listener (הוספת מאזין). המאזין מופיע ככרטיס עם הסטטוס Active (פעיל). אם הזנתם כתובת, נוצר עבורה סוד Webhook.

ניהול מאזינים#

כל כרטיס מציג את המספר, את הסטטוס שלו, את Webhook URL: (כתובת Webhook, או Not configured – לא מוגדרת), את Last Activity: (פעילות אחרונה: מתי נבדקו לאחרונה הודעות במספר, או Never – אף פעם) ואת Webhook Secret: (סוד Webhook), שמוסתר עד שלוחצים על כפתור העין.

פתחו את התפריט בכרטיס כדי:

פעולהמה קורה
Edit (עריכה)שינוי כתובת ה-Webhook, אירועי ה-Webhook או הסוד. אי אפשר לשנות את המספר.
Disable (השבתה) / Enable (הפעלה)השבתה מעבירה את המאזין לסטטוס Inactive (לא פעיל): המספר מפסיק להסתנכרן לתיבת הדואר הנכנס ולא נשלחים Webhooks. הפעלה מחזירה אותו לסטטוס Active.
Delete (מחיקה)מסירה את המאזין אחרי אישור. שיחות שכבר נמצאות בתיבת הדואר הנכנס נשארות. הוספה מחדש של אותו מספר בהמשך משחזרת את המאזין. אם תזינו כתובת Webhook כשאתם מוסיפים אותו מחדש, המאזין שומר את סוד ה-Webhook הקודם שלו, אם היה לו, במקום לקבל סוד חדש.

סטטוסים של מאזין#

סטטוסמשמעות
Activeהודעות מסתנכרנות ו-Webhooks נשלחים כל עוד המספר מחובר.
Pending (ממתין)המספר לא היה מחובר כשהמאזין נוצר, למשל על ידי Zapier. לחצו על Enable אחרי שהמספר מתחבר.
Inactiveמושבת. שום דבר לא מסתנכרן ולא נשלחים Webhooks.

נתונים#

כרטיסמה הוא מציג
Active Listeners (מאזינים פעילים)כל המאזינים בדף, כולל מושבתים.
Available Numbers (מספרים זמינים)מספרים מחוברים שעדיין אינם מאזינים. מספרים שמחקתם את המאזין שלהם עדיין נספרים כאן כתפוסים, כך שהערך עשוי להיות נמוך ממה שאפשר להוסיף בפועל.
Total Limit (מגבלה כוללת)כמה מאזינים חבילת התוספת Unibox שלכם מתירה.
Messages Today (הודעות היום)עדיין לא נמדד; תמיד מציג 0.

שינוי כתובת ה-Webhook או האירועים#

  1. פתיחת המאזין

    לחצו על בכרטיס, ולאחר מכן על Edit.

  2. עדכון ההגדרות

    שנו את Webhook URL (Optional) ואת Webhook Events. מחקו את הכתובת כדי להפסיק Webhooks עבור המספר הזה: גם הסוד שלו נמחק, וסוד חדש ייווצר אם תוסיפו כתובת שוב.

  3. שמירה

    לחצו על Update Listener (עדכון מאזין).

יצירת סוד חדש#

בחלון Edit Listener (עריכת מאזין) לחצו על כפתור הרענון שליד Webhook Secret ואשרו. הסוד החדש נשמר מיד, גם אם תסגרו אחר כך את החלון בלי ללחוץ על Update Listener, ומאותו רגע הבקשות נחתמות איתו. עדכנו מיד את השרת שלכם עם הסוד החדש.

איך Webhooks נשלחים#

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

  • אירועים: האירוע message_received עבור הודעות שאנשים שולחים למספר שלכם, והאירוע message_sent עבור הודעות שנשלחות ממנו (מהטלפון, מקמפיינים או מה-API). נשלחים רק האירועים שמסומנים ב-Webhook Events.
  • תשובות מתיבת הדואר הנכנס של Unibox בדרך כלל לא מפעילות את message_sent, כי הן כבר נמצאות בתיבה כשהסנכרון רץ.
  • תגובה: השיבו עם HTTP 200 תוך 8 שניות. כל תגובה אחרת או חריגה מהזמן נחשבות למסירה שנכשלה.
  • אין ניסיונות חוזרים: כל הודעה נשלחת פעם אחת. אם השרת שלכם לא זמין, ה-Webhook הזה אובד.
  • סדר: הבקשות נשלחות בנפרד זו מזו ועלולות להגיע שלא לפי הסדר. מיינו לפי message.timestamp אם הסדר חשוב.

כותרות#

כותרתערך
Content-Typeapplication/json
X-Wbiztool-Eventmessage_received או message_sent
X-Wbiztool-Timestampמתי ה-Webhook נשלח, בפורמט ISO 8601 ב-UTC. זהה ל-timestamp בגוף הבקשה.
X-Wbiztool-Webhook-Idהמזהה של המאזין. זהה ל-webhook_id בגוף הבקשה.
X-Wbiztool-Signatureהקידומת sha256= ואחריה החתימה. נשלחת בכל פעם שלמאזין יש סוד, וזה תמיד המצב כשמוגדרת כתובת.

גוף ה-Webhook (payload)#

דוגמאות לגוף של Webhook
{
  "event": "message_received",
  "timestamp": "2026-09-16T10:31:12.482913+00:00",
  "webhook_id": 42,
  "whatsapp_client_id": "678",
  "whatsapp_phone": "919812345678",
  "message": {
    "id": "[email protected]_3EB0C1A2B3D4E5F60718",
    "type": "chat",
    "content": "Hi, is my order #4821 out for delivery?",
    "from": "919876543210",
    "from_name": "Aman",
    "to": "919812345678",
    "timestamp": "2026-09-16T10:29:58+00:00",
    "whatsapp_timestamp": 1789554598,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "919876543210",
    "name": "Aman",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Acme Stores"
  }
}

המספרים, המזהים והשמות שלמעלה הם דוגמאות בלבד.

שדות ברמה העליונה#

שדהסוגתיאור
eventstringmessage_received או message_sent.
timestampstringמתי ה-Webhook נשלח (ISO 8601, UTC).
webhook_idintegerהמזהה של המאזין.
whatsapp_client_idstringהמזהה של מספר ה-WhatsApp שלכם, כפי שהוא מוצג בדף WhatsApp settings.
whatsapp_phonestringמספר ה-WhatsApp שלכם.
messageobjectההודעה. ראו בהמשך.
contactobjectהאדם או הקבוצה שאיתם מתנהלת השיחה. ראו בהמשך.
organisationobjectהשדות id (string) ו-name של סביבת העבודה שלכם.
groupobjectרק בצ'אטים קבוצתיים: name, שם הקבוצה.

השדות של message#

שדהסוגתיאור
idstringהמזהה של WhatsApp להודעה. השתמשו בו כדי להתעלם מכפילויות.
typestringהערך chat עבור טקסט. אחרת, הסוג של WhatsApp, כמו image, video, audio, ptt (הודעה קולית), document, sticker או location.
contentstringהטקסט בהודעות chat. במדיה מופיעה במקומו תווית: 📸 Image, 🎥 Video, 🎵 Audio, 🎤 Voice Message, 😊 Sticker, Document: ואחריו הטקסט של המסמך (Document כשאין טקסט), או שם הסוג באות ראשונה גדולה בכל מקרה אחר, כמו Location. כיתובים לא נכללים.
fromstringתמיד המספר של איש הקשר (או המזהה של הקבוצה), בשני הכיוונים.
from_namestringהשם של איש הקשר או של הקבוצה. יכול להיות ריק.
tostringתמיד מספר ה-WhatsApp שלכם, בשני הכיוונים.
timestampstringמתי ההודעה נשלחה ב-WhatsApp (ISO 8601, UTC).
whatsapp_timestampintegerאותו זמן כחותמת זמן Unix בשניות.
directionstringincoming או outgoing. השתמשו בשדה הזה, ולא ב-from וב-to, כדי לזהות את הכיוון.
statusstringכרגע תמיד pending. אל תסתמכו עליו לסטטוס מסירה או קריאה.
is_forwardedbooleanהאם ההודעה הועברה.
forwarding_scoreintegerכמה פעמים היא הועברה.
mediaobjectבהודעות מדיה, כשהפרטים זמינים: filename, mimetype ו-size בבייטים. הקובץ עצמו לא נכלל.
quoted_message_idstringרק כשההודעה היא תשובה להודעה אחרת.

השדות של contact#

שדהסוגתיאור
whatsapp_idstringמזהה ה-WhatsApp, כמו [email protected] עבור אדם או …@g.us עבור קבוצה.
phonestringהמספר בלי +, או המזהה של הקבוצה עבור קבוצות.
namestringהשם ש-Wbiztool שמרה לאיש הקשר, או שם הקבוצה. יכול להיות ריק.
is_groupbooleanהערך true עבור צ'אטים קבוצתיים.
is_businessbooleanהערך true עבור חשבונות WhatsApp Business, כשהדבר ידוע.

אימות החתימה#

כל בקשה נחתמת בסוד של המאזין שלכם באמצעות HMAC-SHA256. החתימה מחושבת על גוף הבקשה הגולמי, בדיוק כפי שהתקבל, ונשלחת בכותרת X-Wbiztool-Signature כ-sha256= ואחריו ה-digest ההקסדצימלי באותיות קטנות.

חשבו תמיד את החתימה מהבייטים הגולמיים לפני פענוח ה-JSON. פענוח הגוף וקידודו מחדש משנים אותו (למשל, תווים שאינם באנגלית ואימוג'י מגיעים בצורה מוברחת כ-\uXXXX), והחתימה לא תתאים.

// Express: keep the raw body for this route
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WBIZTOOL_WEBHOOK_SECRET;

app.post("/wbiztool/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Wbiztool-Signature") || "";

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send("Invalid signature");

  const data = JSON.parse(req.body.toString("utf8"));
  if (data.event === "message_received") {
    console.log(`New message from ${data.contact.phone}: ${data.message.content}`);
  }
  res.sendStatus(200); // reply quickly; do slow work in the background
});

app.listen(3000);

החתימה לא מכסה את כותרת חותמת הזמן, ולכן היא לא מגינה מפני שליחה חוזרת (replay) של בקשה. אם זה חשוב לכם, שמרו כל message.id שכבר עיבדתם והתעלמו מחזרות.

פתרון בעיות#

הודעה או בעיהמה לעשות
Unibox Add-on Required כשלוחצים על Add New Listenerלסביבת העבודה שלכם אין את חבילת התוספת Unibox. רכשו אותה תחת Available Add-ons בדף Billing & Plans בתוך מרכז הבקרה.
You have reached your unibox numbers limitמחקו מאזין שאינכם צריכים עוד, או הגדילו את הכמות של חבילת התוספת.
No available WhatsApp numbersחברו מספר נוסף, או שהמספר כבר משמש כמאזין.
This WhatsApp number is already a listenerערכו במקום זאת את הכרטיס הקיים.
Invalid WhatsApp clientהמספר התנתק. חברו אותו מחדש בדף WhatsApp settings וטענו את הדף מחדש.
שגיאה שמזכירה value too long בזמן שמירהכתובת ה-Webhook ארוכה מ-100 תווים. השתמשו בכתובת קצרה יותר.
לא מגיעים Webhooksודאו שהמאזין Active, שהמספר מחובר, שסוג האירוע מסומן ושהכתובת שלכם היא https ציבורית עם תעודה תקפה. ההודעות נשלחות רק אחרי הסנכרון הבא, כמה דקות לאחר מכן.
חלק מה-Webhooks חסריםהשרת שלכם החזיר משהו שאינו 200, לקח לו יותר מ-8 שניות להגיב או שלא היה זמין. מסירות שנכשלו לא נשלחות שוב.
החתימה לא תואמתהשתמשו בגוף הגולמי, ולא ב-JSON שקודד מחדש, ובסוד הנוכחי. יצירת סוד חדש, או חיבור Zapier, מחליפים אותו.
הנתון Last Activity: מציג Neverהמספר עדיין לא נבדק. הוא חייב להיות מחובר ולא עסוק בשליחת הודעות.

מדריכים קשורים#