WhatsApp Cloud API: הקמה רשמית מהחיבור ועד הוכחת המסירה

מה נבנה ומה הראיות במדריך מוכיחות

חיבור של WhatsApp Cloud API מתחיל בנכסי העסק ב־Meta ומסתיים ביכולת לדעת מה קרה לכל הודעה. בקשת שליחה תקינה היא תחנה בדרך. כדי להשתמש בחיבור בתהליך עסקי צריך גם לקבל אירועים, לזהות את מקורם, לשמור אותם ולקשר את התוצאה להודעה המקורית. במסלול הרשמי יש תיק עסקי, חשבון WhatsApp Business ומספר עסקי. Meta WhatsApp Cloud API collection, accessed October 2026 (נפתח בחלון חדש)

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

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

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

קבלה, מסירה וקריאה הן תוצאות שונות

רישום תוצאה כמו "ההודעה הצליחה" מסתיר מידע שדרוש למפעיל. האם נבנתה בקשה? האם Meta קיבלה אותה? האם ההודעה הגיעה לנמען? במדריך הזה לכל שלב יש ראיה משלו. בתיעוד WhatsApp, הסטטוס sent מציין ש־WhatsApp קיבלה את ההודעה, ו־delivered מציין שההודעה הגיעה לנמען. Meta WhatsApp Webhook Payload Reference, accessed October 2026 (נפתח בחלון חדש)

נקודת החיבור בין השלבים היא מזהה ההודעה. Meta מתעדת מזהה ייחודי להודעה ומעקב אחר הסטטוס שלה באמצעות webhook. לכן שומרים את המזהה מתשובת השליחה, ומחפשים אותו בתוך עדכון הסטטוס. אירוע מסירה שאינו קשור לניסיון הנבדק אינו מוכיח דבר על אותו ניסיון. Meta WhatsApp Send Text Message, accessed October 2026 (נפתח בחלון חדש)

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

מכינים את נכסי Meta וההרשאות

לפני כתיבת קוד, הכינו מיפוי של הנכסים שהאפליקציה תשתמש בהם. תיק עסקי, חשבון WhatsApp Business ומספר עסקי הם הנכסים שמונה אוסף Cloud API הרשמי. למיפוי הוסיפו את בעל ההרשאה בארגון ואת הסביבה שאליה הנכס שייך. זאת המלצת תיעוד שמצמצמת בלבול בין בדיקה להפעלה. Meta WhatsApp Cloud API collection, accessed October 2026 (נפתח בחלון חדש)

אסימון משתמש מוגבל לפי האוסף הרשמי ל־24 שעות. אסימון משתמש מערכת יכול להיות מוגדר לעד 60 ימים או ללא תפוגה. אסימון ללא תאריך תפוגה עדיין אינו הבטחה שהרשאותיו יישארו תקפות. בדקו את ההגדרה בפועל לפני הפיילוט, ואל תבססו תהליך קבוע על אסימון בדיקה שנוצר במקרה. Meta WhatsApp Cloud API collection, accessed October 2026 (נפתח בחלון חדש)

גם ההרשאות נפרדות לפי פעולה. שליחת הטקסט המתועדת דורשת whatsapp_business_messaging; הרשמה לאירועי החשבון דורשת אסימון משתמש מערכת עם whatsapp_business_management. הצלחה באחת הפעולות אינה בדיקה של האחרת. Meta WhatsApp Send Text Message, accessed October 2026 (נפתח בחלון חדש) Meta WhatsApp Webhook Subscriptions, accessed October 2026 (נפתח בחלון חדש)

1. זהו את התיק העסקי ואת חשבון WhatsApp Business המיועד לבדיקה.
2. רשמו את מזהה החשבון ואת מזהה המספר בשדות נפרדים וברורים.
3. התאימו את הרשאות האסימון לפעולות השליחה וההרשמה שתבצעו.
4. שמרו את האסימון בצד השרת, מחוץ לקוד ציבורי, למסמך עבודה ולצילום מסך.
5. תעדו מי בארגון יכול לבדוק הרשאות ולטפל באסימון שפסק לעבוד.

Getting Started with WhatsApp Cloud APIs in 2026

מגדירים הסכמה, פרטיות ונמען בדיקה

