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

בדף הזה מפורטים רכיבי ה-method של ממשק ה-API שזמינים ב-SDK של headless web.

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

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

getTrigger

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

const trigger = await client.getTrigger()

getCompany

השיטה הזו מאחזרת את פרטי החברה.

חתימת שיטה

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;
  cobrowse_domain?: string;
}

דוגמה לשימוש

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

getMenus

השיטה הזו מפרטת את כל פריטי התפריט שזמינים לדייר.

חתימת שיטה

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

הערך המוחזר

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

ממשקים

interface MenuResponse {
  menus: MenuItem[];
  direct: {
    key: boolean;
    user: boolean;
  };
}

interface MenuItem {
  id: number;
  name?: string;
  enabled: boolean;
  redirection?: {
    option: string;
    data: string;
  };
  children?: MenuItem[];
  channels: MenuChannel[];
  deflection?: {
    enabled: boolean;
    type: string;
  };
}

דוגמה לשימוש

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>

הערך המוחזר

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

ממשקים

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

דוגמה לשימוש

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

שיחות

שיטות לטיפול בשיחות מתוזמנות דרך ה-SDK.

createCall

השיטה הזו יוצרת שיחה מיידית או שיחה מתוזמנת.

חתימת שיטה

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;
  use_advanced_call_scheduling?: boolean;
}

דוגמה לשימוש

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

loadCall

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

Method Signature

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

אחזור של משבצות זמן פנויות לשיחות מתוזמנות בתפריט נתון.

כשקוראים ל-method עם אובייקט אפשרויות GetTimeSlotsRequest, היא תומכת באפשרויות הבאות:

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

חתימת שיטה

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

הערך המוחזר

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

ממשקים

interface GetTimeSlotsRequest {
  lang?: string;
  rescheduleCallId?: number;          // ID of an existing call being rescheduled
  useAdvancedCallScheduling?: boolean; // Enable advanced call scheduling behavior
}

דוגמה לשימוש

// New options-based signature (recommended)
try {
  const slots = await client.getTimeSlots(123, {
    lang: 'en',
    useAdvancedCallScheduling: true,
  })
} catch (error) {
  // handle error
}

// Deprecated signature (still supported)
try {
  const slots = await client.getTimeSlots(123, 'en')
} catch (error) {
  // handle error
}

fetchTimeSlotAvailability

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

חתימת שיטה

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
}

צ'אטים

שיטות לטיפול בצ'אטים באמצעות ה-SDK.

createChat

השיטה הזו יוצרת צ'אט חדש.

Method Signature

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 = client.createChat(123, { lang: 'en' })
} catch (error) {
  // handle error
}

loadChat

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

חתימת שיטה

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

הערך המוחזר

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

דוגמה לשימוש

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

loadOngoingChat

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

Method Signature

loadOngoingChat(): Promise<Chat | null>

ערך מוחזר

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

דוגמה לשימוש

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

resumeChat

השיטה הזו מפעילה מחדש שיחה שנסגרה.

חתימת שיטה

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

הערך המוחזר

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

דוגמה לשימוש

client.resumeChat(1234)

finishChat

השיטה הזו משנה את סטטוס הצ'אט לfinished.

חתימת שיטה

finishChat(): Promise<void>

דוגמה לשימוש

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

destroyChat

השיטה הזו משמידה את הצ'אט הנוכחי.

חתימת שיטה

destroyChat(): Promise<void>

דוגמה לשימוש

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

fetchMessages

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

חתימת שיטה

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: string;
  };
  signature: string;
  form?: {
    id: number;
    form_type: string;
    name: string;
    title: string;
    subtitle: string;
    external_form_id: string;
    smart_action_id: number;
    image: string;
  };
}

דוגמה לשימוש

const messages = client.fetchMessages()

sendTextMessage

השיטה הזו שולחת הודעת טקסט.

חתימת שיטה

sendTextMessage(rawContent: string): Promise<void>

דוגמה לשימוש

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

sendFileMessage

בשיטה הזו נשלחת הודעה עם קובץ.

חתימת שיטה

sendFileMessage(file: File): Promise<number>

הערך המוחזר

מחזירה את מזהה ההודעה או -1 אם הפעולה נכשלה.

דוגמה לשימוש

const input = document.querySelector('input[type="file"]')
const file = input.files[0]
const id = client.sendFileMessage(file)

sendPreviewMessage

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

