שיטות API של SDK לאינטרנט ללא ממשק משתמש

בדף הזה מפורטות השיטות של ה-API שזמינות ל-SDK לאינטרנט ללא ממשק משתמש.

החברה והתפריטים

שיטות לטיפול בערכים ובתפריטים של החברה.

Methods

ה-SDK ללא ממשק משתמש מספק שיטות שונות שאפשר להפעיל במופע של הלקוח.

הנה כמה דוגמאות:

החברה והתפריטים

שם השיטה תיאור
getCompany אחזור של פרטי החברה שהוגדרו.
getMenus רשימה של כל התפריטים הזמינים לדייר נתון.
getWaitTimes בתפריט אפשר לראות את זמני ההמתנה הנוכחיים בערוצים השונים.

getCompany

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

חתימת השיטה

getCompany(): Promise<CompanyResponse>

הערך המוחזר

מחזירה אובייקט CompanyResponse.

ממשקים

interface CompanyResponse {
  name: string;
  subdomain: string;
  support_email: string;
  languages: LanguageOption[];
  action_tracking: boolean;
  email_transcripts: boolean;
  message_preview: boolean;
  email_enhancement: boolean;
  display_history: boolean;
  use_recording: boolean;
  use_web: boolean;
  cobrowse_domain?: string;
}

דוגמה לשימוש

try {
  const company = await client.getCompany()
} catch (error) {
  // handle error
}

getMenus

השיטה הזו משמשת להצגת רשימה של כל פריטי התפריט שזמינים למכונה. השדה MenuResponse.direct מציין אם התוצאה הגיעה ממפתח גישה ישירה (direct.key: true) או מגישה ישירה ברמת המשתמש (direct.user: true) – שניהם משפיעים על אופן הצגת התפריטים.

חתימת השיטה

getMenus(key?: string, lang?: string): Promise<MenuResponse>

הערך המוחזר

מחזירה אובייקט MenuResponse.

ממשקים

interface MenuResponse {
  menus: MenuItem[];
  direct: {
    key: boolean;
    user: boolean;
    key_id: number | null;
  };
}
interface MenuItem {
  id: number;
  name?: string;
  enabled: boolean;
  redirection?: {
    option: string;
    data: string;
  };
  children?: MenuItem[];
  channels: MenuChannel[];
  deflection?: {
    enabled: boolean;
    type: string;
  };
  hidden: boolean;
}

דוגמה לשימוש

try {
  const data: MenuResponse = await client.getMenus("direct_menu_key")
  console.log(data.menus)
  console.log(data.direct)
} catch (error) {
  // handle error
}

getWaitTimes

הפונקציה מאחזרת את זמן ההמתנה המשוער (בשניות) לערוצי הצ'אט והשיחות הקוליות של תפריט נתון.

חתימת השיטה

getWaitTimes(menuId: number | string, lang?: string): Promise<WaitTimeResponse | null>

הערך המוחזר

מחזירה אובייקט WaitTimeResponse או null.

ממשקים

interface WaitTimeResponse {
  chat: number;
  voice_call: number;
}

דוגמה לשימוש

try {
  const data = await client.getWaitTimes(123)
} catch (error) {
  // handle error
}

שיחות

שם תיאור
createCall יוצרים שיחה מיידית או מתוזמנת.
loadCall קבלת מידע ממזהה שיחה נתון.
cancelCall ביטול השיחה עם מזהה השיחה שצוין.
getTimeSlots קבלת משבצות זמן פנויות לשיחות מתוזמנות לתפריט נתון.
fetchTimeSlotAvailability בודקים אם יש משבצות זמן פנויות בתפריט מסוים.

createCall

יצירת שיחה חדשה לתפריט הנתון. השיחה יכולה להיות מיידית או מתוזמנת, בהתאם לשדה scheduled_at. סוג הקריאה (web_instant_call לעומת web_scheduled_call) נקבע באופן אוטומטי על סמך הנוכחות של scheduled_at. השדה reschedule_call_id נשלח ברמה העליונה של הבקשה, בנפרד מגוף הקריאה. הערך menu_id בתגובה מנורמל מהערך selected_menu.id של ה-API.

חתימת השיטה

createCall(menuId: number | string, data: CallRequest): Promise<CallResponse>

הערך המוחזר

מחזירה אובייקט CallResponse.

ממשקים

interface CallRequest {
  phone_number: string;
  lang?: string;
  scheduled_at?: string;
  ticket_id?: string;
  email?: string;
  recording_permission?: "recording_permission_not_asked" | "recording_permission_granted" | "recording_permission_denied";
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
  reschedule_call_id?: number;
}

דוגמה לשימוש

try {
 const call = await client.createCall(123, { phone_number: '+12345678' })
} catch (error) {
 // handle error
}

loadCall

ה-method‏ loadCall מאחזרת מידע על שיחה ספציפית, לפי המזהה שלה.

