וובהוק (Webhook) user_preferences ב-WhatsApp: כשלקוח עוצר או מחדש הודעות שיווקיות
וובהוק (Webhook) user_preferences מודיע לעסק שמשתמש ב-WhatsApp עצר או חידש את הודעות השיווק שלו דרך ההגדרה "Offers and announcements". כל אירוע כולל את הקטגוריה marketing_messages, ערך stop או resume, משפט פירוט, את השדה wa_id וה-BSUID של המשתמש, וחותמת זמן Unix. משוב מסוג Interested או Not interested באותה הגדרה לא מפעיל אותו.
easyCoexistence מחבר את מספר אפליקציית WhatsApp Business שלכם ל-Cloud API של Meta דרך Coexistence, כך שה-AI והאוטומציות שלכם עובדים על המספר שאתם שומרים באפליקציה.
שתי ההעדפות האפשריות הן stop ו-resume, שתיהן בקטגוריה marketing_messages, כאמור.
קוד הכשל 131050, שמתקבל במצב failed, מתייחס לתבנית שיווקית שנשלחה למשתמש שעצר את הודעות השיווק שלכם.
היעד שאליו Meta שולחת את user_preferences: זהו שדה שחשבון WhatsApp Business או מספר אינם יכולים לדרוס.
ההרשאה הנדרשת לקבלת וובהוקים מלבד messages וגם calls. גם user_preferences נכלל בהם.
מה מפעיל את וובהוק user_preferences?
לקוח שפותח את "Offers and announcements" ב-WhatsApp ובוחר לעצור, או מאוחר יותר לחדש, הודעות שיווק מהעסק שלכם. שתי הפעולות האלה הן המפעילים היחידים. אותה הגדרה מאפשרת ללקוח לסמן "Interested" או "Not interested", והמשוב הזה לא שולח וובהוק, אם כי "Not interested" עלול להקטין את מגבלת הודעות השיווק לאותו משתמש מול אותו לקוח, ופותח מסך שני שמציע לעצור את כל הודעות השיווק. רק אם הלקוח לוחץ אז על עצירה, user_preferences מופעל.
מה תוכן ה-payload?
מערך user_preferences לצד מערך contacts, תחת שם השדה user_preferences. החותמת כאן היא מספר שלם, בעוד וובהוקי הסטטוס שולחים אותה כמחרוזת. השדה wa_id לא נכלל כשהלקוח משתמש בשם משתמש ואינו יכול לשתף את מספר הטלפון שלו, השדה user_id לא נכלל כשמזהי משתמשים ברמת העסק לא מופעלים אצלכם, והשדה parent_user_id לא נכלל אלא אם BSUID של ההורה מופעלים. דוגמה של Meta לחידוש:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824"
}
],
"user_preferences": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824",
"detail": "User requested to resume marketing messages",
"category": "marketing_messages",
"value": "resume",
"timestamp": 1731705721
}
]
},
"field": "user_preferences"
}
]
}
]
}מה על המערכת שלכם לעשות בעצירה?
רשמו את העצירה ברשומת הלקוח, והוציאו אותו מכל שליחה שיווקית עד שיגיע חידוש. שדה הפירוט מופיע באחד משני נוסחים: "User requested to stop marketing messages" או "User requested to resume marketing messages", אבל הקוד צריך להסתמך על ערך השדה value, לא על הטקסט.
- לשמור את ההעדפה לפי BSUID וגם לפי מספר טלפון, כי כל אחד מהם עלול להיעדר באירוע מסוים.
- להוציא את הלקוח משליחות של תבניות שיווק, כי Meta תדחה אותן בכל מקרה, עם השגיאה 131050 שמופיעה כאן.
- להחיל את ההעדפה ללקוח אחד בלבד: Meta לעולם אינה מחילה העדפה ברמת ה-BSUID של ההורה.
- בחידוש, להסיר את ההוצאה, ולשמור את רשומת ההסכמה שלכם כפי שמדיניות ה-opt-in של Meta מחייבת.
מה קורה אם user_preferences לעולם לא מגיע לשרת שלכם?
Meta אוכפת את העצירה בכל מקרה, לכן וובהוק חסר עולה לכם בשליחה שנכשלה, ולא בהפרת מדיניות. כשאתם שולחים תבנית שיווקית למי שעצר, ה-API מקבל את הבקשה, לא שולח את ההודעה, ומפעיל וובהוק סטטוס עם status failed, קוד 131050 והכותרת "Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business". טפלו בכשל הזה בדיוק כמו באירוע עצירה: רשמו אותו, והשעו שליחות שיווק נוספות לאותו לקוח.
איך זה עובד על מספר שמחובר דרך easyCoexistence?
user_preferences אינו בין השדות שמותר ל-Meta להחליף להם יעד, ולכן Meta שולחת אותו רק לכתובת ברירת המחדל של האפליקציה שנרשמה לחשבון. במספר שמחובר דרך easyCoexistence, האפליקציה הזו היא של easyCoexistence, והיא לא נרשמת כרגע ל-user_preferences, ולכן האירוע לא מגיע ליעד ישיר או ל-Forward URL. שגיאת הכשל 131050 כן מגיעה, כי היא נוסעת בשדה messages, ולכן מגיעה אליכם.
אם ה-AI שלכם שולח תבניות שיווק עם send_template, שמרו את רשימת העצירות במערכת שלכם ובדקו אותה קודם: easyCoexistence לא שומרת רשימה כזו.
טעויות נפוצות
- לראות ב-"Not interested" עצירה. הוא לא שולח וובהוק ולא עוצר משלוח, אף שהוא עלול להקטין את מגבלת הודעות השיווק לאותו לקוח.
- לשמור העדפות רק לפי wa_id. השדה הזה חסר אצל לקוחות עם שם משתמש שמספר הטלפון שלהם אינו ניתן לשיתוף, ולכן חשוב לשמור גם את ה-BSUID של הלקוח.
- להחיל עצירה על כל מי שמתחת ל-BSUID של ההורה. Meta מחילה העדפות לפי כל משתמש בנפרד, ולעולם לא ברמת ההורה.
- לנסות שוב אחרי הכשל 131050 במקום לרשום אותו כעצירה. כל ניסיון חוזר נכשל באותה צורה.
תבניות שיווק שנשלחות דרכו יוצאות מחשבון WhatsApp Business Account שלכם, והסטטוסים של הכשל שמדווחים על לקוח שעצר מגיעים לשרת שלכם ישירות או כהעברות חתומות. מ-US$ 9 עד US$ 0.75 למספר בחודש, יורד ככל שמוסיפים מספרים, עם 3 הימים הראשונים בחינם.
שאלות נפוצות
האם עצירה גם חוסמת תשובות להודעות שהלקוח שלח לכם?
התיעוד של Meta מתאר את העצירה כחלה על הודעות שיווק, והשגיאה שהיא מחזירה מזכירה הודעות שיווק במפורש. תשובות ללקוח שכתב לכם הן הודעות שירות, קטגוריה אחרת.
האם חסימת העסק מפעילה את user_preferences?
לא. וובהוק זה מופעל רק בעצירה ובחידוש בהגדרה "Offers and announcements". חסימה היא פעולה נפרדת ואינה מדווחת בשדה הזה.
האם חידוש נחשב להסכמה (opt-in)?
זה אומר שהלקוח בחר לקבל שוב את הודעות השיווק שלכם. חובות ההסכמה שלכם לפי מדיניות Meta עדיין חלות, לכן שמרו תיעוד של האופן ושל המועד שבהם הלקוח הסכים לשמוע מכם.
באיזה שדה וובהוק אני צריך להירשם?
user_preferences, ב-App Dashboard תחת WhatsApp > Configuration, באפליקציה שנרשמה לחשבון WhatsApp Business. זהו שדה נפרד משדה messages, ודורש את ההרשאה whatsapp_business_management כדי לפעול.
המשיכו לקרוא
מוכנים להתחיל?
מגדירים WhatsApp Coexistence בתוך דקות, לא חודשים. האפליקציה ממשיכה לעבוד בטלפון.
התחילו תקופת ניסיון בחינםנבדק ב-