בדיקה טכנית צריכה להתחיל בציפייה משותפת. הנמען צריך לדעת מאיזה עסק תגיע הודעה, מה היא תכיל ומתי הבדיקה תסתיים. מדיניות WhatsApp דורשת פרטי קשר שנמסרו לעסק והרשאה לקבלת פניות בהמשך, וכן כיבוד בקשות להפסיק את התקשורת. גם בניסיון מצומצם, עצם הידיעה של מספר הטלפון אינה תיעוד של הסכמה. Meta WhatsApp Business Messaging Policy, accessed October 2026 (נפתח בחלון חדש)

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

המדיניות מטילה על העסק אחריות להודעות פרטיות, הרשאות והסכמות נדרשות, ולפרסום מדיניות פרטיות. כאשר משתמשים במענה אוטומטי, נדרש גם נתיב סיוע ברור וזמין, כגון אדם, טלפון או דוא"ל. Meta WhatsApp Business Messaging Policy, accessed October 2026 (נפתח בחלון חדש) תכנון השיחה והמעבר לסיוע מפורטים במדריך לבוט WhatsApp עסקי.

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

בוחרים בין הודעת שירות לתבנית

לפני שבונים את בקשת השליחה, מחליטים איזה סוג הודעה מותר לשלוח בהקשר הנוכחי. הודעה מהלקוח פותחת חלון שירות של 24 שעות, וכל הודעה נוספת ממנו מאפסת אותו. בתוך החלון ניתן לענות בהודעות שירות, אבל מאז 1 באוקטובר 2026 הן חזרו להיות מחויבות: Meta נותנת לכל מספר עסקי 1,000 הודעות שירות שנמסרו בחודש ללא חיוב, וגובה מההודעה ה־1,001. גם תבנית utility שנשלחת בתוך החלון כבר אינה חינמית. Meta WhatsApp Business Platform Pricing, developer documentation, accessed October 2026 (נפתח בחלון חדש)

לפתיחת שיחה מצד העסק נדרשת תבנית מאושרת, וגם מחוץ לחלון השירות מותר לשלוח רק באמצעות תבניות מאושרות. אישור של הנמען להשתתף בבדיקה אינו מבטל את הכלל הזה. הסכמה וחלון שירות הם תנאים שונים, ולכן צריך לבדוק את שניהם. Meta WhatsApp Business Messaging Policy, accessed October 2026 (נפתח בחלון חדש)

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

מאמתים את כתובת ה-webhook

כתובת webhook היא המקום שאליו יגיעו העדכונים. בשלב ההרשמה Meta בודקת שהכתובת בשליטתכם באמצעות בקשת GET הכוללת hub.mode, hub.challenge ו־hub.verify_token. המקלט בודק שהמצב הוא subscribe ושהטוקן מתאים לערך שהוגדר, ואז מחזיר את האתגר. Meta Webhooks Getting Started, accessed October 2026 (נפתח בחלון חדש)

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

הכתובת צריכה להשתמש ב־HTTPS ובתעודה תקפה. פונקציית verification_response, שמופיעה עם הקוד בפרק בניית הבקשה, מדגימה את ההחלטה על קוד התשובה וגוף האתגר. היא אינה פותחת שרת, קוראת פרמטרים ממסגרת אתר או מחברת את הכתובת ל־Meta. שכבת השרת צריכה להעביר אליה את הפרמטרים ולהחזיר את התוצאה. Meta Webhooks Getting Started, accessed October 2026 (נפתח בחלון חדש)

1. הכינו כתובת HTTPS נפרדת לקבלת האירועים.
2. הגדירו טוקן אימות שאינו ריק והעבירו אותו ליישום באופן מאובטח.
3. חברו את פרמטרי ה־GET לפונקציית הבדיקה המתועדת בהמשך.
4. החזירו את ערך האתגר כאשר המצב והטוקן מתאימים.
5. בדקו שהטוקן השגוי נדחה, ואז בצעו את אימות הכתובת מול Meta בחשבונכם.

רושמים את החשבון לקבלת אירועים

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

האפליקציה נרשמת ברמת חשבון WhatsApp Business, כדי לקבל אירועים עבור המספרים שתחתיו. נקודת הקצה להרשמה דורשת אסימון משתמש מערכת עם whatsapp_business_management. לכן צריך לדעת באיזה חשבון מדובר, ולא להשתמש במזהה המספר רק משום שכבר הועתק למסמך העבודה. Meta WhatsApp Webhook Subscriptions, accessed October 2026 (נפתח בחלון חדש)

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

