מדריך לשותפים

הלקוחות שלכם מחברים את הוואטסאפ העסקי שלהם מתוך המערכת שלכם, בלחיצה אחת. Meta שולחת את ההודעות של המספרים שלהם ישירות לשרת שלכם, ואתם שולחים בשמם ישירות מול Meta. שלח לי מטפל בחיבור מול Meta ובהרשאות, ולא עומד באמצע ההודעות.

איך זה עובד

  1. פעם אחת: אתם מגדירים בקונסולה של שלח לי את הכתובת של השרת שלכם. לשם Meta תשלח את ההודעות של כל הלקוחות שלכם.
  2. לכל לקוח: השרת שלכם מבקש מאיתנו קישור חיבור, עם המזהה של הלקוח אצלכם (ref).
  3. הלקוח לוחץ במערכת שלכם ונפתח חלון קטן, ישר על פייסבוק. שם הוא נכנס, בוחר את העסק ואת המספר, ומאשר.
  4. בסיום Meta מחזירה את החלון לכתובת שלנו לכמה שניות, בדף נקי בלי לוגו. אנחנו משלימים את החיבור מול Meta, מפנים את ההודעות של המספר לשרת שלכם, ומודיעים לדף שלכם שפתח את החלון: איזה ref חיבר איזה מספר. החלון נסגר לבד.
  5. השרת שלכם מושך מאיתנו את הטוקן של הלקוח, לפי ה-ref.
  6. מכאן והלאה ההודעות של המספר מגיעות ישר לשרת שלכם, ואתם שולחים, מורידים קבצים ומנהלים תבניות ישירות מול Meta עם הטוקן של הלקוח.

החיוב על ההודעות: Meta מחייבת את העסק של הלקוח ישירות, לפי המחירון שלה. הלקוח מוסיף אמצעי תשלום ב-WhatsApp Manager של העסק שלו. מה שעובר דרכנו הוא רק החיבור וההרשאות.

ארבעת הפרטים, ולמה כל אחד משמש

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

מהאיך הוא נראהמאיפה מקבליםלמה הוא משמש
מפתח APIshl_…בקונסולה: הגדרות ← "חיבור ל-Make ולמתכנתים"הזהות שלכם מול ה-API של שלח לי: יצירת קישורי חיבור ומשיכת המספרים והטוקנים של הלקוחות. מפתח אחד לכל הסביבה. נשאר רק בשרת שלכם.
כתובת הוובהוקhttps://your-system.example/wa/…אתם בוחרים, ומדביקים בקונסולה: הגדרות ← שותףלאן Meta שולחת את ההודעות, הסטטוסים וההיסטוריה של כל המספרים של הלקוחות שלכם. כתובת אחת לכולם. החלק הארוך והאקראי בכתובת הוא מה שמגן עליה.
verify_tokenמחרוזת אקראיתבקונסולה: הגדרות ← שותף (נוצר אוטומטית)משמש רק לבדיקת הכתובת. כשאנחנו שומרים את הכתובת, וכש-Meta מפנה אליה מספר, נשלחת לשרת בקשת GET עם הערך הזה. השרת בודק שהוא תואם ומחזיר את hub.challenge. הוא לא מופיע בהודעות עצמן (POST).
הטוקן של הלקוחEAA…מה-API שלנו: GET /v1/partner/numbersההרשאה מול Meta לחשבון הוואטסאפ של לקוח אחד: שליחת הודעות, הורדת קבצים, ניהול תבניות ופרטי המספר. כל טוקן פותח רק את הלקוח שלו. נשאר רק בשרת שלכם, ונשמר כמו סיסמה.

בקיצור: מפתח ה-API מדבר איתנו, הטוקן של הלקוח מדבר עם Meta, כתובת הוובהוק היא לאן Meta מדברת אליכם, ו-verify_token מוכיח לשרת שלכם שבקשת הבדיקה באמת מגיעה מ-Meta או מאיתנו.

לפני שמתחילים צריך סביבה בשלח לי על חבילת שותף. אנחנו מפעילים אותה, פנו ל-support@shlach.li. בקונסולה, בעמוד ההגדרות, יופיע הכרטיס "שותף".

שלב 1: השרת שלכם (כתובת הוובהוק)

צריך כתובת אחת שעונה לשני סוגי בקשות:

