הקמת WhatsApp Cloud API: השלבים שהתיעוד של Meta מחביא

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

מה צריך להיות מוכן לפני שמתחילים

• Business Manager עם עסק מאומת. אימות עסקי אינו נדרש כדי לשלוח הודעות בדיקה, אבל כן נדרש כדי לצאת ממגבלות הכמות הנמוכות.
• אפליקציית Meta עם מוצר WhatsApp מוסף, ובידך app_id ו-app_secret.
• WhatsApp Business Account (WABA) עם waba_id, ומספר טלפון עם phone_number_id.
• טוקן של System User עם ההרשאה whatsapp_business_messaging ושיוך מפורש לנכסי ה-WABA ומספר הטלפון. טוקן זמני מ-Graph API Explorer יעבוד היום וייפול מחר עם קוד 190.
• נקודת קצה ציבורית ב-HTTPS ל-webhook, פרוסה וחיה. לא ngrok זמני, אלא הכתובת שתישאר.

שלב 1: מציאת מזהה מספר הטלפון

מזהה מספר הטלפון אינו מספר הטלפון. שולפים אותו מרשימת המספרים של ה-WABA, ומשתמשים בו כמעט בכל קריאה אחרת. הקריאה היא GET /{waba_id}/phone_numbers.

שלב 2: הגדרת ה-webhook ברמת האפליקציה

הקריאה היא POST /{app_id}/subscriptions, והיא שקולה למה שעושים ידנית ב-App Dashboard תחת WhatsApp ואז Configuration. שדות הבקשה:

• object - הערך whatsapp_business_account
• callback_url - כתובת ה-webhook הציבורית שלך
• verify_token - המחרוזת ששמרת בצד שלך
• fields - לכל הפחות messages; בפועל כדאי גם message_template_status_update ו-message_template_quality_update כדי לדעת מתי תבנית אושרה, נדחתה או הושהתה
• access_token - לא טוקן המשתמש. כאן צריך App Access Token, שהוא פשוט APP_ID|APP_SECRET עם קו אנכי ביניהם

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

שלב 3: המנוי שכולם שוכחים

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

POST /{waba_id}/subscribed_apps - עם גוף ריק.

הקריאה אידמפוטנטית ואפשר לחזור עליה בבטחה. היא לעולם לא קורית אוטומטית. בלעדיה שליחה יוצאת תעבוד מצוין, וזה בדיוק מה שמטעה - נראה שהחיבור תקין. אפשר לוודא עם GET /{waba_id}/subscribed_apps.

שלב 4: רישום המספר

לפני שליחה ראשונה כלשהי המספר חייב להירשם ל-Cloud API:

POST /{phone_number_id}/register עם messaging_product: "whatsapp" ו-pin בן שש ספרות.

ה-PIN הוא קוד האימות הדו-שלבי של המספר. אם אימות דו-שלבי כבוי, הקריאה מגדירה אותו. אם הוא כבר פעיל, הקוד חייב להתאים לקוד הקיים. מגבלת הקצב היא 10 ניסיונות למספר ב-72 שעות, ולכן ניחושים חוזרים ינעלו את המספר לשלושה ימים. אם אין לך את הקוד, אפס אותו ב-WhatsApp Manager לפני שתנסה.

מספר לא רשום מחזיר קוד 133010 או 131045 בכל שליחה.

שלב 5: לוודא שהמספר באמת יכול לשלוח

במקום לנחש, Meta חושפת בדיקה ייעודית: GET /{phone_number_id}?fields=health_status. התשובה היא אחת מ-AVAILABLE, LIMITED או BLOCKED. זו הבדיקה הראשונה שכדאי להריץ כשמשהו מפסיק לעבוד, לפני שמחפשים באג בקוד.

אימות ה-webhook הנכנס

נקודת הקצה שלך צריכה לטפל בשני סוגי בקשות:

• GET - אימות. Meta שולחת hub.mode, hub.verify_token ו-hub.challenge. אם ה-verify_token תואם, יש להחזיר את ערך ה-hub.challenge כטקסט גולמי.
• POST - אירועים. חובה לאמת את החתימה בכותרת X-Hub-Signature-256, שהיא HMAC-SHA256 של גוף הבקשה הגולמי עם ה-app secret כמפתח.

מלכודת שנייה, ומאוד נפוצה: אימות החתימה חייב לרוץ על הבייטים הגולמיים. אם ה-framework שלך מפרסר את ה-JSON ואז אתה מסדר אותו מחדש למחרוזת, החתימה לא תתאים - אפילו אם התוכן זהה - כי סדר המפתחות והרווחים משתנים. בסביבת proxy יש לוודא שהנתיב של ה-webhook ממופה לפני ה-body parser.

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

מה נשאר ידני

אימות העסק ב-Business Manager, העלאת תמונת פרופיל עסקית ובקשת עלייה במדרגת הכמות - כולם עוברים דרך ממשקי Meta ולוקחים ימים ולא דקות. כדאי לפתוח אותם מוקדם, במקביל לפיתוח, ולא לגלות ביום העלייה לאוויר שהחשבון תקוע במגבלה של 250 נמענים ביום.