שליחת אירוע

הבקשה POST https://api.pristo.io/v1/events/send מדווחת ל-Pristo CX על אירוע של איש קשר, למשל רכישה. בעקבות הבקשה, Pristo CX מוסיפה את איש הקשר לאוכלוסייה של התוכנית שאליה שייך מפתח ה-API או מעדכנת אותו שם, והפצות פעילות מבוססות אירועים שבוחרות בסוג האירוע הזה שולחות את השאלון שלהן ב-SMS או באימייל.

לפני שמתחילים

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

שלבים

1. בנו את גוף ה-JSON עם type ו-contact.id. הוסיפו contact.email או contact.phone כדי שאיש הקשר יוכל לקבל את הסקר.

2. שלחו את הגוף לכתובת https://api.pristo.io/v1/events/send עם הכותרות X-API-Key ו-Content-Type: application/json.

3. שמרו את ה-eventId מהתשובה.

4. בדקו את האירוע ב-Pristo CX: פתחו את איש הקשר בלשונית אוכלוסיה. האירוע מופיע בקטע אירועים, עם הסטטוס שלו.

curl -X POST "https://api.pristo.io/v1/events/send" \
  -H "X-API-Key: $PRISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "purchase",
    "contact": {
      "id": "CUST-1042",
      "email": "dana@example.com",
      "phone": "+972501234567",
      "name": "Dana",
      "lastName": "Example",
      "language": "en",
      "customFields": { "tier": "gold" }
    },
    "customFields": { "branch": "example_branch", "amount": "120" }
  }'

גוף הבקשה

שדה	סוג	חובה	מה הוא עושה
type	string	כן	הערך בשדה מזהה יחודי של סוג האירוע. 1 עד 50 תווים
contact	object	כן	איש הקשר שהאירוע קרה לו
contact.id	string	כן	המזהה שלכם לאיש הקשר, 1 עד 50 תווים. לפי המזהה הזה Pristo CX מאתרת איש קשר קיים, בלי הבחנה בין אותיות גדולות לקטנות, או יוצרת איש קשר חדש
contact.email	string	לא	כתובת האימייל של איש הקשר. המערכת מתעלמת מכתובת לא תקינה
contact.phone	string	לא	מספר נייד ישראלי, למשל +972501234567 או 0501234567. מספרים אחרים נשמרים, אבל אי אפשר לשלוח אליהם SMS
contact.name, contact.lastName	string	לא	שם פרטי ושם משפחה. ערכים ארוכים יותר נחתכים ל-50 תווים
contact.language	string	לא	קוד בן שתי אותיות, למשל he או en. אם לא שולחים אותו, איש הקשר מקבל את שפת ברירת המחדל של האוכלוסייה
contact.customFields	object	לא	ערכים של מאפייני איש הקשר. המפתח של כל ערך הוא הערך בשדה מזהה יחודי של המאפיין, בחלון מאפייני אנשי קשר. המערכת מתעלמת ממפתחות לא מוכרים ומערכים שלא מתאימים למאפיין
customFields	object	לא	ערכים של מאפייני האירוע. המפתח של כל ערך הוא הערך בשדה מזהה יחודי של מאפיין האירוע, בלשונית מאפיינים. מסנני ההפצה קוראים כל ערך לפי הסוג של מאפיין האירוע, וערך שאי אפשר לקרוא כך לא עומד בתנאי של המסנן

חוץ מ-contact.language, שדות שלא שולחים שומרים על הערכים שכבר שמורים אצל איש הקשר. ה-API מתעלם משדות שהוא לא מכיר, כמו occurredAt: זמן האירוע הוא הזמן שבו Pristo CX מקבלת אותו.

התוצאה

ה-API עונה 200 OK עם המזהה של האירוע:

{
  "eventId": "AbCdEfGhIjKlMnOpQrStUv"
}

התשובה 200 אומרת שהאירוע נשמר ב-Pristo CX. לאחר מכן Pristo CX מעדכנת את איש הקשר ומתזמנת את הסקר, ולכן הם מופיעים זמן קצר אחרי שהקריאה מסתיימת, לא בזמן שהיא רצה.

הנתיב הישן POST /v1/events/send/{popId} עדיין עובד ועושה אותו דבר. המערכת מתעלמת מה-popId שלו: האוכלוסייה נקבעת תמיד לפי התוכנית של מפתח ה-API. בקוד חדש השתמשו ב-/v1/events/send.

מגבלות

• גוף הבקשה יכול להיות עד 10,000 בייטים. רק השדות שה-API מכיר נספרים במגבלה, וכל תו שאינו ASCII, למשל אות בעברית, נספר כ-6 בייטים.
• type ו-contact.id: 1 עד 50 תווים כל אחד.
• כללי המרווח של ההפצה קובעים באיזו תדירות איש קשר יכול לקבל את הסקר. גם במרווח של 0 ימים נשמרות לפחות 10 דקות בין שני סקרים לאותו איש קשר, כולל סקרים שתוזמנו ועדיין לא נשלחו.

פתרון בעיות

ה-API החזיר 200, אבל לא נשלח סקר. בדקו ש-type תואם לסוג אירוע שהפצה פעילה מבוססת אירועים בוחרת בו, ושלאיש הקשר יש כתובת אימייל להפצה באימייל או מספר נייד ישראלי להפצה ב-SMS. איש קשר שהוסר מרשימת התפוצה, או שלא תואם למסננים של ההפצה, לא מקבל כלום. גם ההשהיה וחלונות השליחה של ההפצה יכולים לדחות את השליחה למועד מאוחר יותר.

ה-API החזיר 404 עם no population is associated with this api key. לתוכנית של מפתח ה-API אין אוכלוסייה. צרו קודם את האוכלוסייה, או השתמשו במפתח של תוכנית שיש לה אוכלוסייה.

השפה של איש הקשר השתנתה. כש-contact.language חסר, Pristo CX מגדירה לאיש הקשר את שפת ברירת המחדל של האוכלוסייה. שלחו את contact.language בכל אירוע.

ה-API החזיר 400 או 401. ברוב תשובות ה-400 הגוף מתאר את הבעיה בטקסט פשוט. תשובת 401 פירושה שמפתח ה-API חסר או לא פעיל. ראו שגיאות API.

ראו גם

• שליחת סקרים אחרי אירוע
• סקירה כללית של אוכלוסיות
• ייבוא פעילויות
• אימות באמצעות מפתח API
• שגיאות API
• תיעוד ה-API: שליחת אירוע (באנגלית)