אישור הרשמה כשלעצמו עדיין אינו תוצאה עסקית. כדי להשלים את הבדיקה צריך ליזום בהמשך אירוע מותר ולראות אותו במקלט. התיעוד של Meta הוא המקור לפעולת ההרשמה עצמה; אין להעתיק לכאן בקשת API ממסלול אחר או להניח שהרשאת השליחה מכסה גם אותה.

1. זהו את חשבון WhatsApp Business שאליו שייך מספר הבדיקה.
2. בדקו שאסימון משתמש המערכת כולל את הרשאת הניהול הנדרשת.
3. בצעו את הרשמת האפליקציה לפי תיעוד ההרשמות הרשמי.
4. תעדו את תוצאת ההרשמה ואת החשבון שנבדק ללא סודות.
5. השאירו את בדיקת הגעת האירוע פתוחה עד שנראה אירוע מתאים ביומן הקליטה.

בונים בקשת טקסט רשמית בלי לשלוח עדיין

בקשת טקסט נשלחת בשיטת POST לנתיב ההודעות של מזהה המספר ב־Graph API. היא כוללת את המוצר whatsapp, את הנמען ואת גוף הטקסט, ודורשת אסימון עם whatsapp_business_messaging. הקוד הבא מפריד בין בניית הבקשה לבין הפעלתה. Meta WhatsApp Send Text Message, accessed October 2026 (נפתח בחלון חדש)

את graph_version ממלאים לפי גרסה נתמכת שאומתה בתיעוד הרשמי בעת ההקמה. המדריך אינו קובע גרסה עדכנית, והבדיקה בקוד שהמחרוזת מתחילה ב־v אינה מאשרת שהגרסה קיימת או נתמכת. גם זהות הנמען, הרשאות האסימון וזמינות המספר דורשות בדיקה נפרדת.

בשלב הזה משתמשים ב־build_text_request בלבד. הפעלת send_text מבצעת בקשת רשת, ולכן מקומה בנוהל השליחה הבא, לאחר הכנת המקלט. אל תדפיסו את אובייקט הבקשה או את כותרותיו לצורך צילום: כותרת Authorization מכילה את האסימון. תעדו בדיקה של מבנה הבקשה באמצעות ערכי דמה בלבד.

פלט ההרצה המתועד לקוד הסתיים בהצלחה מול שרת מדומה. זה מאמת את ההתנהגות שנבדקה מקומית, לרבות בניית הבקשה ופענוח התשובה המדומה. הוא אינו מעיד ש־Meta אישרה אסימון, שקיים מספר מתאים או שהנמען קיבל הודעה. גם ערך ה־timeout בפונקציה הוא בחירת מימוש מקומית, לא התחייבות של הספק.

import json
from urllib.request import Request, urlopen


def verification_response(query, expected_token):
    if query.get("hub.mode") != "subscribe":
        return 403, ""
    if query.get("hub.verify_token") != expected_token:
        return 403, ""
    challenge = query.get("hub.challenge")
    if not challenge:
        return 400, ""
    return 200, challenge


def build_text_request(graph_version, phone_number_id, access_token, recipient, body):
    if not graph_version.startswith("v"):
        raise ValueError("graph_version must look like vNN.N")
    url = f"https://graph.facebook.com/{graph_version}/{phone_number_id}/messages"
    payload = {
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": recipient,
        "type": "text",
        "text": {"preview_url": False, "body": body},
    }
    return Request(
        url,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
        },
        method="POST",
    )


def send_text(request, timeout=10):
    with urlopen(request, timeout=timeout) as response:
        return response.status, json.loads(response.read())

מריצים שליחת בדיקה ושומרים את המזהה

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

דוגמת הקוד שולחת טקסט חופשי. לצורך הבדיקה הנמען המסכים צריך לפתוח חלון שירות בהודעה לעסק, והניסיון צריך להתבצע בתוך החלון. מחוץ לו נדרשת תבנית מאושרת; אין כאן קוד תבנית שנבדק ואפשר להפעיל במקום. Meta WhatsApp Business Platform Pricing, accessed October 2026 (נפתח בחלון חדש) Meta WhatsApp Business Messaging Policy, accessed October 2026 (נפתח בחלון חדש) הודעת טקסט חופשי בתוך החלון נחשבת הודעת שירות, ולכן בבדיקה קטנה היא נספרת במכסה החינמית החודשית של המספר, כל עוד המספר לא ניצל אותה.