חתימת השיטה

loadCall(callId: number | string): Promise<CallResponse>

הערך המוחזר

מחזירה אובייקט CallResponse.

ממשקים

interface CallResponse {
 id: number;
 lang: string;
 menu_id: number;
 status: string;
 type: string;
 scheduled_at?: string;
 recording_permitted: boolean;
 survey_enabled: boolean;
 created_at: string;
 menus: {
   id: number;
   name: string;
 }[];
}

דוגמה לשימוש

try {
 const call = await client.loadCall(1234)
} catch (error) {
 // handle error
}

cancelCall

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

חתימת השיטה

cancelCall(callId: number | string): Promise<CallResponse>

הערך המוחזר

מחזירה אובייקט CallResponse.

ממשקים

interface CallResponse {
 id: number;
 lang: string;
 menu_id: number;
 status: string;
 type: string;
 scheduled_at?: string;
 recording_permitted: boolean;
 survey_enabled: boolean;
 created_at: string;
 menus: {
   id: number;
   name: string;
 }[];
}

דוגמה לשימוש

try {
 const response = await client.cancelCall(1234)
} catch (error) {
 // handle error
}

getTimeSlots

אחזור של משבצות זמן פנויות לשיחות מתוזמנות בתפריט נתון. כשמפעילים את הפונקציה עם אובייקט האפשרויות GetTimeSlotsRequest, אפשר לקבוע מחדש שיחה קיימת באמצעות rescheduleCallId. החתימה של המחרוזת lang שהוצאה משימוש עדיין נתמכת ומנתבת לאותה נקודת קצה, ורק lang מאוכלס. הפונקציה מחזירה מערך של מחרוזות של משבצות זמן.

חתימת השיטה

getTimeSlots(menuId: number | string, options?: GetTimeSlotsRequest): Promise<string[]>

הערך המוחזר

הפונקציה מחזירה מערך של מחרוזות (משבצות זמן).

ממשקים

interface GetTimeSlotsRequest {
 lang?: string;
 rescheduleCallId?: number;          // ID of an existing call being rescheduled
}

דוגמה לשימוש

// New options-based signature (recommended)
try {
 const slots = await client.getTimeSlots(123, {
   lang: 'en',
   rescheduleCallId: 98765, // optional: pass when rescheduling an existing call
 })
} catch (error) {
 // handle error
}
// Deprecated signature (still supported)
try {
 const slots = await client.getTimeSlots(123, 'en')
} catch (error) {
 // handle error
}

fetchTimeSlotAvailability

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

היקף

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

תרחישים נפוצים לדוגמה:

  • הצגת קריאה לפעולה של "קביעת שיחה חוזרת" רק כשיש משבצות זמן פנויות.

  • העברה לתהליך חלופי (למשל, אימייל, הודעה מחוץ לשעות הפעילות) כשאין משבצות פנויות, בלי לשלם על שיחת getTimeSlots מלאה.

  • בדיקה מקדימה של פעולת תזמון מחדש לפני קריאה ל-getTimeSlots עם rescheduleCallId.

חתימת השיטה

fetchTimeSlotAvailability(menuId: number | string, lang?: string): Promise<boolean>

הערך המוחזר

הפונקציה מחזירה את הערך true אם יש משבצות זמן זמינות, ואת הערך false אם אין.

דוגמה לשימוש

try {
 const isAvailable = await client.fetchTimeSlotAvailability(123, 'en')
 if (isAvailable) {
   // Show scheduling UI
 }
} catch (error) {
 // handle error
}

צ'אטים

שם תיאור
createChat יצירת שיחה חדשה.
loadChat אחזור של שיחה לפי מזהה השיחה שצוין.
loadOngoingChat ניסיונות לטעון שיחת צ'אט פעילה.
resumeChat המשך שיחה שנסגרה עם מזהה שיחה נתון.
finishChat הגדרת הסטטוס של הצ'אט הנוכחי כ"הסתיים".
destroyChat מפעיל את finishChat ומוחק את הצ'אט הנוכחי
fetchMessages אחזור של הודעות קודמות – הפעולה מחזירה את הערך [] אם היא נכשלת.
sendTextMessage שליחת הודעת SMS.
sendFileMessage שליחת הודעה עם קובץ – הפונקציה מחזירה את הערך -1 אם ההעלאה נכשלת.
sendPreviewMessage שליחת הודעה לתצוגה מקדימה.
getChatDeflection אחזור ההגדרות של הפניית הצ'אט.
sendChatTranscripts שליחת תמליל של הצ'אט לכתובות האימייל שצוינו.
downloadChatTranscript הורדת תמליל הצ'אט.
getPdfStatus מקבלת את סטטוס ה-PDF של תמליל.
getChatSurvey מקבל את השאלות בסקר של הצ'אט.
sendChatSurvey שליחת משוב משתמשים מהסקר.
sendChatRate שליחת משוב על הצ'אט.
escalateChat מעביר את הצ'אט מנציג וירטואלי לנציג אנושי.
trackChatEscalation מעקב אחרי אירוע של העברת צ'אט לטיפול ברמה גבוהה יותר.
trackChatEndUserEvent מעקב אחרי אירוע של משתמש קצה.
getChatHistory אחזור ההיסטוריה של צ'אט נתון.