חתימת שיטה

sendPreviewMessage(content: string): Promise<void>

דוגמה לשימוש

client.chat.startTyping();
clearTimeout(stopTimer);
stopTimer = setTimeout(() => {
    if (client.chat) {
        client.chat.stopTyping();
    }
}, 5000);

clearTimeout(previewTimer);
const currentTime = Date.now();

if (currentTime - lastPreviewTime >= 2000) {
    lastPreviewTime = currentTime;
    try {
        const response = await client.sendPreviewMessage("chat message");
    } catch (error) {
        console.error("Error sending preview message:", error);
    }
} else {
    previewTimer = setTimeout(async () => {
        lastPreviewTime = Date.now();
        try {
            const response = await client.sendPreviewMessage("chat message");
        } catch (error) {
            console.error("Error sending debounced preview message:", error);
        }
    }, 1000);
}

startTyping

חתימת שיטה

startTyping()

דוגמה לשימוש

try {
  client.startTyping()
} catch (error) {
  // handle error
}

stopTyping

חתימת שיטה

stopTyping()

דוגמה לשימוש

try {
  client.stopTyping()
} catch (error) {
  // handle error
}

getChatDeflection

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

חתימת שיטה

getChatDeflection(): Promise<ChatDeflectionResponse>

הערך המוחזר

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

ממשקים

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 {
  client.sendChatTranscripts([
    "name1@example.com",
    "name2@example.com",
  ])
} catch (error) {
  // handle error
}

downloadChatTranscript

חתימת שיטה

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

הערך המוחזר

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

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

דוגמה לשימוש

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

getPdfStatus

חתימת שיטה

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 = resp.headers['x-transcript-status'];

// otherwise use status on data
const data: PdfStatusResponse = resp.data
console.log(data.status)

getChatSurvey

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

חתימת שיטה

getChatSurvey(): Promise<ChatSurveyResponse>

הערך המוחזר

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

ממשקים

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()
  console.log(data.questions)
} catch (error) {
  // handle error
}

sendChatSurvey

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

חתימת שיטה

sendChatSurvey(answers: SurveyAnswers): 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 {
  reason?: string;
  // ...other escalation fields
}

דוגמה לשימוש

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

חתימת שיטה

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

ערך מוחזר

ההחזרות בטלות.

ממשקים

interface ChatEndUserEventRequest {
  end_user_name?: string;
  // ...other event fields
}

דוגמה לשימוש

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

getChatHistory

חתימת שיטה

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

הערך המוחזר

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

ממשקים

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 = client.getChatHistory(page: number)
  console.log(data)
} catch (error) {
  console.log(error)
}

אימיילים

שיטות לטיפול באימיילים לתמיכה.

createEmails

חתימת שיטה

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

Method Signature

getProhibitedFileTypes(): Promise<FileTypeItem[]>

הערך המוחזר

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

ממשקים

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

דוגמה לשימוש

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

שיתוף מסך

שיטות לטיפול ביכולת שיתוף המסך.

createCobrowseCode

השיטה הזו יוצרת קוד לשיתוף מסך.

חתימת שיטה

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()

getMessageAttachment

חתימת שיטה

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

הערך המוחזר

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

דוגמה לשימוש

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

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

שיטות לטיפול בנציגים וירטואליים אחרי סשן.

updatePostSession

עדכון הסטטוס של הנציג הווירטואלי אחרי סיום הסשן בצ'אט הפעיל. אפשר להשתמש בזה כדי לציין מוכנות, התקדמות או סיום של תהליך נציג וירטואלי אחרי סיום הסשן. השיטה הזו מחזירה מיד כפעולה לא פעילה אם postSessionStatus הוא FINISHED או WAITING, כי המעברים האלה מטופלים באופן פנימי. ל-method הזו יש לוגיקה פנימית לניסיון חוזר, שרלוונטית במיוחד לסטטוס 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.

ניפוי באגים

שיטות לניפוי באגים ב-SDK.

getLogs

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

חתימת שיטה

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

הערך המוחזר

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

ממשקים

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

דוגמה לשימוש

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

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

חתימת שיטה

printLogs(): Promise<void>

דוגמה לשימוש

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

שונות

שיטות SDK שונות.

runTrigger

חתימת שיטה

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

דוגמה לשימוש

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

getAfterHourMessage

חתימת שיטה

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

הערך המוחזר

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

דוגמה לשימוש

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