שמרו את מזהה ההודעה מתשובת השליחה יחד עם מזהה פנימי של ניסיון הבדיקה. לפי Meta, מזהה ההודעה מאפשר לעקוב אחר הסטטוס שלה ב־webhooks. תשובת קבלה ומזהה אינם ראיית מסירה; הם הבסיס לקישור שיבוצע בהמשך. Meta WhatsApp Send Text Message, accessed October 2026 (נפתח בחלון חדש)

1. השלימו את אימות החתימה, השמירה וקישור הסטטוסים המתוארים בפרקים הבאים.
2. אשרו עם הנמען את תוכן הבדיקה ובקשו ממנו לפתוח שיחה עם העסק.
3. בדקו את מצב חלון השירות ואת התאמת המספר והאסימון.
4. בנו את הבקשה ורק אז הפעילו את פונקציית השליחה.
5. שמרו את זמן הניסיון, תוצאת הבקשה ומזהה ההודעה שהתקבל.
6. עצרו לבדיקה במקרה של כשל או timeout; אל תניחו שהודעה לא נשלחה רק מפני שלא התקבלה תשובה אצלכם.

מאמתים חתימה לפני פענוח האירוע

לכל בקשת אירוע נכנסת יש להתייחס כקלט שדורש אימות. Meta מתעדת חתימה בכותרת X-Hub-Signature-256 עם הקידומת sha256=. מחשבים HMAC עם סוד האפליקציה על תוכן הבקשה ומשווים לחתימה שהתקבלה. הקוד משתמש בבתים המקוריים ובהשוואה באמצעות hmac.compare_digest. Meta Webhooks Getting Started, accessed October 2026 (נפתח בחלון חדש)

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

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

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

import hashlib
import hmac
import json


def verify_meta_signature(raw_body: bytes, signature: str, app_secret: str) -> bool:
    if not signature.startswith("sha256="):
        return False
    expected = hmac.new(
        app_secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    supplied = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, supplied)


def webhook_events(raw_body: bytes) -> list[dict]:
    payload = json.loads(raw_body)
    events = []
    for entry in payload.get("entry", []):
        for change in entry.get("changes", []):
            if change.get("field") != "messages":
                continue
            value = change.get("value", {})
            for message in value.get("messages", []):
                events.append({
                    "key": f"message:{message['id']}",
                    "kind": "message",
                    "message_id": message["id"],
                    "from": message.get("from"),
                    "message_type": message.get("type"),
                })
            for status in value.get("statuses", []):
                state = status["status"]
                events.append({
                    "key": f"status:{status['id']}:{state}:{status['timestamp']}",
                    "kind": "status",
                    "message_id": status["id"],
                    "status": state,
                    "timestamp": status["timestamp"],
                    "errors": status.get("errors", []),
                })
    return events

מפרידים בין הודעה נכנסת לעדכון סטטוס

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

אובייקט של הודעה נכנסת כולל מזהה ייחודי, שולח, חותמת זמן וסוג הודעה. הקוד מצמצם חלק מהמידע הזה לרשומת עבודה עם kind,‏ message_id ו־key. זאת צורת הפלט של הדוגמה המקומית, לא שמות שדות שמוצגים כאן כחוזה הרשמי של Meta. Meta WhatsApp Messages Object, accessed October 2026 (נפתח בחלון חדש)

בענף הסטטוסים הקוד שומר גם מצב, זמן ופרטי שגיאה אם קיימים. הערכים שמונה התיעוד כוללים sent,‏ delivered,‏ read,‏ failed ו־deleted. המימוש העסקי צריך להחליט מה לעשות בכל סוג בלי להניח שעצם הגעת אירוע פירושה שהלקוח כתב. Meta WhatsApp Webhook Payload Reference, accessed October 2026 (נפתח בחלון חדש)

מונעים שמירה כפולה של אירועים בבדיקה המקומית

אם אותה הודעה נכנסת מגיעה שוב לעיבוד, רצוי שהמערכת תזהה שכבר ראתה אותה. מזהה ההודעה המתועד הוא נקודת אחיזה יציבה לכך. בדוגמה המקומית מפתח של הודעה נכנסת מבוסס עליו; מפתח של עדכון סטטוס כולל גם את המצב ואת הזמן. ההרכב השני הוא החלטת מימוש במדריך, ולא שדה ייעודי שמובטח על ידי Meta. Meta WhatsApp Messages Object, accessed October 2026 (נפתח בחלון חדש)

