מדריך לשותפים
הלקוחות שלכם מחברים את הוואטסאפ העסקי שלהם מתוך המערכת שלכם, בלחיצה אחת. Meta שולחת את ההודעות של המספרים שלהם ישירות לשרת שלכם, ואתם שולחים בשמם ישירות מול Meta. שלח לי מטפל בחיבור מול Meta ובהרשאות, ולא עומד באמצע ההודעות.
איך זה עובד
- פעם אחת: אתם מגדירים בקונסולה של שלח לי את הכתובת של השרת שלכם. לשם Meta תשלח את ההודעות של כל הלקוחות שלכם.
- לכל לקוח: השרת שלכם מבקש מאיתנו קישור חיבור, עם המזהה של הלקוח אצלכם (
ref). - הלקוח לוחץ במערכת שלכם ונפתח חלון קטן, ישר על פייסבוק. שם הוא נכנס, בוחר את העסק ואת המספר, ומאשר.
- בסיום Meta מחזירה את החלון לכתובת שלנו לכמה שניות, בדף נקי בלי לוגו. אנחנו משלימים את החיבור מול Meta, מפנים את ההודעות של המספר לשרת שלכם, ומודיעים לדף שלכם שפתח את החלון: איזה
refחיבר איזה מספר. החלון נסגר לבד. - השרת שלכם מושך מאיתנו את הטוקן של הלקוח, לפי ה-
ref. - מכאן והלאה ההודעות של המספר מגיעות ישר לשרת שלכם, ואתם שולחים, מורידים קבצים ומנהלים תבניות ישירות מול Meta עם הטוקן של הלקוח.
החיוב על ההודעות: Meta מחייבת את העסק של הלקוח ישירות, לפי המחירון שלה. הלקוח מוסיף אמצעי תשלום ב-WhatsApp Manager של העסק שלו. מה שעובר דרכנו הוא רק החיבור וההרשאות.
ארבעת הפרטים, ולמה כל אחד משמש
יש כאן ארבעה פרטים שונים. כדאי להבין מה כל אחד עושה, כי כל אחד מהם נשמר במקום אחר ומשמש לדבר אחר.
| מה | איך הוא נראה | מאיפה מקבלים | למה הוא משמש |
|---|---|---|---|
| מפתח API | shl_… | בקונסולה: הגדרות ← "חיבור ל-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
})
הגדרה בקונסולה
- בקונסולה: הגדרות ← שותף. מעתיקים משם את ה-verify_token לשרת שלכם.
- מדביקים את הכתובת ולוחצים "שמירה ובדיקה". אנחנו שולחים לשרת את אותה בקשת GET ש-Meta שולחת. אם הוא מחזיר את
hub.challenge, הכתובת נשמרת. - מרגע השמירה, כל מספר שכבר מחובר בסביבה מופנה לכתובת הזו, וכל מספר חדש מופנה אליה כבר ברגע החיבור.
- הכתובת חייבת להיות
httpsציבורית, עד 200 תווים. - כדאי להגדיר את הכתובת לפני שהלקוח הראשון מתחבר. אחרת ההודעות הראשונות שלו יגיעו אלינו, וההיסטוריה שלו תחכה עד שהכתובת תוגדר (ראו היסטוריה ואנשי קשר).
- החלפת כתובת: מדביקים כתובת חדשה ושומרים, וכל המספרים עוברים אליה. שדה ריק מחזיר את ההודעות לשלח לי.
- פעם בשעה אנחנו מוודאים שכל מספר מופנה לכתובת הנכונה, ומתקנים אם צריך. אם חבילת השותף מסתיימת, ההודעות חוזרות אלינו.
שלב 2: חיבור לקוח
2א. השרת שלכם מבקש קישור
POST /v1/signup-links | קישור חד-פעמי לחיבור מספר אחד, בתוקף לשעה. |
| שדה | מה זה |
|---|---|
ref | המזהה של הלקוח אצלכם, עד 100 תווים. הוא יופיע על המספר, ולפיו מושכים את הטוקן. |
name | שם הלקוח, לזיהוי אצלכם: מופיע ליד המספר ב-GET /v1/partner/numbers (ref_name) ובקונסולה. עד 80 תווים. |
return_url | כתובת https במערכת שלכם. חייבת להיות באותו דומיין (origin) כמו הדף שפותח את החלון, כי ההודעה על סיום החיבור נשלחת רק לדומיין הזה. בלי return_url אין הודעה על הסיום. |
curl -X POST https://api.shlach.li/v1/signup-links \
-H "Authorization: Bearer shl_XXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{"ref": "customer-1042", "name": "מספרת דנה", "return_url": "https://your-system.example/whatsapp/done"}'
{"url": "https://www.facebook.com/v24.0/dialog/oauth?client_id=…&state=shs_…", "ref": "customer-1042", "expires_in": 3600}
ה-url הוא ישר החיבור של פייסבוק. פותחים אותו כמו שהוא, בלי לשנות בו דבר.
שגיאות: 402 אם הסביבה לא על חבילת שותף או שאין בה מקום למספר נוסף, ו-400 אם return_url לא כתובת https תקינה.
2ב. הדף שלכם פותח את החלון
מפתח ה-API נשאר בשרת. הדפדפן מבקש קישור מהשרת שלכם, ופותח אותו בחלון קטן. את החלון פותחים מיד בלחיצה, לפני שהקישור חוזר, אחרת הדפדפן יחסום אותו כחלון קופץ:
connectButton.onclick = async () => {
const w = window.open("", "shlachli_signup", "width=520,height=780") // on the click itself
const {url} = await fetch("/api/whatsapp/link?customer=1042").then(r => r.json()) // your server → POST /v1/signup-links
w.location = url
}
window.addEventListener("message", async e => {
if (e.origin !== "https://app.shlach.li" || e.data?.type !== "SHLACHLI_SIGNUP") return
// e.data = {type: "SHLACHLI_SIGNUP", status: "connected", ref, phone_number_id, waba_id}
await fetch("/api/whatsapp/connected", {method: "POST", headers: {"Content-Type": "application/json"},
body: JSON.stringify({ref: e.data.ref})}) // your server pulls the token (step 3)
})
2ג. מה הלקוח רואה
- החלון נפתח ישר על פייסבוק. הלקוח נכנס עם החשבון שמנהל את העסק, בוחר או יוצר עסק, ובוחר מספר: מספר שכבר עובד עם אפליקציית WhatsApp Business בטלפון (וממשיך לעבוד בה), או מספר חדש שמאמתים בקוד ב-SMS או בשיחה.
- Meta מחזירה את החלון לכתובת שלנו (
app.shlach.li) לכמה שניות. הדף נקי, בלי לוגו ובלי שם מערכת: "מחברים את המספר…" ואז "החיבור הושלם!". הדף שלכם מקבל אתSHLACHLI_SIGNUP, והחלון נסגר לבד אחרי כשתי שניות.
בחלון של פייסבוק, Meta מציגה את shlach.li כעסק שמבקש גישה לחשבון הוואטסאפ. זה קבוע ולא תלוי בנו: החיבור עובר דרך האפליקציה שלנו ב-Meta, שבזכותה הלקוחות שלכם מתחברים בלי שתצטרכו אישור משלכם מ-Meta.
- אם החלון נפתח כלשונית רגילה ולא מתוך הדף שלכם (למשל קישור שנשלח ללקוח בהודעה), אין לו לאן לשלוח הודעה. במקום זה, בסיום הוא עובר ל-
return_urlעם הפרמטריםstatus,ref,phone_number_idו-waba_id. - אם הלקוח ביטל בפייסבוק, החלון מציג "החיבור לא הושלם" וכפתור "לנסות שוב". אם סגר את החלון, אתם לא מקבלים כלום. הקישור נשאר בתוקף עד שהוא משמש לחיבור, או עד שעברה שעה.
- קישור שפג תוקפו או שכבר שימש נעצר רק בסוף, אחרי פייסבוק, עם הודעה בעברית. לכן יוצרים קישור חדש בכל לחיצה ולא שומרים קישורים לשימוש חוזר.
SHLACHLI_SIGNUPוה-return_urlהם רק סימן שאפשר להמשיך. ההוכחה היא ה-API: את הטוקן ואת מצב המספר לוקחים תמיד מ-GET /v1/partner/numbers.
שלב 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. |
status | active, או disconnected אם הלקוח ניתק את המספר. במצב הזה הטוקן כבר לא עובד, וצריך לחבר את המספר מחדש. |
coexistence | true אם המספר ממשיך לעבוד גם באפליקציית WhatsApp Business בטלפון. |
webhook | לאן ההודעות של המספר מופנות. ok: true אומר ש-Meta אישרה שהן מגיעות לכתובת שלכם. אם לא, error מסביר למה. |
history | רק במספר שממשיך לעבוד גם בטלפון: אילו בקשות כבר נשלחו ל-Meta (smb_app_state_sync לאנשי קשר, history לשיחות), ועד מתי אפשר לבקש שוב (until). |
מה מגיע לשרת שלכם
Meta שולחת לכתובת שלכם את האירועים של המספרים בפורמט שלה, כמו שהוא, בלי שום שינוי מצדנו. סוג האירוע כתוב ב-entry[].changes[].field:
field | מה יש בו |
|---|---|
messages | value.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.
הורדת קבצים
- בהודעה עם קובץ יש מזהה, למשל
image.id. GET https://graph.facebook.com/v24.0/{media_id}עם הטוקן מחזירurl,mime_typeו-file_size.- מורידים את ה-
urlעם אותה כותרתAuthorization: Bearer. הכתובת בתוקף לכמה דקות בלבד.
Meta שומרת את הקבצים לזמן מוגבל (7 ימים), אז שומרים אותם אצלכם ברגע שההודעה מגיעה.
תבניות
יצירה: POST /{waba_id}/message_templates. רשימה וסטטוס: GET /{waba_id}/message_templates. עדכוני אישור לא נשלחים לשרת שלכם, ולכן בודקים את הסטטוס בקריאה הזו: Meta בדרך כלל מאשרת תוך דקות, ולפעמים עד 24 שעות.
היסטוריה ואנשי קשר: מספר שממשיך לעבוד גם בטלפון
לקוח שכבר עובד עם אפליקציית WhatsApp Business בטלפון יכול לחבר את אותו מספר ולהמשיך לעבוד בה. במקרה כזה Meta יכולה להעביר את אנשי הקשר ואת השיחות הקודמות מהאפליקציה, אבל רק פעם אחת, ורק תוך 24 שעות מהחיבור.
- אנחנו מבקשים אותם מ-Meta רק אחרי שההודעות של המספר מופנות לשרת שלכם, והשרת עונה לבדיקה. כך ההיסטוריה מגיעה אליכם, ולא אלינו.
- אם הכתובת לא הייתה מוגדרת, או שהשרת לא ענה, הבקשה מחכה. ברגע שהכתובת תקינה (בשמירה, או בבדיקה השעתית), היא נשלחת. אפשר גם ללחוץ "משיכה עכשיו" בקונסולה, בהגדרות ← שותף, ליד המספר.
- אחרי 24 שעות Meta כבר לא מאפשרת לבקש. כדי לקבל את ההיסטוריה צריך לנתק את המספר ולחבר אותו מחדש.
- המצב מופיע בשדה
historyשל המספר (שלב 3).
אבטחה
- מפתח ה-API והטוקנים נשארים בשרת שלכם בלבד. לא בדפדפן, לא באפליקציה, ולא בקוד שהלקוח רואה.
- הכתובת הסודית היא ההגנה של הוובהוק. Meta חותמת כל אירוע בכותרת
X-Hub-Signature-256, אבל עם הסוד של האפליקציה שלנו, ולכן אין לכם דרך לבדוק את החתימה. מה שמגן היא הכתובת: https, וחלק ארוך ואקראי בנתיב. אל תכתבו אותה בלוגים. אם היא דלפה, מחליפים אותה בקונסולה, וכל המספרים עוברים לכתובת החדשה. - כל טוקן פותח לקוח אחד. טוקן שדלף חושף רק את הלקוח שלו. מי שמחזיק אותו יכול לשלוח בשם העסק, אז שומרים אותו מוצפן.
- הודעות מהדפדפן הן רק סימן.
SHLACHLI_SIGNUPוהפרמטרים שלreturn_urlמגיעים מהדפדפן, ומשתמש יכול לזייף אותם. מה שקובע הוא מה ש-GET /v1/partner/numbersמחזיר.
גבולות ושאלות
- מספר אחד לכל קישור. אם בחשבון הוואטסאפ של הלקוח יש כמה מספרים, מתחבר הראשון שבהם. למספר נוסף צריך קישור נוסף.
- קצב: עד 120 קריאות בדקה לכל מפתח API ב-API של שלח לי. הקריאות מול Meta כפופות למגבלות של Meta.
- חיבורים חדשים בשבוע: Meta מגבילה כמה עסקים חדשים אפשר לחבר בשבוע. אם אתם מתכננים לחבר הרבה לקוחות בבת אחת, ספרו לנו מראש.
- ניתוק: לקוח יכול לנתק בכל רגע, מהאפליקציה בטלפון או מההגדרות של העסק שלו בפייסבוק. המספר יופיע אז עם
status: "disconnected", והטוקן יפסיק לעבוד. - שגיאות מה-API שלנו חוזרות כ-JSON עם
error.401אומר שהמפתח שגוי, ו-402אומר שהפעולה לא כלולה בחבילה. - שאלות: support@shlach.li.
בדיקה מקצה לקצה
- השרת עונה לבדיקה. הפקודה הזו צריכה להחזיר בדיוק
12345:curl "https://your-system.example/wa/7fQ2kx9LmZr4...?hub.mode=subscribe&hub.verify_token=YOUR_VERIFY_TOKEN&hub.challenge=12345" - בקונסולה, בהגדרות ← שותף: הדביקו את הכתובת ולחצו "שמירה ובדיקה".
- צרו קישור עם
refשל לקוח בדיקה, וחברו מספר אמיתי דרך החלון. - ודאו שהדף שלכם קיבל
SHLACHLI_SIGNUP, ושב-GET /v1/partner/numbersמופיעיםtokenו-"webhook": {"ok": true}. - שלחו למספר הודעה, תמונה והקלטה מטלפון אחר, וודאו שהן מגיעות לשרת ושהקבצים יורדים.
- ענו עם הטוקן, וודאו שהסטטוסים
sent,deliveredו-readמגיעים לשרת.
שלח