בקשהמתימה השרת עושה
GETבדיקת הכתובת: כששומרים אותה בקונסולה, וכש-Meta מפנה אליה מספראם hub.mode הוא subscribe ו-hub.verify_token שווה ל-verify_token שלכם: מחזיר 200 עם הערך של hub.challenge כגוף התשובה, כטקסט רגיל, בלי שום תוספת. אחרת: 403.
POSTכל אירוע: הודעה נכנסת, סטטוס, היסטוריה ועודמחזיר 200 מיד, ומעבד אחר כך, ברקע. אם התשובה מתעכבת או נכשלת, Meta שולחת שוב, ולכן מסננים כפילויות לפי id של ההודעה.

דוגמה ב-Node.js (Express):

const SECRET_PATH = "/wa/7fQ2kx9LmZr4..."      // long and random, it is what protects the address
const VERIFY_TOKEN = process.env.SHLACHLI_VERIFY_TOKEN  // from Settings → Partner

app.get(SECRET_PATH, (req, res) => {
  const ok = req.query["hub.mode"] === "subscribe" && req.query["hub.verify_token"] === VERIFY_TOKEN
  ok ? res.type("text/plain").send(req.query["hub.challenge"]) : res.sendStatus(403)
})

app.post(SECRET_PATH, express.json({limit: "5mb"}), (req, res) => {
  res.sendStatus(200)                  // answer first
  queue.push(req.body)                 // then handle it in the background
})

הגדרה בקונסולה

  1. בקונסולה: הגדרות ← שותף. מעתיקים משם את ה-verify_token לשרת שלכם.
  2. מדביקים את הכתובת ולוחצים "שמירה ובדיקה". אנחנו שולחים לשרת את אותה בקשת GET ש-Meta שולחת. אם הוא מחזיר את hub.challenge, הכתובת נשמרת.
  3. מרגע השמירה, כל מספר שכבר מחובר בסביבה מופנה לכתובת הזו, וכל מספר חדש מופנה אליה כבר ברגע החיבור.

שלב 3: הטוקן של הלקוח

מיד אחרי SHLACHLI_SIGNUP, השרת שלכם מושך את המספר של הלקוח ואת הטוקן שלו. בלי ref מקבלים את כל המספרים בסביבה.

GET /v1/partner/numbers?ref=המספרים בסביבה, כל אחד עם הטוקן שלו. עובד רק עם מפתח API.
curl "https://api.shlach.li/v1/partner/numbers?ref=customer-1042" \
  -H "Authorization: Bearer shl_XXXXXXXXXXXXXXXX"
{"data": [{
  "ref": "customer-1042",
  "ref_name": "מספרת דנה",
  "phone_number_id": "1353317711192248",
  "waba_id": "1661504035398209",
  "name": "מספרת דנה",
  "display_phone": "+972 50-123-4567",
  "status": "active",
  "token": "EAAU…",
  "coexistence": true,
  "webhook": {"url": "https://your-system.example/wa/…", "ok": true, "error": null, "at": "2026-11-16T19:42:10+00:00"},
  "history": {"until": "2026-11-17T19:41:55+00:00", "done": ["smb_app_state_sync", "history"], "error": null}
}]}
שדהמה זה
phone_number_idהמזהה של המספר אצל Meta. לפיו שולחים, ולפיו מזהים לאיזה לקוח שייכת הודעה שהגיעה לשרת.
waba_idחשבון הוואטסאפ העסקי של הלקוח. לפיו מנהלים תבניות.
tokenהטוקן של הלקוח מול Meta. שומרים אותו מוצפן, ליד ה-ref.
statusactive, או disconnected אם הלקוח ניתק את המספר. במצב הזה הטוקן כבר לא עובד, וצריך לחבר את המספר מחדש.
coexistencetrue אם המספר ממשיך לעבוד גם באפליקציית WhatsApp Business בטלפון.
webhookלאן ההודעות של המספר מופנות. ok: true אומר ש-Meta אישרה שהן מגיעות לכתובת שלכם. אם לא, error מסביר למה.
historyרק במספר שממשיך לעבוד גם בטלפון: אילו בקשות כבר נשלחו ל-Meta (smb_app_state_sync לאנשי קשר, history לשיחות), ועד מתי אפשר לבקש שוב (until).

מה מגיע לשרת שלכם

Meta שולחת לכתובת שלכם את האירועים של המספרים בפורמט שלה, כמו שהוא, בלי שום שינוי מצדנו. סוג האירוע כתוב ב-entry[].changes[].field:

