לכל בקשת שליחה ב-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בבקשה תמיד גובר, לשני הכיוונים.
איך בוחרים בפועל
| ההודעה | המצב הנכון |
|---|---|
| קוד אימות (OTP) | transactional |
| אישור או עדכון הזמנה | transactional |
| תזכורת תור | transactional |
| מבצע, קופון, הטבה | marketing |
| ניוזלטר, עדכון תוכן | marketing |
| תזכורת תור עם קופון בסוף | marketing - ברגע שיש בה קידום מכירות, היא דבר פרסומת |
כלל אצבע: אם ההודעה הייתה נשלחת גם בלי שום מטרה שיווקית - היא תפעולית. אם הסיבה לקיומה היא לגרום לרכישה - היא שיווקית, גם אם היא מנוסחת כשירות.
שאלות שחוזרות
מה ברירת המחדל אם לא נגעתי בכלום? בחשבון חדש: שיווקי, עם בדיקת הסרות. את המצב הנוכחי של החשבון רואים בעמוד המפתחים.
שלחתי קוד אימות למספר שהוסר וזה עבר. תקין? כן, אם הבקשה הייתה במצב תפעולי - בדיוק בשביל זה הוא קיים. הסרה חלה על דיוור שיווקי, לא על קודי אימות.
למה שליחת ה-API שלי לא מופיעה בציר הזמן של איש הקשר? שליחה שיווקית לנמען שקיים ברשימה מופיעה בציר הזמן שלו. שליחה תפעולית לא נקשרת לכרטיס איש הקשר.
קיבלתי RECIPIENT_UNSUBSCRIBED על מספר שאני בטוח שלא ביקש להסיר. בדקו את היסטוריית איש הקשר - כל הסרה רשומה שם עם מקור ותאריך. ייתכן שמישהו בצוות סימן אותו בהסרה ידנית.
חויבתי על שליחה שנדחתה? לא. דחיית RECIPIENT_UNSUBSCRIBED היא ללא חיוב.
הצעד הבא
עוד לא שלחתם הודעה ראשונה דרך ה-API? התחילו כאן: השליחה הראשונה דרך ה-API. ואם אתם רוצים להבין את הצד השני של המטבע - איך נמענים יוצאים מהרשימה ומה נרשם: איך עובדת ההסרה מרשימת התפוצה.
מדריכים נוספים במפתחים ואינטגרציות
30 הודעות חינם בפתיחת חשבון עסקי. בלי כרטיס אשראי, בלי התחייבות.
התחילו בחינם