SMS API

באמצעות Contact Center AI Platform‏ (CCAI Platform), אתם יכולים להשתמש ב-SMS API כדי לטפל בהודעות SMS נכנסות ויוצאות.

אימות

כדי להשתמש ב-SMS API, צריך להזין פרטי כניסה.

כדי ליצור פרטי כניסה ל-SMS API, פועלים לפי השלבים הבאים:

  1. בפורטל של פלטפורמת CCAI, לוחצים על הגדרות > הגדרות למפתחים > ניהול פרטי כניסה ל-API.

  2. לוחצים על הלחצן + הוספת פרטי כניסה ל-API. תיפתח ההודעה Add API Credential (הוספת פרטי כניסה ל-API).

  3. מזינים שם לפרטי הכניסה.

  4. לוחצים על יצירה.

Outbound SMS API

‫Outbound SMS API מספק נקודת קצה ליצירת הודעות SMS יוצאות. כך תוכלו לשלוח הודעות SMS לצרכנים באופן אוטומטי.

יש שלוש נקודות חשובות שכדאי לקחת בחשבון כשמשתמשים ב-API הזה:

  • השירות הזה לא מיועד לשליחה של עשרות אלפי הודעות בבת אחת. המטרה היא העברת הודעות מבוססת-אירועים.

  • הלקוחות יכולים להשיב להודעת ה-SMS ולהתחיל סשן תמיכה.

  • ה-API הזה לא יפעל אם תצטרכו לשלוח כמה הודעות SMS לאותו מספר באותו יום.

תרחישים לדוגמה

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

ההבדל בין זה לבין ממשק ה-API של Sessionless Outbound SMS הוא שב-Sessionless, אתם שולחים רק את ההתראה, ואם הלקוח מגיב, הוא מקבל הודעת ברירת מחדל (אם היא מוגדרת) והשיחה לא מועברת לסוכן.

תרחישי שימוש פוטנציאליים אחרים:

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

נקודת הקצה ל-API של SMS יוצא

כתובת ה-URI הבסיסית של נקודת הקצה החדשה היא:

POST https://<subdomain>.<domain>/apps/api/v1/sms

תמיכה ב-SMS נכנס

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

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

פעולות API

בקטע הזה מפורטים פעולות ה-API, פרמטרים של גוף הבקשה וקודי התגובה.

Body and Params

צריך לכלול את השדות הבאים בגוף הבקשה ל-API:

שם השדה סוג חובה תיאור ערכים הערות
agent_id מספר שלם לא הנציג שמתאים למזהה הזה יוקצה לשיחה חדשה אם לא קיימת שיחה בין המספרים שצוינו. אם הנציג מחובר לצ'אט קיים, ההודעה תישלח בשמו.
agent_email String לא כתובת האימייל של הנציג.
chat_type String כן הודעת SMS SMSAP
chat_subtype String כן api_initiated
end_user_number String כן המספר שאליו רוצים לשלוח את הודעת הטקסט אימות: מספר טלפון תקין: +18882468888 למספר טלפון בארה"ב
outbound_number String כן מספר הטלפון היוצא שישמש לשליחת הודעת ה-SMS אימות: א) מספר הטלפון צריך להיות מספר טלפון ל-SMS שמשויך לדייר, ב) מספר הטלפון חסר, ג) מספר הטלפון לא בפורמט הנכון: +18882468888 למספר טלפון בארה"ב
הודעה String כן הודעת ה-SMS שתישלח לצרכן הודעות ארוכות: פיצול הודעות ארוכות לכמה הודעות (אמור להיות כלול ביכולת הקיימת של שליחת SMS) אימות: א) חסרה הודעה, ב) ההודעה חורגת ממספר התווים המקסימלי (ב-x)
ticket_id id לא ההגדרה תשייך את הסשן למספר כרטיס ספציפי במערכת CRM הערה: המערכת תתעלם ממזהי כרטיסים לא תקינים.

שגיאה והצלחה