שיחת עדכון בצ'אט

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

שם תיאור
checkIn שליחת אות לשרת כדי לאשר שהמשתמש נמצא בתור.
exitCheckIn הסרת המשתמש מתור הצ'ק-אין.
notifyCheckInState הפונקציה מודיעה לקצה העורפי על מצב החשיפה של חלון העזר של הצ'ק-אין.
rejoinChat המשתמש מוחזר לתור אם הוא לא מאשר את הצ'ק-אין.
trackCheckInEvent שליחת אותות לקצה העורפי כשאירועי צ'ק-אין מופעלים על ידי ממשק המשתמש.

checkIn

שולח אות אישור לשרת שמציין שהלקוח נוכח ומוכן להתחבר לנציג במהלך חלון הצ'ק-אין. עדכון של check_in_status בצ'אט באופן מקומי אחרי שהשרת מאשר. משתמשים בו בתגובה לאירוע chat.checkInRequested.

חתימת השיטה

checkIn(): Promise<CheckInResponse>

הערך המוחזר

מחזירה אובייקט CheckInResponse.

ממשקים

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

דוגמה לשימוש

try {
 const response = await client.checkIn()
} catch (error) {
 // handle error
}

exitCheckIn

שליחת אות לשרת שהלקוח בחר לעזוב את תור הצ'ק-אין. מעדכן את check_in_status באופן מקומי. אחרי שמפעילים את ה-method הזו, הלקוח לא יקבל חיבור לנציג במחזור הצ'ק-אין הנוכחי.

חתימת השיטה

exitCheckIn(): Promise<CheckInResponse>

הערך המוחזר

מחזירה אובייקט CheckInResponse.

ממשקים

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

דוגמה לשימוש

try {
 const response = await client.exitCheckIn()
} catch (error) {
 // handle error
}

notifyCheckInState

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

חתימת השיטה

notifyCheckInState(data: CheckInVisibilityStateRequest): Promise<void>

ממשקים

interface CheckInVisibilityStateRequest {
 widget_minimized?: boolean;
 tab_inactive?: boolean;
}

דוגמה לשימוש

try {
 const visibilityState = {
   widget_minimized: true,
   tab_inactive: false,
 }
 await client.notifyCheckInState(visibilityState)
} catch (error) {
 // handle error
}

rejoinChat

הלקוח חוזר לתור אם הוא לא אישר את הצ'ק-אין בפרק הזמן שהוקצב. מעדכן את check_in_status באופן מקומי. צריך להשתמש בה בתגובה לאירוע chat.checkInTimedOut אם הצרכן עדיין רוצה להתחבר.

חתימת השיטה

rejoinChat(): Promise<CheckInResponse>

ערך מוחזר: מחזיר אובייקט CheckInResponse.

ממשקים

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

דוגמה לשימוש

try {
 const response = await client.rejoinChat()
} catch (error) {
 // handle error
}

trackCheckInEvent

הודעה לשרת שהמודל של הצ'ק-אין הוצג לצרכן. צריך להפעיל את הפונקציה הזו פעם אחת, מיד אחרי שמציגים את ממשק המשתמש של הצ'ק-אין בתגובה ל-chat.checkInRequested. השרת משתמש בנתונים האלה לניתוח תפעולי של שיעורי ההצגה של הצ'ק-אין. הקריאה ממתינה באופן פנימי ומחזירה Promise<void> שיכול להידחות, לכן צריך לעטוף אותה ב-try/catch (כמו בדוגמה הבאה).

חתימת השיטה

trackCheckInEvent(): Promise<void>

דוגמה לשימוש

try {
 await client.trackCheckInEvent()
} catch (error) {
 // handle error
}

getMessageAttachment

אחזור קובץ מצורף שעומד בדרישות ומשויך להודעת צ'אט ספציפית. האפליקציה מאחזרת רק אם ההודעה נשלחה על ידי מישהו שהוא לא משתמש קצה ($userType !== 'end_user') ואם סוג הקובץ המצורף נתמך (תמונה, סרטון, אודיו, מסמך). הפונקציה מחזירה את הערך null לכל הודעה שלא עומדת בשני התנאים, ולא רק להודעות בלי media_id. שומר את הקובץ שאוחזר במטמון המדיה המקומי של הצ'אט אחרי האחזור.

חתימת השיטה

getMessageAttachment(message: MessageResponse): Promise<File | null>

