לכל בקשת שליחה ב-API יש שדה אחד קטן עם השלכות גדולות: mode. הוא קובע אם ההודעה תיבדק מול רשימת ההסרות של החשבון לפני שהיא יוצאת. בחירה לא נכונה עולה לאחד משני הכיוונים: מפתח שחושב שיש לו הגנה שאין לו, או קוד אימות לגיטימי שנחסם בגלל הסרה ישנה. המדריך הזה עושה סדר.
שני המצבים
| מצב | מה קורה | למה הוא מיועד |
|---|---|---|
marketing (שיווקי) | ההודעה נבדקת מול רשימת ההסרות. שליחה לנמען שהוסר נדחית, בלי חיוב | מבצעים, ניוזלטרים וכל תוכן פרסומי |
transactional (תפעולי) | מדלג על בדיקת ההסרות | קודי אימות, עדכוני הזמנה ותזכורות בלבד |
ההיגיון פשוט: מי שביקש לא לקבל פרסומות עדיין צריך לקבל את קוד האימות שלו ואת אישור ההזמנה. לכן הבדיקה חלה על שיווק, ולא על תפעול.
מי מחליט: הבקשה גוברת על ההגדרה
סדר ההכרעה הוא תמיד:
modeבבקשה עצמה - אם שלחתם אותו, הוא קובע. תמיד.- ברירת המחדל של החשבון - כשהבקשה לא מציינת
mode, ההגדרה מצב שליחה ב-API בעמוד המפתחים קובעת.
לחשבון חדש ברירת המחדל היא שיווקי - כלומר בדיקת ההסרות פעילה על כל שליחה שלא הצהירה אחרת. לא בטוחים מה מוגדר אצלכם? עמוד המפתחים מציג את המצב הנוכחי ליד תיוג ברור: שיווקי · בודק הסרות או תפעולי · צינור.
ההמלצה שלנו לאינטגרציה חדשה: אל תסתמכו על ברירת המחדל. שלחו mode מפורש בכל בקשה - הקוד שלכם מתעד את הכוונה, וההתנהגות לא תשתנה אם מישהו ישנה את הגדרת החשבון.
מה קורה כששליחה שיווקית פוגשת נמען שהוסר
הבקשה נדחית עם 403 והקרדיט לא נגבה:
{
"error": {
"code": "RECIPIENT_UNSUBSCRIBED",
"message": "Recipient +9725… has unsubscribed from this workspace's messages. …"
}
}שלוש נקודות ששוות תשומת לב:
- הבדיקה מכסה גם את הרגע האחרון. גם אם הנמען מסיר את עצמו שנייה אחרי שהבקשה התקבלה, ההודעה השיווקית נעצרת לפני שליחה.
- הבדיקה מזהה רק מספרים שמסומנים כמוסרים אצלכם. מספר שמעולם לא נכנס לרשימת אנשי הקשר שלכם לא ייחסם - פירוט במדריך השליחה הראשונה.
- הקוד שלכם צריך לטפל בתשובה הזאת. היא לא תקלה - היא המערכת שעושה את העבודה. לוג, דילוג והמשך הם בדרך כלל הטיפול הנכון. אל תבנו retry על
RECIPIENT_UNSUBSCRIBED: התשובה לא תשתנה.
איך אנשים מגיעים לרשימת ההסרות מלכתחילה: איך עובדת ההסרה מרשימת התפוצה.
מצב תפעולי הוא הצהרה, לא כפתור
מעבר החשבון למצב תפעולי נעשה בעמוד המפתחים, והוא מנוסח שם בדיוק כמו שצריך להבין אותו: אתם מצהירים שההודעות הנשלחות ב-API מהחשבון הן תפעוליות - אימות, עדכוני הזמנה וכדומה - ואינן "דבר פרסומת" כהגדרתו בחוק התקשורת. שליחת תוכן שיווקי במצב תפעולי מפרה את תנאי השימוש, והאחריות עליכם.
שלושה דברים שכדאי לדעת על ההגדרה:
- רק בעלי העסק (Owner) יכולים לשנות אותה.
- ההצהרה נרשמת ברגע ההפעלה.
- היא חלה רק על בקשות בלי
modeמפורש -modeבבקשה תמיד גובר, לשני הכיוונים.
מדיניות התוכן חלה על שני המצבים
המצב קובע מי מקבל את ההודעה, לא מה מותר לכתוב בה. הודעה שתוכנה אינו עומד במדיניות התוכן של הפלטפורמה נדחית בשני המצבים באותה מידה, עם CONTENT_FLAGGED ו-HTTP 422. ההודעה לא נשלחת ולא מחויבת.
מצב תפעולי אינו פטור מזה. הוא מוותר על בדיקת ההסרה, וזה כל מה שהוא עושה.
איך בוחרים בפועל
| ההודעה | המצב הנכון |
|---|---|
| קוד אימות (OTP) | transactional |
| אישור או עדכון הזמנה | transactional |
| תזכורת תור | transactional |
| מבצע, קופון, הטבה | marketing |
| ניוזלטר, עדכון תוכן | marketing |
| תזכורת תור עם קופון בסוף | marketing - ברגע שיש בה קידום מכירות, היא דבר פרסומת |
כלל אצבע: אם ההודעה הייתה נשלחת גם בלי שום מטרה שיווקית - היא תפעולית. אם הסיבה לקיומה היא לגרום לרכישה - היא שיווקית, גם אם היא מנוסחת כשירות.
שאלות שחוזרות
מה ברירת המחדל אם לא נגעתי בכלום? בחשבון חדש: שיווקי, עם בדיקת הסרות. את המצב הנוכחי של החשבון רואים בעמוד המפתחים.
שלחתי קוד אימות למספר שהוסר וזה עבר. תקין? כן, אם הבקשה הייתה במצב תפעולי - בדיוק בשביל זה הוא קיים. הסרה חלה על דיוור שיווקי, לא על קודי אימות.
למה שליחת ה-API שלי לא מופיעה בציר הזמן של איש הקשר? שליחה שיווקית לנמען שקיים ברשימה מופיעה בציר הזמן שלו. שליחה תפעולית לא נקשרת לכרטיס איש הקשר.
קיבלתי RECIPIENT_UNSUBSCRIBED על מספר שאני בטוח שלא ביקש להסיר. בדקו את היסטוריית איש הקשר - כל הסרה רשומה שם עם מקור ותאריך. ייתכן שמישהו בצוות סימן אותו בהסרה ידנית.
חויבתי על שליחה שנדחתה? לא. דחיית RECIPIENT_UNSUBSCRIBED היא ללא חיוב.
הצעד הבא
עוד לא שלחתם הודעה ראשונה דרך ה-API? התחילו כאן: השליחה הראשונה דרך ה-API. ואם אתם רוצים להבין את הצד השני של המטבע - איך נמענים יוצאים מהרשימה ומה נרשם: איך עובדת ההסרה מרשימת התפוצה.
מדריכים נוספים במפתחים ואינטגרציות
30 הודעות חינם בפתיחת חשבון עסקי. בלי כרטיס אשראי, בלי התחייבות.
התחילו בחינם