שליחת עדכוני WhatsApp מפריוריטי: ארכיטקטורה שעובדת

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

המדריך מניח היכרות עם Webhooks בפריוריטי ועם הקמת WhatsApp Cloud API.

למה לא לחבר ישירות

אפשר להגדיר ב-פריוריטי webhook שמצביע על כתובת כלשהי. מפתה להצביע ישירות על Graph API של Meta. זה לא יעבוד, מארבע סיבות:

1. מבנה המטען. פריוריטי שולחת JSON בפורמט שלה, מאורגן לפי טופס. Meta דורשת מבנה ספציפי לחלוטין עם messaging_product, to, type ומערך components. אין דרך לגשר בין השניים בהגדרה.
2. אימות. Meta דורשת טוקן System User בכותרת Authorization. פריוריטי שולחת את הטוקן שלה בכותרת priority-bpm-token. אלה מנגנונים שונים.
3. נרמול מספרים. המספר בכרטיס הלקוח כמעט אף פעם אינו בפורמט E.164.
4. אין retry. לפריוריטי אין מדיניות ניסיון חוזר מתועדת. אם Meta מחזירה שגיאה חולפת, ההודעה פשוט אבדה ואף אחד לא יידע.

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

הארכיטקטורה

פריוריטי (כלל BPM)
   → webhook →
שירות ביניים (תור + מיפוי + לוג)
   → Graph API →
WhatsApp Cloud API

1. הצד של פריוריטי

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

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

אם יש תנאי עסקי - למשל רק לקוחות שנתנו הסכמה - עדיף לשים אותו בתנאי הכלל בפריוריטי ולא בקוד שלך. פחות תעבורה ופחות מקומות לבדוק.

2. שירות הביניים

זה הרכיב שעושה את העבודה האמיתית:

• מאמת את priority-bpm-token ודוחה כל בקשה בלעדיו. זו ההגנה היחידה - בלעדיה כל מי שמגלה את הכתובת יכול לגרום לך לשלוח הודעות.
• כותב לתור ומחזיר תשובה מיד. אין לקרוא ל-Meta בתוך ה-webhook.
• מעשיר - מושך מפריוריטי את מה שחסר: שם הלקוח, טלפון, פרטי המסמך.
• מנרמל את הטלפון ל-E.164.
• ממפה את סוג האירוע לשם תבנית ולערכי המשתנים.
• שולח, מתעד ומנסה שוב לפי קוד השגיאה.

3. נרמול מספרי טלפון - לא פרט טכני

שדה הטלפון בכרטיס לקוח ב-ERP מכיל בפועל כל דבר: 052-1234567, 0521234567, 972521234567, +972-52-123-4567, לפעמים שני מספרים באותו שדה. Meta מקבלת רק E.164.

הכללים המעשיים לישראל: מספר שמתחיל ב-0 - להחליף ב-+972; מספר שמתחיל ב-972 - להוסיף +; להסיר רווחים, מקפים וסוגריים. מספר שלא נפתר - לא לשלוח ולסמן לטיפול, לא לנחש.

מה מותר לשלוח: תבניות בלבד

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

המשמעות התכנונית: כל סוג אירוע דורש תבנית משלו, מאושרת מראש, בכל שפה. אי אפשר לכתוב טקסט דינמי - רק להציב ערכים במשתנים מיקומיים {{1}}, {{2}}.

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

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

טיפול בכשלים

לא כל שגיאה מטופלת אותו דבר. חלוקה מעשית לפי קודי השגיאה של Meta:

שגיאת 131026 - "אין WhatsApp" - היא מידע עסקי שימושי. שווה לכתוב אותה חזרה לכרטיס הלקוח כדי שהמערכת תדע בפעם הבאה שהערוץ הזה לא זמין ותיפול חזרה למייל או SMS.

מה לא לעשות

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