הערך המוחזר

הפונקציה מחזירה אובייקט File אם הוא נמצא, או null אם הוא לא רלוונטי.

דוגמה לשימוש

try {
 const file = await client.getMessageAttachment(message)
} catch (error) {
 // handle error
}

createChat

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

אחרי הקריאה הראשונית ל-API, ה-method שולחת סקר לשרת עד ש-provider_channel_id הופך לזמין או עד שהצ'אט מבוטל או מסתיים. אם ערוץ של ספק הופך לזמין, השיטה יוזמת את החיבור לספק בזמן אמת. יכול להיות שהחיבור עדיין לא יושלם כשההבטחה תתממש – צריך להאזין לאירוע chat.connectedMessages כדי לדעת מתי החיבור ואחזור ההודעה הראשונית הושלמו.

חתימת השיטה

createChat(menuId: number | string, data: ChatRequest): Promise<Chat>

הערך המוחזר

הפונקציה מחזירה מופע של Chat.

ממשקים

interface ChatRequest {
  lang?: string;
  trigger_id?: string;
  ticket_id?: string;
  email?: string;
  greeting?: string;
  cobrowsable?: boolean;
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
}

דוגמה לשימוש

try {
 const chat = await client.createChat(123, { lang: 'en' })
} catch (error) {
 // handle error
}

loadChat

אחזור של שיחת צ'אט קיימת לפי המזהה שלה.

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

חתימת השיטה

loadChat(chatId: number | string): Promise<Chat>

הערך המוחזר

הפונקציה מחזירה מופע של Chat.

דוגמה לשימוש

try {
 const chat = await client.loadChat(1234)
} catch (error) {
 // handle error
}

loadOngoingChat

מנסה לטעון את שיחת הצ'אט הפעילה, אם יש כזו. אם לא נמצא צ'אט פעיל, הפונקציה מחזירה את הערך null.

חתימת השיטה

loadOngoingChat(): Promise<Chat | null>

הערך המוחזר

הפונקציה מחזירה מופע של Chat אם נמצאה שיחה פעילה, או ערך null אם אין שיחה פעילה. אם השיחה לא נמשכת, ערכי האחסון יימחקו.

דוגמה לשימוש

try {
 const chat = await client.loadOngoingChat()
} catch (error) {
 // handle error
}

resumeChat

הפונקציה הזו מחדשת שיחה שנסגרה לפי המזהה שלה, ומאפשרת ללקוח להמשיך את השיחה.

אם ללקוח כבר יש הפניה לצ'אט עם אותו מזהה, השיטה מקצרת את התהליך: היא מתקנת את הסטטוס ל-queued במופע הקיים במקום לאחזר מופע חדש. אם המזהים לא תואמים, נוצר מופע חדש של Chat והוא נרשם.

חתימת השיטה

resumeChat(chatId: number | string): Promise<Chat>

הערך המוחזר

הפונקציה מחזירה מופע של Chat.

דוגמה לשימוש

try {
 const chat = await client.resumeChat(1234)
} catch (error) {
 // handle error
}

finishChat

הפרמטר הזה מגדיר את הסטטוס של שיחת הצ'אט הנוכחית כ"הסתיימה". הפעולה הזו מסיימת את הצ'אט מהצד של הלקוח.

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

חתימת השיטה

finishChat(): Promise<void>

דוגמה לשימוש

try {
 await client.finishChat()
} catch (error) {
 // handle error
}

destroyChat

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

חתימת השיטה

destroyChat(): Promise<void>

דוגמה לשימוש

try {
 await client.destroyChat()
} catch (error) {
 // handle error
}

fetchMessages

אחזור של היסטוריית ההודעות של הסשן הנוכחי בצ'אט מספק ה-real-time. צריך להפעיל אותה אחרי שהצ'אט מחובר. אם מפעילים אותה לפני שהצ'אט מחובר, היא מחזירה מערך ריק במקום להפעיל את הפונקציה. הוא מאחזר באופן אוטומטי כתובות URL של מסמכים לכל ההודעות מסוג document וממזג אותן בתשובה. בהודעות מסוג server_message, מאחזר את תוכן ההודעה של הנציג הווירטואלי של המשימה ומעצב אותו בתוך השורה. אם הפעולה נכשלת, הפונקציה מחזירה מערך ריק במקום להציג שגיאה.

חתימת השיטה

fetchMessages(): Promise<MessageResponse[]>

הערך המוחזר

מחזירה מערך של MessageResponse. אם הפעולה נכשלת, הפונקציה מחזירה מערך ריק.

ממשקים