fieldמה יש בו
messagesvalue.messages[]: הודעות נכנסות מהלקוחות של הלקוח שלכם (טקסט, תמונה, הקלטה, וידאו, מסמך, מדבקה, מיקום, איש קשר, לחיצה על כפתור). value.statuses[]: מה קרה להודעות ששלחתם (sent, delivered, read, failed).
smb_message_echoesהודעות שבעל העסק שלח בעצמו מאפליקציית WhatsApp Business בטלפון. מגיע רק במספר שממשיך לעבוד גם בטלפון.
historyשיחות העבר מהאפליקציה בטלפון, בכמה חלקים. ההתקדמות מופיעה ב-phase וב-progress. מגיע פעם אחת.
smb_app_state_syncאנשי הקשר מהאפליקציה בטלפון.

לאיזה לקוח שייך כל אירוע: לפי value.metadata.phone_number_id, ואם הוא חסר, לפי entry[].id, שהוא ה-waba_id. את שניהם קיבלתם בשלב 3.

{"object": "whatsapp_business_account",
 "entry": [{"id": "1661504035398209", "changes": [{"field": "messages", "value": {
   "messaging_product": "whatsapp",
   "metadata": {"display_phone_number": "972501234567", "phone_number_id": "1353317711192248"},
   "contacts": [{"profile": {"name": "רונית"}, "wa_id": "972501112233"}],
   "messages": [{"from": "972501112233", "id": "wamid.HBgM…", "timestamp": "1794852576", "type": "text",
                 "text": {"body": "היי, אפשר לקבוע תור למחר?"}}]}}]}]}

מה לא מגיע אליכם: עדכונים על אישור תבניות, עדכוני חשבון ושינויים בדירוג האיכות ובמגבלות השליחה. Meta שולחת אותם לאפליקציה שלנו, לא למספר. את הסטטוס של תבנית בודקים ישירות מול Meta (ראו בהמשך).

שליחה, קבצים ותבניות

הכול ישירות מול ה-API של Meta (https://graph.facebook.com/v24.0), עם הטוקן של הלקוח בכותרת Authorization: Bearer.

שליחת הודעה

curl -X POST "https://graph.facebook.com/v24.0/1353317711192248/messages" \
  -H "Authorization: Bearer EAAU…" -H "Content-Type: application/json" \
  -d '{"messaging_product": "whatsapp", "to": "972501112233", "type": "text", "text": {"body": "בטח, מחר ב-10:00 פנוי"}}'

הכלל של וואטסאפ: הודעה חופשית אפשר לשלוח רק תוך 24 שעות מההודעה האחרונה של הלקוח. אחרי זה רק תבנית מאושרת ("type": "template"). התשובה מ-Meta כוללת messages[0].id, והסטטוסים של ההודעה יגיעו לשרת שלכם עם אותו id.

הורדת קבצים

  1. בהודעה עם קובץ יש מזהה, למשל image.id.
  2. GET https://graph.facebook.com/v24.0/{media_id} עם הטוקן מחזיר url, mime_type ו-file_size.
  3. מורידים את ה-url עם אותה כותרת Authorization: Bearer. הכתובת בתוקף לכמה דקות בלבד.

Meta שומרת את הקבצים לזמן מוגבל (7 ימים), אז שומרים אותם אצלכם ברגע שההודעה מגיעה.

תבניות

יצירה: POST /{waba_id}/message_templates. רשימה וסטטוס: GET /{waba_id}/message_templates. עדכוני אישור לא נשלחים לשרת שלכם, ולכן בודקים את הסטטוס בקריאה הזו: Meta בדרך כלל מאשרת תוך דקות, ולפעמים עד 24 שעות.

היסטוריה ואנשי קשר: מספר שממשיך לעבוד גם בטלפון

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

אבטחה

גבולות ושאלות

בדיקה מקצה לקצה

  1. השרת עונה לבדיקה. הפקודה הזו צריכה להחזיר בדיוק 12345:
    curl "https://your-system.example/wa/7fQ2kx9LmZr4...?hub.mode=subscribe&hub.verify_token=YOUR_VERIFY_TOKEN&hub.challenge=12345"
  2. בקונסולה, בהגדרות ← שותף: הדביקו את הכתובת ולחצו "שמירה ובדיקה".
  3. צרו קישור עם ref של לקוח בדיקה, וחברו מספר אמיתי דרך החלון.
  4. ודאו שהדף שלכם קיבל SHLACHLI_SIGNUP, ושב-GET /v1/partner/numbers מופיעים token ו-"webhook": {"ok": true}.
  5. שלחו למספר הודעה, תמונה והקלטה מטלפון אחר, וודאו שהן מגיעות לשרת ושהקבצים יורדים.
  6. ענו עם הטוקן, וודאו שהסטטוסים sent, delivered ו-read מגיעים לשרת.