Case התוצאה הצפויה העתקה
שירות ה-SMS מופעל
שירות ה-SMS היוצא מופעל
הערך של chat_type הוא OutboundSMSAPI
הערך של end_user_number סופק והוא בפורמט תקין
הערך של outbound_number סופק והוא בפורמט תקין
למספרי טלפון שאינם בארה"ב: מספר הטלפון שאינו בארה"ב מופעל
ההודעה סופקה
אין צ'אט פעיל בין outbound_number לבין end_user_number		 הפעולה בוצעה (200) דוגמה לתגובה על הצלחה
{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.000Z",
   "queued_at": null,
   "assigned_at": null,
   "ends_at": null,   "wait_duration": 0,
   "chat_duration": 0,   "rating": null,
   "has_feedback": false, 
   "out_ticket_id": null,
   "out_ticket_url": null,
   "verified": false,
   "disconnected_by": "disconnected_by_unknown",
   "fail_reason": null,
   "selected_menu": null,
   "menu_path": null,
   "agent_info": null,
   "end_user": {       "id": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}
מזהה הסוכן וכתובת האימייל שלו מצוינים שגיאה אפשר לספק רק מאפיין אחד מבין agent_id או agent_email.
סופק מזהה נציג או אימייל של נציג
הנציג לא מחובר לצ'אט קיים		 שגיאה שליחת SMS יוצאת נכשלה. הנציג לא מחובר לצ'אט.
שירות ה-SMS לא מופעל שגיאה ‫"SMS service is not enabled" (שירות ה-SMS לא מופעל).
שירות ה-SMS היוצא לא מופעל שגיאה ‫"Outbound SMS service is not enabled" ‏(שירות שליחת הודעות SMS לא מופעל)
לא צוין chat_type שגיאה ‫"chat_type needs to be provided" ‏(חובה לציין את סוג הצ'אט)
הפרמטר chat_type סופק אבל לא הוגדר כ-sms שגיאה ‫"Valid chat_type needs to be provided"
הפרמטר end_user_number סופק אבל הוא לא בפורמט תקין שגיאה ‫"end_user_number is invalid"
(הערה: מספר טלפון תקין: ‎+18882468888 למספר טלפון בארה"ב)
לא צוין מספר משתמש קצה שגיאה ‫"end_user_number is required"
הפרמטר outbound_number סופק אבל לא בפורמט תקין שגיאה ‫"outbound_number is invalid"
(הערה: מספר טלפון תקין: ‎+18882468888 למספר טלפון בארה"ב)
הפרמטר outbound_number סופק אבל לא קיים בדייר הזה שגיאה ‫"outbound_number is not found" (לא נמצא מספר יוצא)
לא צוין outbound_number שגיאה ‫"outbound_number is required" (נדרש מספר יוצא)
המספר outbound_number הוא מספר טלפון שלא נמצא בארה"ב, והשירות 'מספר טלפון שלא נמצא בארה"ב' לא מופעל שגיאה "שירות מספר טלפון שאינו בארה"ב לא מופעל"
הערה: תלוי בהגדרה מספר טלפון שאינו בארה"ב בהגדרות > SMS במהלך שיחה > הגדרות של מספר טלפון שאינו בארה"ב
ההודעה ריקה שגיאה ‫"message is required" (נדרשת הודעה)
שיחה פעילה בצ'אט בין מספר יוצא לבין מספר משתמש קצה שגיאה "שליחת ה-SMS נכשלה. הצרכן כבר נמצא בסשן SMS פעיל".
השדה ticket_id מלא אבל לא קיים במערכת לניהול קשרי לקוחות שגיאה "הכרטיס לא נמצא"

תפוגת תוקף של SMS

הודעות SMS יוצאות פעילות מיד אחרי שהן נשלחות.

כל שיחת SMS צריכה להסתיים לפני שאפשר להתחיל סשן חדש של שיחת SMS בין מספר טלפון יוצא נתון לבין מספר טלפון של לקוח. ההודעות האלה כוללות הודעות SMS יוצאות שנשלחות באמצעות ה-API. שליחת SMS יוצאת תיכשל אם יש צ'אט פעיל בין מספר הטלפון של השולח לבין מספר הטלפון של הלקוח.

אפשרויות של זמן קצוב לתגובה בצ'אט

אפשרויות ההגדרה של פסק זמן אוטומטי בצ'אט מוגדרות בהגדרות > צ'אט > תפוגה של הודעות SMS ופסק זמן כללי. כאן אפשר להגדיר כמה זמן שיחת צ'אט תישאר פעילה אם לא תהיה בה פעילות או התקדמות.

ההבדלים בין הסטטוסים בצ'אט

אלה ההבדלים בין שינויים במצב של תהליך הצ'אט:

  • מצב בחירת התור פג תוקף בצ'אטצ'אטים יוצאים שנשלחים באמצעות ה-API נחשבים במצב בחירת התור עד שהלקוח משיב

    כל שיחת צ'אט שלא התקדמה מעבר למצב של בחירת תור. ההגדרה הזו כוללת הודעות SMS יוצאות שנשלחו ולא התקבלה עליהן תשובה מלקוח. אפשר להגדיר כמה זמן הצ'אט יכול להישאר במצב הזה לפני שהוא יפוג (ההודעה נשלחה והלקוח לא הגיב בתוך הזמן שהוגדר – הצ'אט יפוג).

  • תוקף של צ'אט SMS שלא נענה (במהלך שעות הפעילות) משך הזמן שבו צ'אט יכול להישאר בתור בלי לקבל מענה לפני שהוא יפוג בשעות הפעילות שהוגדרו לתור הספציפי.

  • תוקף של צ'אט שלא נענה (במהלך שעות לא פעילות) משך הזמן שבו צ'אט יכול להישאר בתור בלי מענה לפני שהתוקף שלו יפוג מחוץ לשעות הפעילות שהוגדרו לתור הספציפי.

  • הזמן הקצוב לתפוגה של צ'אטים ב-SMS סשנים של צ'אטים ב-SMS יסתיימו באופן אוטומטי אם לא תהיה פעילות במשך [x] דקות.

פרטים על סטטוס הזמינות לצ'אט

  • כששולחים SMS יוצא באמצעות ה-API, הצ'אט נחשב פעיל אבל לא מחובר

  • שיחות ה-SMS היוצאות הפעילות נחשבות כשיחות שנמצאות במצב בחירת תור עד שהלקוח משיב.

  • שיחות צ'אט נחשבות מחוברות ברגע שהלקוח משיב ומוקצה נציג לשיחה

ההשפעה של סטטוס הצ'אט על טיימרים שהופעלו

  • שיחות פעילות שנשלחו באמצעות ה-API ולא התקבלה עליהן תגובה מהלקוח כפופות לטיימר של מצב הבחירה בתור

  • שיחות בצ'אט שמקושרות לנציג כפופות לטיימר של תפוגת שיחות יוצאות

  • אם לקוח משיב להודעה הראשונית אבל סוכן אף פעם לא מוקצה, הצ'אט לא מחובר והוא כפוף לטיימר של תפוגת צ'אט ללא מענה, במהלך שעות הפעילות או אחריהן

דוגמה לזרימת הודעות וסטטוסים של API:

  1. הודעת SMS נשלחת באמצעות ה-API ללקוח – הצ'אט נמצא במצב של בחירה בתור ולא מחובר לנציג

  2. הטיימר של תפוגת הצ'אט במצב של בחירת תור מתחיל. הצ'אט מסתיים אם הלקוח לא משיב במסגרת הזמן שנקבע.

  3. הלקוח עונה בצ'אט – הצ'אט מחובר עכשיו לנציג.

  4. הלקוח שולח את ההודעה האחרונה – טיימר זמן קצוב לתפוגה של הצ'אט ב-SMS לדואר יוצא מתחיל לפעול.

  5. השיחה הסתיימה כי הגיע הזמן הקצוב לתפוגה של הצ'אט ב-SMS.

אין טיימר לסגירת הצ'אט – בסשנים של SMS יוצאים שהופעלו על ידי API, הטיימר לסגירת הצ'אט לא פועל, ולכן לא יתרחש אירוע של סגירת צ'אט גם אחרי שהצ'אט הזה יגיע כצ'אט נכנס כשהלקוח יענה להודעה.

הגדרת התשובה

ה-API מגיב עם אובייקט קריאה יחיד, כמו שרואים במודל מתוך ‎/calls.

Sessionless Outbound SMS API

פלטפורמת CCAI מציעה API לשליחת SMS שיכול לתמוך בהודעות SMS יוצאות ללא הפעלת סשנים מקושרים.

קריאה ל-API הזו מפעילה הודעות SMS שלא מקושרות לסשן, שאפשר להפעיל אותן במהלך תהליך עבודה קיים באמצעות CCAI Platform.

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

ממשק ה-API הזה לשליחת SMS מאפשר לשלוח עד 500 הודעות בכל קריאה ל-API.

תרחישים לדוגמה

תרחישים נפוצים לשימוש ב-SMS ללא סשן:

  • הגדרה של סיסמה חד-פעמית.

  • קוד האימות

  • תזכורות לפגישות.

  • קישורים למשוב.

  • הודעות שיווקיות או לקידום מכירות.

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

נקודת קצה ל-API של SMS יוצא ללא הפעלה של סשן

מזהה ה-URI הבסיסי של נקודת הקצה הזו הוא:

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

הוספת פרטי כניסה ל-API

  1. בפורטל של פלטפורמת CCAI, עוברים אל Settings (הגדרות) > Developer Settings (הגדרות למפתחים) > API Credential management (ניהול פרטי הכניסה ל-API).

  2. לוחצים על הלחצן + הוספת פרטי כניסה ל-API. תיפתח ההודעה Add API Credential (הוספת פרטי כניסה ל-API).

  3. מזינים שם לפרטי הכניסה בשדה Name.

  4. לוחצים על יצירה.

שליחת הודעות SMS

כדי לשלוח SMS יוצא ללא הפעלה של סשן, מתקשרים אל POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms ומעבירים את פרמטרי הבקשה הבאים:

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
שם השדה סוג חובה תיאור הערות
from_phone String כן מספר הטלפון שממנו יישלחו ההודעות. חייב להיות מספר תקין בארה"ב.
הקריאה ל-API תחזיר שגיאה אם:
* מספר הטלפון לא משויך לדייר
* השדה from_phone ריק
* מספר הטלפון לא בפורמט הנכון. לדוגמה, המספר הבא הוא מספר טלפון תקין בארה"ב: +18882468888
to_phones מערך [מחרוזת] כן מספרי הטלפון שאליהם יישלחו ההודעות. כדי לוודא שהקריאה ל-API תצליח:
* מוודאים שיש לכם מספר טלפון תקין, כמו +18882468888
המספר המקסימלי של מספרי טלפון הוא 100 לכל קריאה ל-API.
הודעות ‫Array [String] כן ההודעות שרוצים לשלוח. אפשר לשלוח עד 5 הודעות נפרדות.
כל הודעה מוגבלת ל-320 תווים, ואי אפשר לחרוג מהמגבלה הזו.

תגובות מ-API

אם הקריאה ל-API תצליח, יוצגו:

  • קוד: 200

  • מזהה בקשה

    חשוב לתעד את מזהה הבקשה ברשומות המערכת. אם תצטרכו לפתור בעיה, צוות התמיכה יזדקק למזהה הבקשה כדי לעזור לכם.

אם הקריאה ל-API נכשלת, מוצגת ההודעה:

  • קוד: 4xx

  • הודעת השגיאה

הגבלות על הודעות SMS

  • ה-API מעבד עד 300 הודעות בדקה.

  • התוקף של כל ההודעות שלא עברו עיבוד יפוג תוך שעתיים.