interface MessageResponse {
  $index: number;
  $sid: string;
  $timestamp: Date;
  $userType: string;
  $userId: number;
  type: string;
  content?: string;
  event?: string;
  file?: File;
  media_id?: number;
  groupMessageId?: number;
  document?: {
    url: string;
  };
  unredacted?: string;
  buttons?: {
    title: string;
  }[];
  message?: { messages: string[], type };
  signature?: string,
  form?: {
    id: number,
    form_type: string,
    name: string,
    title: string,
    subtitle: string,
    external_form_id: string,
    smart_action_id: number,
    image: string
  }

  // allow extra parameters
  [key: string]: unknown;
}

דוגמה לשימוש

const messages = await client.fetchMessages()

sendTextMessage

שליחת הודעת טקסט בשיחת הצ'אט הנוכחית.

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

חתימת השיטה

sendTextMessage(rawContent: string): Promise<void>

דוגמה לשימוש

try {
 await client.sendTextMessage("hello world")
} catch (error) {
 // handle error
}

sendFileMessage

העלאת קובץ לסשן הצ'אט הנוכחי בתהליך של שלושה שלבים: קבלת כתובת URL חתומה מראש לאחסון בענן מהשרת, העלאת הקובץ ישירות לכתובת ה-URL הזו, ואז אישור ההעלאה בחזרה לשרת. נתיב ההעלאה נקבע אוטומטית לפי סוג ה-MIME של הקובץ: תמונות נשלחות כהודעות תמונה וסרטונים כהודעות וידאו. סוגי קבצים אחרים מנותבים לפי סוג ה-MIME שלהם. הפונקציה מחזירה את מזהה ההודעה אם היא נשלחה בהצלחה, או -1 אם היא נכשלה.

חתימת השיטה

sendFileMessage(file: File): Promise<number>

הערך המוחזר

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

דוגמה לשימוש

const input = document.querySelector('input[type="file"]')
const file = input.files[0]
try {
  const id = await client.sendFileMessage(file)
  if (id === -1) {
    // handle upload failure
  }
} catch (error) {
  // handle message-send failure
}

sendPreviewMessage

שליחת הודעה מקדימה בשיחת הצ'אט הנוכחית. הודעות תצוגה מקדימה משמשות בדרך כלל כדי להראות לנציג מה הצרכן מקליד לפני שההודעה נשלחת. אם גם redaction_enabled וגם agent_incoming_ha_enabled מוגדרים כ-true במצב הצ'אט, התצוגה המקדימה נשלחת דרך נקודת קצה של השרת (POST /chats/{id}/redact_messages) ולא דרך הערוץ של ספק הנתונים בזמן אמת.

חתימת השיטה

sendPreviewMessage(content: string): Promise<void>

דוגמה לשימוש

try {
 await client.sendPreviewMessage('preview content')
} catch (error) {
 // handle error
}

getChatDeflection

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

הפונקציה מחזירה null אם לא הופעלה הפניית שיחות בצ'אט (השדה enabled בתגובת השרת הוא falsy). לפני קריאת התגובה, צריך לבדוק אם הערך הוא null.

חתימת השיטה

getChatDeflection(): Promise<ChatDeflectionResponse | null>

הערך המוחזר

הפונקציה מחזירה אובייקט ChatDeflectionResponse או null אם לא הופעלה הפניית משתמשים לצ'אט.

ממשקים

interface ChatDeflectionResponse {
 enabled: boolean;
 threshold: number;
 email: boolean;
 keep_waiting: boolean;
 external_deflection_links: {
   enabled: boolean;
   ids: number[];
 };
}

דוגמה לשימוש

try {
 const deflection = await client.getChatDeflection()
} catch (error) {
 // handle error
}

sendChatTranscripts

שליחת התמליל של הצ'אט הנוכחי לכתובות האימייל שצוינו.

חתימת השיטה

sendChatTranscripts(emails: string[]): Promise<void>

דוגמה לשימוש

try {
 await client.sendChatTranscripts([
   "name1@example.com",
   "name2@example.com",
 ])
} catch (error) {
 // handle error
}

downloadChatTranscript

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

חתימת השיטה

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

הערך המוחזר

מחזירה את אובייקט התמליל.

ממשקים

interface GenerateTranscriptResponse {
 status: string;
 chat_transcript_id: number;
}

דוגמה לשימוש

try {
 const resp = await client.downloadChatTranscript()
} catch (error) {
 // handle error
}

getPdfStatus

בודק את סטטוס היצירה של קובץ PDF של תמליל צ'אט שהתבקש בעבר. משתמשים בערך chat_transcript_id שמוחזר על ידי downloadChatTranscript כדי לבדוק אם הפעולה הושלמה.

חתימת השיטה

getPdfStatus(id: number): Promise<RequestReturn>

הערך המוחזר

מחזירה את אובייקט הסטטוס של קובץ ה-PDF.

ממשקים

interface RequestReturn {
   //...
   headers,
   data: PdfStatusResponse,
 }


 interface PdfStatusResponse {
   status: string;
   body?: File;
   failed_reason?: string;
 }