הטבלה הבאה משתמשת במפתח ראשי ובהכנסה שמתעלמת מהתנגשות. מקימים את הטבלה בזמן הכנת סביבת הבדיקה, ובהמשך משתמשים בפקודת ההכנסה לכל אירוע. היישום מחבר את key מהפלט אל event_key, את kind אל event_kind, ואת המזהה אל message_id. את הערכים מעבירים כפרמטרים לפקודה.

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

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

CREATE TABLE webhook_events (
  event_key TEXT PRIMARY KEY,
  event_kind TEXT NOT NULL,
  message_id TEXT NOT NULL,
  payload_json TEXT NOT NULL,
  received_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO webhook_events (event_key, event_kind, message_id, payload_json)
VALUES (:event_key, :event_kind, :message_id, :payload_json)
ON CONFLICT (event_key) DO NOTHING;

מאשרים קבלה מהר ומעבדים בנפרד

Meta מצפה ל־HTTP 200 עבור התראה שהתקבלה. מבחינת התכנון המקומי, רצוי להחזיר את האישור אחרי שהאירוע עבר אימות ונשמר באופן עמיד, ולהפריד ממנו את העבודה העסקית הארוכה. כך ההחלטה אם אירוע נקלט אינה תלויה במשך הפעולה שתתבצע בעקבותיו. Meta Webhooks Getting Started, accessed October 2026 (נפתח בחלון חדש)

בתיעוד Meta Webhooks הכללי מתוארים ניסיון חוזר מיידי ובהמשך ניסיונות בתדירות פוחתת, עד 36 שעות. זהו מידע מהתיעוד הכללי, ולא התחייבות ייעודית למשך הניסיונות החוזרים של WhatsApp Cloud API. המסקנה התפעולית כאן היא להכין קליטה של אירוע חוזר, ולא לכוון שעון טיפול לפי המספר הזה. Meta Webhooks Getting Started, accessed October 2026 (נפתח בחלון חדש)

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

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

1. אמתו את החתימה לפני פענוח ועיבוד.
2. שמרו את האירוע והשלימו את פעולת השמירה לפני אישור הקבלה.
3. החזירו אישור קליטה בלי להמתין לפעולה עסקית ממושכת.
4. העבירו את האירוע לעיבוד נפרד עם מצב טיפול מתועד.
5. בדקו מה קורה כשהשמירה נכשלת וכשהעיבוד נעצר לאחר שמירה.

קושרים סטטוס למזהה ההודעה

אחרי השליחה ואחרי קליטת האירועים, צריך לחבר את הרשומות. מזהה ההודעה שהוחזר בבקשת השליחה הוא אותו סוג מזהה שמופיע באירוע הסטטוס המתייחס אליה. ההצלבה הזאת מאפשרת לעדכן את הניסיון הנכון, גם כשיש פעילות נוספת באותו זמן. Meta WhatsApp Send Text Message, accessed October 2026 (נפתח בחלון חדש) Meta WhatsApp Webhook Payload Reference, accessed October 2026 (נפתח בחלון חדש)

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

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

1. אתרו את רשומת השליחה לפי מזהה ההודעה שהתקבל מה־API.
2. השוו אליה את message_id שהופק מתוך אירוע הסטטוס המאומת.
3. הוסיפו את האירוע להיסטוריה עם המצב, הזמן ופרטי השגיאה הזמינים.
4. הציגו delivered רק כשיש אירוע מתאים שמקושר לאותה הודעה.
5. הפנו אירועים שלא נמצאה להם התאמה לבדיקה, במקום לנחש לאיזו שליחה הם שייכים.

מאבחנים תקלה לפי הראיה שחסרה

אבחון טוב מתחיל בשלב האחרון שיש לו ראיה. אם לא הושלם אתגר החיבור, אין טעם לשנות את פקודת השמירה. אם יש אירוע עם חתימה תקינה שנשמר ביומן, אפשר לבדוק את הפענוח והקישור. ואם יש failed, שמרו את הפרטים שהגיעו איתו לפני ניסיון תיקון. פירוש מצבי ההודעה מופיע בתיעוד הרשמי. Meta WhatsApp Webhook Payload Reference, accessed October 2026 (נפתח בחלון חדש)

timeout בבקשת שליחה דורש זהירות: היישום לא קיבל תשובה בזמן, אבל מכאן לא נובע שהבקשה לא התקבלה אצל הספק. בדקו את התיעוד המקומי ואת האירועים הזמינים לפני ניסיון נוסף. פקודת SQL שמונעת שמירת webhook כפול אינה מנגנון למניעת שליחה חוזרת של אותה הודעה.

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

ממפים את רכיבי העלות של ההפעלה

לפי דף התמחור של Meta, שעודכן ב־30 בספטמבר 2026 ומשקף שינויים שנכנסו לתוקף ב־1 באוקטובר 2026, בסיס החיוב הוא הודעה שנמסרה, והמחיר תלוי בקטגוריה ובשוק הנמען, שנקבע לפי קידומת מספר הטלפון שלו. הקטגוריות הן marketing,‏ utility,‏ authentication,‏ service ו־Meta Business Agent. הודעה שהלקוח שולח לעסק אינה מחויבת. Meta WhatsApp Business Platform Pricing, developer documentation, accessed October 2026 (נפתח בחלון חדש)

מה השתנה ב־1 באוקטובר 2026: הודעות שירות, כלומר כל הודעה שאינה תבנית ואינה של Meta Business Agent ונשלחת בחלון של 24 שעות, מחויבות שוב בתעריף קבוע לפי שוק, אחרי מכסה חינמית של 1,000 הודעות שירות שנמסרו בחודש לכל מספר עסקי. המכסה מתאפסת בכל חודש ואינה עוברת לחודש הבא. גם תבניות utility שנשלחות בתוך חלון השירות, שהיו חינמיות מאז יולי 2025, מחויבות כעת. לשינוי יש חריגים: ארגונים ממשלתיים ולא רווחיים זכאים ממשיכים לקבל הודעות שירות ללא חיוב גם מעבר למכסה, עד 31 בדצמבר 2027, וספקי AI כפופים למדיניות תמחור נפרדת. Meta WhatsApp Business Platform Pricing, developer documentation, accessed October 2026 (נפתח בחלון חדש)

אמצעי תשלום הוא תנאי להמשכיות: בלי אמצעי תשלום בחשבון המסרים, Meta ממשיכה למסור הודעות שירות בתוך המכסה החינמית בלבד, ולא אחריה. הוסיפו אמצעי תשלום ב־Billing Hub של Meta לפני שהמכסה נגמרת, ובדקו את זה לכל חשבון מסרים. עדכוני הסטטוס ב־webhook מסמנים את השינוי: הודעה שחויבה מגיעה עם pricing type מסוג regular, והודעה שלא חויבה בחלון השירות מגיעה עם free_customer_service. Meta WhatsApp Business Platform Pricing, developer documentation, accessed October 2026 (נפתח בחלון חדש)

יש גם חלון כניסה חינמי. כשמשתמש פונה דרך מודעת Click to WhatsApp, באפליקציית אנדרואיד או iOS, לא בדסקטופ ולא ב־Web, והעסק עונה בתוך חלון השירות, התשובה אינה מחויבת ופותחת חלון שיכול להישאר פתוח עד 7 ימים. בזמן הזה הודעות marketing,‏ utility,‏ authentication ו־service אינן מחויבות, והודעות של Meta Business Agent ממשיכות להיות מחויבות. מקורות משניים מדברים על 72 שעות; בדף Meta נכתב עד 7 ימים, ולכן זה הנתון שנשמר כאן. Meta WhatsApp Business Platform Pricing, developer documentation, accessed October 2026 (נפתח בחלון חדש)

ישראל מופיעה בתעריפון של Meta כשוק עצמאי. לפי תעריפון ה־USD שבתוקף מ־1 באוקטובר 2026, הודעת marketing לנמען עם קידומת 972 עולה 0.0353 דולר, והודעת utility, authentication או service עולה 0.0053 דולר כל אחת, לכל הודעה שנמסרה. מדרגות הנפח חלות רק על utility ועל authentication, והמדרגה הראשונה בישראל נמשכת עד 100,000 הודעות לחודש ל־utility ועד 300,000 ל־authentication. המדריך אינו ממיר את הסכומים לשקלים, משום שהמטבע נקבע בחשבון המסרים. את הטבלה העדכנית, כולל מטבעות נוספים, מורידים מתעריפון הרשמי של Meta (נפתח בחלון חדש). המטבע נבחר ביצירת חשבון המסרים ואי אפשר לשנות אותו אחר כך, ולכן בוחרים אותו מראש. Meta WhatsApp Business Platform Rate Cards, accessed October 2026 (נפתח בחלון חדש)

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

משלימים הוכחת מסירה מול נמען אמיתי לפני פיילוט

בדיקת הקבלה מחברת את החלקים לניסיון שאפשר להסביר מתחילתו ועד סופו. נדרשות בקשת שליחה מתועדת, תשובת קבלה עם מזהה, אירוע delivered מאומת עם מזהה מתאים ואישור מהנמען שהתוכן הגיע כצפוי. Meta מספקת את מזהה ההודעה ואת עדכון הסטטוס שמאפשרים את הקישור. Meta WhatsApp Send Text Message, accessed October 2026 (נפתח בחלון חדש) Meta WhatsApp Webhook Payload Reference, accessed October 2026 (נפתח בחלון חדש)

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

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

1. הגדירו מראש את תוכן הבדיקה ואת התוצאה העסקית הצפויה, אם קיימת.
2. תעדו את הסכמת הנמען ובדקו שהשליחה מתאימה למצב השיחה.
3. בצעו את ניסיון השליחה ושמרו את מזהה ההודעה ותוצאת הבקשה.
4. קבלו אירוע מסירה, אמתו אותו והשוו את מזההו למזהה שנשמר.
5. אספו אישור מהנמען שהתוכן הצפוי הגיע בשיחה המתאימה.
6. בדקו את הרשומה העסקית ושמרו ראיות מצומצמות שאינן חושפות סודות או פרטי נמען למי שאינו צריך אותם.
7. השאירו את בדיקת הקבלה פתוחה אם חוליה כלשהי חסרה, וציינו איזו ראיה נדרשת לסגירתה.

רשימת מעבר לפיילוט

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

במהלך הפיילוט חשוב שמפעיל יוכל להבחין בין הודעה שנקלטה לשליחה, הודעה שנמסרה והודעה שנכשלה. חשוב גם שיהיה ברור מי מטפל במקרה שנותר ללא הכרעה. דרישת נתיב הסיוע של WhatsApp ממשיכה לחול גם כשהאוטומציה פעילה. Meta WhatsApp Business Messaging Policy, accessed October 2026 (נפתח בחלון חדש)

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

• זהות התיק העסקי, החשבון והמספר מתועדת ללא חשיפת אסימונים.
• הרשאות השליחה וההרשמה נבדקו עבור הסביבה המיועדת.
• הסכמה, הסרה, מדיניות פרטיות ונתיב סיוע הוגדרו לפני ההפעלה.
• אתגר החיבור הושלם בכתובת HTTPS עם תעודה תקפה.
• אירועי POST נבדקים בחתימה על גוף הבקשה המקורי לפני עיבוד.
• השמירה, מניעת הכפילויות וההתנהגות בכשל נבדקו ביישום המשולב.
• עדכוני סטטוס מקושרים למזהי השליחה, והיסטוריית האירועים נשמרת.
• אירוע שאין לו התאמה או ניסיון עם תוצאה לא ידועה מופנים לבדיקה.
• הודעת בדיקה הוצלבה מול אירוע מסירה ואישור של הנמען האמיתי.
• התוצאה העסקית נבדקה בנפרד, כאשר היא חלק מהמטרה.
• לכל ראיה חסרה יש אחראי, והפיילוט אינו מוצג כמאושר לפני השלמתה.
• אמצעי תשלום פעיל מוגדר בכל חשבון מסרים לפני שמכסת 1,000 הודעות השירות החודשית מסתיימת.
• נפח הודעות השירות החודשי של כל מספר נמדד מול המכסה, וידוע כמה תבניות utility נשלחות בתוך חלון השירות.
• התעריף לנמענים עם קידומת 972 והמטבע של החשבון נבדקו בתעריפון הרשמי של Meta, ולא לפי סכום ממקור משני.
• ידוע אילו הודעות נשלחות לנמענים עם קידומת 972 ואילו לנמענים בחו״ל, כי כל קידומת עשויה להיות בשוק תמחור אחר.
• אם יש מודעות Click to WhatsApp, ידוע מי עונה בחלון הכניסה החינמי ומה נשלח בו.