דוגמה לשימוש

const response = await client.getPdfStatus(pdfId)
// check header for status
const status = response.headers['x-transcript-status'];
// otherwise use status on data
const data = response.data
console.log(data.status)

getChatSurvey

אחזור של שאלות הסקר שאחרי הצ'אט שהוגדרו לסשן הצ'אט הנוכחי. הסקר מוצג לצרכנים אחרי שהצ'אט מסתיים.

חתימת השיטה

getChatSurvey(): Promise<ChatSurveyResponse | null>

הערך המוחזר

הפונקציה מחזירה אובייקט ChatSurveyResponse או ערך null.

ממשקים

interface QuestionItem {
 id: number;
 type: "csat" | "star" | "free-form" | "scale" | "enumeration";
 display_text: string;
 name?: string;
 is_csat?: boolean;
 position?: number;
 valid_answers?: {
   key: string;
   value: string;
 }[]
}
interface ChatSurveyResponse {
 id?: number;
 lang?: string;
 sign_off_display_text: string;
 questions: QuestionItem[];
}

דוגמה לשימוש

try {
 const data = await client.getChatSurvey()
 if (data) {
   console.log(data.questions)
 }
} catch (error) {
 // handle error
}

sendChatSurvey

שליחת התשובות של הצרכן לסקר שאחרי הצ'אט. כל תשובה מקושרת למזהה השאלה.

חתימת השיטה

sendChatSurvey(answers: SurveyAnswers): Promise<void>

ממשקים

interface SurveyAnswers {
 [question_id: string]: number | string;
}

דוגמה לשימוש

try {
 await client.sendChatSurvey({
   123: "a",
   231: "b",
 })
} catch (error) {
 // handle error
}

sendChatRate

שליחת הדירוג והמשוב האופציונלי של הצרכן לגבי סשן הצ'אט. משמש כשסוג המשוב אחרי הצ'אט הוא דירוג ולא סקר מלא.

חתימת השיטה

sendChatRate(data: RateRequest): Promise<void>

ממשקים

interface RateRequest {
 rating: number;
 feedback?: string;
}

דוגמה לשימוש

try {
 await client.sendChatRate({
   rating: 5,
   feedback: "Very good service",
 })
} catch (error) {
 // handle error
}

escalateChat

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

חתימת השיטה

escalateChat(data?: EscalateRequest): Promise<void>

ממשקים

interface EscalateRequest {
 force_escalate: boolean;
 menu_id: number;
 lang: string;
}

דוגמה לשימוש

try {
 // Escalate to a specific menu in a given language
 await client.escalateChat({
   force_escalate: true,
   menu_id: 123,
   lang: 'en',
 })
} catch (error) {
 // handle error
}
// Or, escalate without arguments to use defaults
try {
 await client.escalateChat()
} catch (error) {
 // handle error
}

trackChatEscalation

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

חתימת השיטה

trackChatEscalation(escalationId: number, channel: string): Promise<void>

דוגמה לשימוש

try {
 await client.trackChatEscalation(escalationId, channel)
} catch (error) {
 // handle error
}

trackChatEndUserEvent

מעקב אחרי אירוע מותאם אישית של משתמש קצה במהלך הסשן בצ'אט, שאפשר להשתמש בו לניתוח נתונים או להפעלת תהליכי עבודה בקצה העורפי. אם האובייקט data לא כולל את end_user_name ויש שם זמין בפרופיל המשתמש המאומת, הוא מאוכלס באופן אוטומטי לפני שהבקשה נשלחת.

חתימת השיטה

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

הערך המוחזר

מחזירה void.

ממשקים

interface ChatEndUserEventRequest {
  event: {
    name: string;
    payload: Record<string, string>;
  };
  end_user_name?: string;
}

דוגמה לשימוש

try {
 await client.trackChatEndUserEvent({
   event: {
     name: 'add_to_cart',
     payload: {
       product_id: 'sku-1234',
       quantity: '2',
     },
   },
   // end_user_name is auto-populated from the authenticated user
   // profile if omitted
 })
} catch (error) {
 // handle error
}

getChatHistory

אחזור של היסטוריית הצ'אט של הצרכן, כולל תוכן ההודעות והמטא-נתונים. התוצאות מחולקות לדפים. בדף 1 מוחזרות עד 2 שיחות, ובדפים הבאים מוחזרת שיחה אחת בכל דף. העימוד האסימטרי הזה הוא מכוון ומאפשר לקריאה הראשונה לטעון מראש את ההקשר של ההיסטוריה הסמוכה.

חתימת השיטה

getChatHistory(page?: number): Promise<ChatHistoryResponse | null>

הערך המוחזר

מחזירה אובייקט ChatHistoryResponse או null.

ממשקים

interface ChatHistoryItem {
 comm_id: number;
 assigned_at: string;
 comm_type: string;
 timezone: string;
 entries: MessageResponse[];
 [key: string]: unknown;
}
interface ChatHistoryResponse {
 chats: ChatHistoryItem[];
 missing_chat_ids: number[];
 pagination: {
   next_page: number;
   per_page: number;
 }
}

דוגמה לשימוש

try {
 const data = await client.getChatHistory(1) // page defaults to 1 if omitted
 console.log(data)
} catch (error) {
 console.log(error)
}

אימיילים

שם תיאור
createEmail שליחת אימייל לערוץ האימייל של מזהה תפריט נתון.
getProhibitedFileTypes לבדוק אילו סוגי קבצים אסור לצרף לאימיילים.

createEmail

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

חתימת השיטה

createEmail(menuId: number | string, data: EmailRequest): Promise<EmailResponse>

הערך המוחזר

הפונקציה מחזירה אובייקט EmailResponse אם הפעולה נכשלה או הצליחה.

ממשקים

interface EmailRequest {
 name?: string;
 email: string;
 content: string;
 lang?: string;
 files?: File[];
 recaptcha?: string;
}
interface EmailResponse {
 id: number;
 type: string;
 status: string;
 fail_reason: string;
 attachment_count: number;
}

דוגמה לשימוש

try {
 await client.createEmail(123, {
   lang: "en",
   name: "User name",
   email: "name@example.com",
   content: "description of the question",
   files: input.files,
 })
} catch (error) {
 console.log(error.message)
}

getProhibitedFileTypes

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

חתימת השיטה

getProhibitedFileTypes(): Promise<FileTypeItem[]>

הערך המוחזר

מחזירה מערך של FileTypeItem.

ממשקים

interface FileTypeItem {
 extension: string;
 description: string;
}

דוגמה לשימוש

try {
 const types = await client.getProhibitedFileTypes()
} catch (error) {
 // handle error
}

שיתוף המסך

שם תיאור
createCobrowseCode יצירת קוד לגלישה משותפת.
startCobrowse לבקש סשן גלישה משותפת.
restoreCobrowseSession משחזר סשן גלישה משותפת אחרי שפותחים מחדש את חלון הדפדפן.

createCobrowseCode

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

חתימת השיטה

createCobrowseCode(lang?: string, customData?: Record<string, string>): Promise<string>

הערך המוחזר

מחזירה מחרוזת של קוד גלישה משותפת או מחרוזת ריקה ('') במקרה של כישלון.

דוגמה לשימוש

const code = await client.createCobrowseCode()
// 123456

startCobrowse

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

חתימת השיטה

startCobrowse(from?: string): Promise<void>

דוגמה לשימוש

try {
 await client.startCobrowse()
} catch (error) {
 // handle error
}

restoreCobrowseSession

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

חתימת השיטה

restoreCobrowseSession(): Promise<void>

הערך המוחזר

האפליקציה מחזירה את הערך Promise<void>. השיטה הזו לא מבצעת פעולה (מחזירה מיד ללא שגיאה) אם הגלישה המשותפת לא מופעלת באפשרויות הלקוח או אם אין סשן קודם של גלישה משותפת באחסון.

דוגמה לשימוש

// Safe to call unconditionally - will no-op if cobrowse is not enabled
// or if no previous session exists
await client.restoreCobrowseSession()

נציג וירטואלי אחרי סשן

שם תיאור
updatePostSession הגדרת הסטטוס של שיחת צ'אט פעילה אחרי שהיא מסתיימת.

updatePostSession

השיטה הזו משמשת לעדכון הסטטוס של הנציג הווירטואלי אחרי הסשן בצ'אט שמתנהל.

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

  • הפונקציה מחזירה מיד ערך של no-op אם postSessionStatus הוא FINISHED או WAITING – המעברים האלה מטופלים באופן פנימי.

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

חתימת השיטה

updatePostSession(postSessionStatus: PostSessionStatus, optInSelection?: boolean): Promise<void>

ממשקים

enum PostSessionStatus {
 READY = 'ready',
 IN_PROGRESS = 'in_progress',
 WAITING = 'waiting',
 FINISHED = 'finished',
}

דוגמה לשימוש

try {
 // Without opt-in selection
 await client.updatePostSession(PostSessionStatus.READY)
 // With opt-in selection
 await client.updatePostSession(PostSessionStatus.READY, true)
} catch (error) {
 // handle error (e.g., show a notification to the user)
}

interface ChatResponse {
 //...
 post_session_required?: boolean;
 post_session_opt_in_required?: boolean;
 post_session_transfer_status?: string;
}

  • ‫post_session_required – נדרש סשן לאחר שיחת צ'אט.

  • ‫post_session_opt_in_required – האם ההצטרפות מופעלת.

  • ‫post_session_transfer_status – אחד מהערכים של PostSessionStatus.

ניפוי באגים

שם תיאור
getLogs אחזור של יומני ניפוי באגים פנימיים מה-SDK.
printLogs הדפסת יומני ניפוי באגים פנימיים במסוף הדפדפן.

getLogs

מאחזר את יומני ניפוי הבאגים הפנימיים שנאספו על ידי ה-SDK, כולל יומנים ברמת הגשר וברמת הבסיס. המידע הזה שימושי לפתרון בעיות בשילוב.

חתימת השיטה

getLogs(): Promise<{ bridgeLogs: LogHistoryData[], rootLogs: LogHistoryData[] }>

הערך המוחזר

הפונקציה מחזירה אובייקט שמכיל שני מערכים של LogHistoryData.

ממשקים

interface LogHistoryData {
 date: string;
 channel: string;
 level: string;
 args: any[];
}

רמת הפירוט

כל רשומה של LogHistoryData מתעדת אירוע יומן אחד:

  • ‫date – חותמת זמן של האירוע בפורמט ISO 8601.

  • ‫channel – מודול ה-SDK שהפיק את האירוע (למשל, לקוח ברמה העליונה, שכבת צ'אט, שכבת גלישה משותפת, ספק בזמן אמת).

  • ‫level – רמת החומרה של היומן: debug, ‏info, ‏warn או error.

  • args – הארגומנטים הגולמיים שתועדו על ידי קריאת היומן.

ערך לדוגמה:

{
 "date": "2026-05-08T14:02:13.412Z",
 "channel": "Provider",
 "level": "info",
 "args": ["chat connected", { "chatId": 4421 }]
}

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

‫getLogs מחזיר רשומות פנימיות של ה-SDK שנועדו לעזור באבחון בעיות בשילוב עם ה-SDK עצמו לאינטרנט ללא ממשק משתמש. השימוש העיקרי בו הוא אבחון תמיכה: כשמשתמש קצה מדווח על בעיה, האפליקציה יכולה לתעד את התוצאה של getLogs ולצרף אותה לכרטיס התמיכה שנשלח אל פלטפורמת CCAI.

היומנים שמוחזרים לא כוללים:

  • נתוני הטלמטריה של האפליקציה, האירועים העסקיים או הניווט של המשתמשים בדף המארח.

  • כשלים ברשת שהדפדפן לא מציג ל-SDK (למשל, שגיאות CORS, תוכן מעורב או שגיאות אישור).

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

‫getLogs לא מחליף את כלי הניטור שלכם. מומלץ לשלב את ה-SDK עם:

  • כלי למעקב אחר שגיאות/RUM בצד הדפדפן (Sentry,‏ Datadog Browser RUM,‏ New Relic Browser או כלי דומה).

  • רישום ביומן בצד השרת בנקודת הקצה לאימות (authenticate הקריאה החוזרת (callback) שה-SDK מבצע).

  • מאזינים ברמת האפליקציה ב-chat.disconnected, ב-chat.timeout וב-chat.ended, אם אתם צריכים להעביר אותות של מחזור החיים של הצ'אט לצינור עיבוד הנתונים של הטלמטריה שלכם.

דוגמה לשימוש

try {
 const { bridgeLogs, rootLogs } = await client.getLogs()
 console.log('Bridge logs:', bridgeLogs)
 console.log('Root logs:', rootLogs)
} catch (error) {
 // handle error
}

printLogs

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

חתימת השיטה

printLogs(): Promise<void>

דוגמה לשימוש

try {
 await client.printLogs()
} catch (error) {
 // handle error
}

שונות

שם תיאור
runTrigger בודק אם יש טריגרים יזומים שצריך להפעיל.
getAfterHourMessage מקבלים את ההודעה על הפנייה לאחר שעות הפעילות.

runTrigger

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

חתימת השיטה

runTrigger(cb: (trigger: TriggerItem) => void): Promise<void>

ממשקים

interface TriggerItem {
 id: number;
 menu_id: number;
 messages: TriggerMessage[];
 keywords_included?: string[];
 keywords_included_or?: string[][];
 keywords_excluded?: string[];
 keywords_excluded_or?: string[][];
 lang?: string;
 page_visit_count: number;
 stay_time: number;
 visitor_type: string;
}
interface TriggerMessage {
 lang: string;
 text: string;
}

דוגמה לשימוש

await client.runTrigger((trigger: TriggerItem) => {
 // code to run for given trigger
})

getAfterHourMessage

הפונקציה מחזירה את הודעת ההפניה שהוגדרה להצגה כשהערוץ המבוקש לא פועל.

חתימת השיטה

חתימת ה-method היא:

getAfterHourMessage(lang?: string): Promise<string>

הערך המוחזר

מחזירה מחרוזת שמכילה הודעה שהוגדרה.

דוגמה לשימוש

try {
 const message: string = await client.getAfterHourMessage()
} catch (error) {
 // handle error
}