נקודות קצה של שיחות

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

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

אובייקט השיחה

דוגמה לאובייקט השיחה:

[
  {
    "id": 0,
    "parent_id": 0,
    "lang": "en",
    "call_type": "Voice Scheduled (API)",
    "status": "scheduled",
    "created_at": "2018-06-07T19:49:52.896Z",
    "queued_at": "2018-06-07T19:49:52.896Z",
    "assigned_at": "2018-06-07T19:49:52.896Z",
    "connected_at": "2018-06-07T19:49:52.896Z",
    "ends_at": "2018-06-07T19:49:52.896Z",
    "scheduled_at": "2018-06-07T19:49:52.896Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": 0,
    "has_feedback": true,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "string",
    "out_ticket_url": "string",
    "verified": true,
    "recording_url": "string",
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_details": "string",
    "fail_reason": "nothing",
    "support_number": "string",
    "selected_menu": {
      "id": 0,
      "name": "string",
      "parent_id": 0,
      "position": 0,
      "deleted": true,
      "hidden": "string",
      "menu_type": "ivr_menu",
      "output_msg": "string"
    },
    "menu_path": {
      "items_count": 0,
      "name": "string",
      "materialized_path": "string"
    },
    "agent_info": {
      "id": 0,
      "name": "string",
      "last_name": "string",
      "first_name": "string",
      "agent_number": "string",
      "avatar_url": "string"
    },
    "end_user": {
      "id": 0,
      "identifier": "string",
      "out_contact_id": "string"
    },
    "photos": [
      {
        "id": 0,
        "photo_type": "photo",
        "url": "string"
      }
    ],
    "videos": [
      {
        "id": 0,
        "url": "string"
      }
    ],
    "transfers": [
      {
        "id": 0,
        "status": "transferring",
        "fail_reason": "nothing",
        "created_at": "2018-06-07T19:49:52.896Z",
        "from_menu": {
          "items_count": 0,
          "name": "string",
          "materialized_path": "string"
        },
        "to_menu": {
          "items_count": 0,
          "name": "string",
          "materialized_path": "string"
        },
        "from_agent": {
          "id": 0,
          "name": "string",
          "last_name": "string",
          "first_name": "string",
          "agent_number": "string",
          "avatar_url": "string"
        },
        "to_agent": {
          "id": 0,
          "name": "string",
          "last_name": "string",
          "first_name": "string",
          "agent_number": "string",
          "avatar_url": "string"
        }
      }
    ],
    "participants": [
      {
        "id": 0,
        "type": "end_user",
        "status": "waiting",
        "call_id": 0,
        "user_id": 0,
        "end_user_id": 0,
        "call_duration": 0,
        "hold_duration": 0,
        "connected_at": "2018-06-07T19:49:52.896Z",
        "ended_at": "2018-06-07T19:49:52.896Z",
        "fail_reason": "nothing"
      }
    ]
  }
]

הגדרות הסטטוס של השיחות

שדה הסטטוס יכול להיות באחד מהמצבים הבאים:

סטטוס השיחה תיאור
בחירה מצב שמתרחש כשמשתמש קצה התקשר למוקד, אבל עדיין מנווט בין אפשרויות התפריט לפני שהוא מועבר לתפריט עלה.
מחכה בתור מצב שמתרחש אחרי שמשתמש הקצה בחר צומת תפריט עלה והפעיל בקשת שיחה שתועבר לנציג ב-deltcast או ב-multicast.
הקצאה מצב שמתרחש כשנציג נבחר לקבל את השיחה של משתמש הקצה. זה קורה כשנציג עונה לשיחה.
הדף מתחבר מצב שמתרחש אחרי שנציג מוקצה, ונוצר חיבור בין משתמש הקצה לנציג.
מחובר מצב שמתרחש כשהשיחה מתחברת והנציג ומשתמש הקצה נמצאים בשיחה.
סיימתי מצב שמתרחש כששיחה מסתיימת אחרי שהיא חוברה.
נכשל מצב שמתרחש כששיחה מסתיימת לפני שהיא חוברה בהצלחה. בנוסף, תופיע סיבת הכישלון עם פרטים נוספים.
מעבר מצב שמתרחש כששיחה נכשלת במהלך הניסיון להתחבר, ופלטפורמת CCAI מנסה לחבר את השיחה עם ספק VOIP אחר.
חולים שהחלימו מצב שמתרחש כשמתקשרים בחזרה לשיחה שנכשלה. השיחה החדשה הזו היא שיחת בת של השיחה המקורית. הערות משוחזרות שהקריאה החוזרת הסתיימה ללא שגיאה.
מתוזמנת מצב שמתרחש כשמשתמש קצה קובע שיחה עתידית דרך האתר או האפליקציה.
פעולה בלבד מצב שמתרחש כששיחה שמטופלת על ידי ספק הטלפוניה של הלקוח שלנו מחוברת ל-iOS SDK או ל-Android SDK שלנו.
הפעולה הסתיימה מצב שמתרחש כששיחה שמטופלת על ידי ספק הטלפוניה של הלקוח שלנו מחוברת ל-iOS או ל-Android SDK שלנו ומסתיימת
הדיפה מצב שמתרחש על סמך ההגדרות של תורים עם קיבולת יתר או שיחות מחוץ לשעות הפעילות. האפשרויות להסטת שיחות כוללות, בין היתר, דואר קולי ותזמון שיחה. ההסטה תשתנה בהתאם לערוץ (בתוך האפליקציה, IVR, באינטרנט)
דואר קולי מצב שמתרחש כשמשתמש קצה מופנה לאפשרות של דואר קולי, ובוחר להשאיר הודעה קולית כדי שיאזינו לה מאוחר יותר. המצב הזה מופיע כשמשתמש הקצה משאיר הודעה קולית
התקבל דואר קולי מצב שמתרחש אחרי שמשתמש קצה השאיר הודעה קולית ונציג לא הקשיב להודעה הקולית
קריאת הודעות קוליות מצב שמתרחש כשנציג פותח את ההודעה הקולית כדי להאזין לה.

הגדרות של סוגי שיחות

השדה call_type יכול להיות רק אחד מהערכים הבאים:

סוג השיחה תיאור
שיחות יוצאות (API) השיחה בוצעה באמצעות Outbound Call API.
שיחות נכנסות (API) השיחה בוצעה באמצעות Incoming Call API.
‫Voice Scheduled (API) השיחה בוצעה באמצעות Scheduled Call API.

קודי תגובה נפוצים מה-API

אלה התגובות הנפוצות ביותר מה-API:

קוד תגובה משמעות
201 בקשת ה-API בוצעה בהצלחה ותיצור שיחה
202 בקשת ה-API בוצעה בהצלחה, אבל נדרשת התערבות ידנית בתוך הווידג'ט כדי להשלים את הפעולה
400 סוג השיחה לא תקין – צריך לוודא ש-call_type נתמך
400 הנציג לא זמין לענות לשיחה הזו
400 פרמטר חסר – צריך לוודא שהפרמטרים הנדרשים נוספו
404 המשאב לא נמצא – צריך לבדוק את תת-הדומיין

שיחה יוצאת ללקוח – end_user_number

פרמטר חובה סוג הנתונים הגדרה
call_tye TRUE String כדי ליצור, צריך להתקשר ל-Tye. האפשרויות "Voice Outbound (API)" ו-"OutboundCall" (הוצאה משימוש) זמינות כרגע
agent_email TRUE String כתובת האימייל של הנציג שיוקצה לשיחה היוצאת ללקוח.
ticket_id לא נכון String מזהה הכרטיס ב-CRM, והמערכת תתקשר למשתמש הקצה שמשויך לכרטיס.
end_user_number לא נכון String מספר הטלפון של משתמש הקצה שיחייג. ל-ticket_id יש עדיפות גבוהה יותר מאשר ל-end_user_number.
outbound_number לא נכון String מספר שיחה יוצאת תקין שמנוהל דרך "הגדרות" > "מספרי טלפון" > "ניהול מספרי טלפון". אם השדה ריק, המערכת תשתמש במספר ברירת המחדל לשיחות יוצאות
lang לא נכון String השפה שבה מדברים בשיחה. צריך להשתמש בקודים לפי תקן ISO 639-1. (ברירת המחדל: "en")

נקודת קצה (endpoint):

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/calls

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}

דוגמה לבקשה ולתשובות

בקטעים הבאים מופיעות דוגמאות לבקשות לנקודת הקצה.

שגיאה : הסוכן לא זמין לשיחה הזו

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
תגובה: שגיאה : הסוכן לא זמין לקבלת השיחה הזו
{
    "message": "Agent is not available to take this call"
}

קוד סטטוס: 400

יצירת שיחה יוצאת ללקוח עם מספר של משתמש קצה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
תגובה: יצירת שיחה יוצאת ללקוח עם end_user_number
{
    "id": 397,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:27:30.406Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:27:30.441Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/avatar.jpg"
    },
    "end_user": null,
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 610,
            "type": "agent",
            "status": "waiting",
            "call_id": 397,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 611,
            "type": "end_user",
            "status": "waiting",
            "call_id": 397,
            "user_id": null,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

קוד סטטוס: 201

יצירת שיחה יוצאת ללקוח עם מזהה כרטיס תמיכה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
תגובה: יצירת שיחה יוצאת ללקוח עם ticket_id
{
    "id": 398,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:28:47.955Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:28:47.971Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "71450",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/avatar.png"
    },
    "end_user": {
        "id": 67,
        "identifier": null,
        "out_contact_id": "381630957514"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 612,
            "type": "agent",
            "status": "waiting",
            "call_id": 398,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 613,
            "type": "end_user",
            "status": "waiting",
            "call_id": 398,
            "user_id": null,
            "end_user_id": 67,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

קוד סטטוס: 201

שגיאה : צריך להזין מזהה כרטיס או מספר משתמש קצה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

תגובה: שגיאה : צריך לציין ticket_id או end_user_number

{
    "message": "ticket_id or end_user_number required"
}

קוד סטטוס: 400

שגיאה : כתובת האימייל של הנציג לא תקינה

הדוגמה הזו ממחישה את הכישלון כשכתובת האימייל שצוינה לנציג לא תקינה.

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

תגובה: שגיאה : כתובת האימייל של הנציג לא תקינה

{
    "message": "Not a valid agent email"
}

קוד סטטוס: 400

שגיאה : חובה להזין את כתובת האימייל של הסוכן

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

תגובה: שגיאה : חובה להזין את כתובת האימייל של הנציג

{
    "message": "Agent email required"
}

קוד סטטוס: 400

שגיאה : לסוכן אין גישה לביצוע שיחות

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
תגובה: שגיאה : לסוכן אין גישה לביצוע שיחות
{
    "message": "Agent does not have access to make calls"
}

קוד סטטוס: 400

שגיאה : הפורמט של end_user_number לא תקין

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
תגובה: שגיאה : הפורמט של end_user_number לא תקין
{
    "message": "end_user_number is not well-formed"
}

קוד סטטוס: 400

שגיאה : איש הקשר לא נמצא

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
תשובה: שגיאה : איש הקשר לא נמצא
{
    "message": "Contact not found"
}

קוד סטטוס: 400

אושר : צריך לבחור מספר לשיחות יוצאות

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}
תשובה
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

קוד סטטוס: 200

שגיאה : סוג שיחה לא תקין

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
תגובה: שגיאה : סוג שיחה לא תקין
{
    "message": "Invalid call type"
}

קוד סטטוס: 400

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

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}
תשובה
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

קוד סטטוס: 200

Accepted : Agent must make an outbound call with ticket ID

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

קוד סטטוס: 202

שיחה יוצאת ללקוח – ticket_id

פרמטר חובה סוג הנתונים הגדרה
call_type TRUE String סוג השיחה שרוצים ליצור. האפשרויות "Voice Outbound (API)" ו-"OutboundCall" (הוצאה משימוש) זמינות כרגע
agent_email TRUE String כתובת האימייל של הנציג שיוקצה לשיחה היוצאת ללקוח.
ticket_id לא נכון String מזהה הכרטיס ב-CRM, והמערכת תתקשר למשתמש הקצה שמשויך לכרטיס.
end_user_number לא נכון String מספר הטלפון של משתמש הקצה שיחייג. ל-ticket_id יש עדיפות גבוהה יותר מאשר ל-end_user_number.
outbound_number לא נכון String מספר שיחה יוצאת תקין שמנוהל דרך "הגדרות" > "מספרי טלפון" > "ניהול מספרי טלפון". אם השדה ריק, המערכת תשתמש במספר ברירת המחדל לשיחות יוצאות
lang לא נכון String השפה שבה מדברים בשיחה. צריך להשתמש בקודים לפי תקן ISO 639-1. (ברירת המחדל: "en")

נקודת קצה (endpoint):

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}​/apps/api/v1/calls

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "ticket_id": "123123",
    "lang": "en"
}

דוגמה לבקשה ולתשובות

בקטעים הבאים מופיעות דוגמאות לבקשות לנקודת הקצה.

שגיאה : צריך להזין מזהה כרטיס או מספר משתמש קצה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

תגובה: שגיאה : צריך לציין ticket_id או end_user_number

{
    "message": "ticket_id or end_user_number required"
}

קוד סטטוס: 400

שגיאה : חובה להזין את כתובת האימייל של הסוכן

בדוגמה הזו אנחנו מראים תרחיש של כשל שבו לא צוינה כתובת האימייל של הנציג, אבל היא נדרשת.

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
תגובה: שגיאה : חובה להזין את כתובת האימייל של הנציג
{
    "message": "Agent email required"
}

קוד סטטוס: 400

יצירת שיחה יוצאת ללקוח עם מספר של משתמש קצה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
תגובה: יצירת שיחה יוצאת ללקוח עם end_user_number
{
    "id": 397,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:27:30.406Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:27:30.441Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reaso": "not_voicemail",
    "deflection": "n_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/default-profile.png"
    },
    "end_user": null,
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 610,
            "type": "agent",
            "status": "waiting",
            "call_id": 397,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 611,
            "type": "end_user",
            "status": "waiting",
            "call_id": 397,
            "user_id": null,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

קוד סטטוס: 201

שגיאה : סוג שיחה לא תקין

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "ScheduledCall",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
תגובה: שגיאה : סוג שיחה לא תקין
{
    "message": "Invalid call type"
}

קוד סטטוס: 400

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

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

קוד סטטוס: 202

Accepted : Agent must make an outbound call with ticket ID

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json
***גוף:*** ```json { "call_type": "Voice Outbound (API)", "agent_email": "allen@somedomain.com", "end_user_number": "+1 205-123-4567", "lang": "en" } ``` ***קוד סטטוס:*** 202 #### שגיאה : לנציג אין גישה לביצוע שיחות בדוגמה הזו אנחנו מראים תרחיש של כשל שבו נשלחת בקשה ליצירת שיחה, אבל לנציג אין גישה לביצוע שיחות יוצאות. ##### בקשה ***כותרות:***
מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
תגובה: שגיאה : לסוכן אין גישה לביצוע שיחות
{
    "message": "Agent does not have access to make calls"
}

קוד סטטוס: 400

יצירת שיחה יוצאת ללקוח עם מזהה כרטיס תמיכה.

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
תגובה: יצירת שיחה יוצאת ללקוח עם ticket_id
{
    "id": 398,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:28:47.955Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:28:47.971Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "71450",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/default-profile.png"
    },
    "end_user": {
        "id": 67,
        "identifier": null,
        "out_contact_id": "381630957514"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 612,
            "type": "agent",
            "status": "waiting",
            "call_id": 398,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 613,
            "type": "end_user",
            "status": "waiting",
            "call_id": 398,
            "user_id": null,
            "end_user_id": 67,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

קוד סטטוס: 201

אושר : צריך לבחור מספר לשיחות יוצאות

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

קוד סטטוס: 202

שגיאה : הסוכן לא זמין לשיחה הזו

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
תגובה: שגיאה : הסוכן לא זמין לקבלת השיחה הזו
{
    "message": "Agent is not available to take this call"
}

קוד סטטוס: 400

שגיאה : מספר משתמש הקצה לא תקין

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
תגובה: שגיאה : הפורמט של end_user_number לא תקין
{
    "message": "end_user_number is not well-formed"
}

קוד סטטוס: 400

שגיאה : כתובת האימייל של הנציג לא תקינה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
תגובה: שגיאה : כתובת האימייל של הנציג לא תקינה
{
    "message": "Not a valid agent email"
}

קוד סטטוס: 400

שגיאה : איש הקשר לא נמצא

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
תשובה: שגיאה : איש הקשר לא נמצא
{
    "message": "Contact not found"
}

קוד סטטוס: 400

שיחה נכנסת

פרמטר חובה סוג הנתונים הגדרה
call_type TRUE String סוג השיחה שרוצים ליצור. כדי ליצור שיחה נכנסת, משתמשים ב-Voice Inbound (API)‎ או ב-IncomingCall (הוצא משימוש).
menu_id TRUE מספר שלם המזהה של התפריט שאליו רוצים לשייך את השיחה. אפשר להזין רק מזהים של תפריטי IVR ותפריטי אינטרנט.
end_user_number TRUE String מספר הטלפון של משתמש הקצה שאליו תתבצע השיחה. אם מעבירים גם ticket_id וגם end_user_number, המערכת תתעדף את ticket_id.
lang לא נכון String השפה שבה מדברים בשיחה. צריך להשתמש בקודים לפי תקן ISO 639-1. (ברירת המחדל: "en")
ticket_id לא נכון String מזהה כרטיס המידע ב-CRM. המערכת תחייג למספר הטלפון של משתמש הקצה שמשויך לכרטיס המידע. אם מעבירים גם ticket_id וגם end_user_number, המערכת תתעדף את ticket_id.
outbound_number לא נכון String מספר הטלפון לשיחות יוצאות שבו רוצים להשתמש. אם לא תזינו מספר טלפון או שתזינו מספר לא תקין, המערכת תשתמש במספר ברירת המחדל הגלובלי לשיחות יוצאות. כדי לנהל את המספרים לשיחות יוצאות, עוברים אל "הגדרות" > "תור" > "עריכה / הצגה" > בוחרים תור > "מספרי טלפון לשיחות יוצאות".
recording_permission לא נכון String הערך נבדק רק אם התכונה "אפשרויות הקלטת שיחות" מוגדרת ל "בקשת הרשאה מהמשתמש להקלטה". אפשר להגדיר את זה ב"הגדרות" > "תור" > "עריכה / צפייה" > בחירת תור > "אפשרויות הקלטת שיחות". אם הערך הוא recording_permission_not_asked (ברירת המחדל) או recording_permission_denied, השיחה לא תוקלט. אם הערך הוא "recording_permission_granted", השיחה תוקלט.

נקודת קצה (endpoint):

Method: POST
Type: RAW
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/calls

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}

דוגמה לבקשה ולתשובות

בקטעים הבאים מופיעות דוגמאות לבקשות לנקודת הקצה.

שגיאה : מספר משתמש הקצה לא תקין

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : end_user_number לא תקין
{
    "message": "end_user_number is not well formed"
}

קוד סטטוס: 400

שגיאה : התפריט במצב "הפניה ידנית", אי אפשר לקבל שיחות

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : התפריט נמצא במצב "הפניה ידנית", אי אפשר לקבל שיחות
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

קוד סטטוס: 400

שגיאה : סוג שיחה לא תקין

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : סוג שיחה לא תקין
{
    "message": "Invalid call type"
}

קוד סטטוס: 400

שגיאה : חובה להזין מזהה תפריט

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : חובה לציין menu_id
{
    "message": "menu_id is required"
}

קוד סטטוס: 400

שגיאה : מותר להשתמש רק במזהים של IVR ושל תפריט לנייד

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : מותר להשתמש רק במזהים של IVR ושל תפריט לנייד
{
    "message": "Only IVR and mobile menu IDs are permitted"
}

קוד סטטוס: 400

יצירת שיחה נכנסת עם מספר של משתמש קצה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "recording_permission": "recording_permission_granted"
}
תגובה: יצירת שיחה נכנסת עם end_user_number
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": "2019-09-10T00:19:14.421Z",
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

קוד סטטוס: 201

שגיאה : התפריט במצב "אחרי שעות הפעילות", אי אפשר לקבל שיחות נכנסות

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : התפריט במצב "אחרי שעות הפעילות", אי אפשר לקבל שיחות נכנסות
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

קוד סטטוס: 400

שגיאה : השפה לא זמינה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תשובה: שגיאה : השפה לא זמינה
{
    "message": "Language 'fr' is not available"
}

קוד סטטוס: 400

יצירת שיחה נכנסת עם מזהה כרטיס תמיכה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תגובה: יצירת שיחה נכנסת עם ticket_id
{
    "id": 519,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T05:12:26.000Z",
    "queued_at": "2019-09-10T05:12:26.295Z",
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": "76517",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 826,
            "type": "end_user",
            "status": "waiting",
            "call_id": 519,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T05:12:26.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

קוד סטטוס: 201

שגיאה : השפה לא נמצאה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : השפה לא נמצאה
{
    "message": "Language 'xy' is not found"
}

קוד סטטוס: 400

שגיאה : menu_id לא נמצא

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : menu_id לא נמצא
{
    "message": "menu_id 9999 is not found"
}

קוד סטטוס: 400

שגיאה : menu_id לא תקין

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : menu_id לא תקין
{
    "message": "menu_id is not well formed"
}

קוד סטטוס: 400

שגיאה : חובה להזין את מספר משתמש הקצה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : חובה להזין את end_user_number
{
    "message": "end_user_number is required"
}

קוד סטטוס: 400

שיחה מתוזמנת

פרמטר חובה סוג הנתונים הגדרה
call_type TRUE String סוג השיחה שרוצים ליצור. כדי ליצור שיחה מתוזמנת, משתמשים ב-Voice Scheduled (API)‎ או ב-ScheduledCall (הוצא משימוש).
menu_id TRUE מספר שלם המזהה של התפריט שאליו רוצים לשייך את השיחה. אפשר להזין רק מזהי תפריטים לנייד ולאינטרנט.
call_id לא נכון מספר שלם מזהה השיחה של השיחה הקודמת, שתקושר כשיחת ההורה של השיחה המתוזמנת החדשה שנוצרה. כשמשתמשים במזהה השיחה, הפרמטר menu_id הוא אופציונלי.
end_user_number TRUE String מספר הטלפון של משתמש הקצה שאליו תתבצע השיחה. אם מעבירים גם ticket_id וגם end_user_number, המערכת תתעדף את ticket_id.
lang לא נכון String השפה שבה מדברים בשיחה. צריך להשתמש בקודים לפי תקן ISO 639-1. (ברירת המחדל: "en")
ticket_id לא נכון String מזהה כרטיס המידע ב-CRM. המערכת תחייג למספר הטלפון של משתמש הקצה שמשויך לכרטיס המידע. אם מעבירים גם ticket_id וגם end_user_number, המערכת תתעדף את ticket_id.
scheduled_at TRUE String השעה שנקבעה לשיחה. צריך להשתמש בפורמט ISO 8601 ולציין זמן תקין בעתיד.
recording_permission לא נכון String הערך נבדק רק אם התכונה "אפשרויות הקלטת שיחות" מוגדרת ל "בקשת הרשאה מהמשתמש להקלטה". אפשר להגדיר את זה ב"הגדרות" > "תור" > "עריכה / צפייה" > בחירת תור > "אפשרויות הקלטת שיחות". אם הערך הוא recording_permission_not_asked (ברירת המחדל) או recording_permission_denied, השיחה לא תוקלט. אם הערך הוא "recording_permission_granted", השיחה תוקלט.

נקודת קצה (endpoint):

Method: POST
Type: RAW
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/calls

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}

דוגמה לבקשה ולתשובות

בקטעים הבאים מופיעות דוגמאות לבקשות לנקודת הקצה.

שגיאה : end_user_number לא תקין

בדוגמה הזו, הבקשה נכשלת כי הפורמט של end_user_namber שגוי.

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : end_user_number לא תקין
{
    "message": "end_user_number is not well formed"
}

קוד סטטוס: 400

שגיאה : התפריט במצב "הפניה ידנית", אי אפשר לקבל שיחות

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : התפריט נמצא במצב "הפניה ידנית", אי אפשר לקבל שיחות
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

קוד סטטוס: 400

שגיאה : סוג שיחה לא תקין

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : סוג שיחה לא תקין
{
    "message": "Invalid call type"
}

קוד סטטוס: 400

שגיאה : חובה לציין menu_id

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : חובה לציין menu_id
{
    "message": "menu_id is required"
}

קוד סטטוס: 400

שגיאה : מותר להשתמש רק במזהי תפריטים לנייד ולאינטרנט

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : מותר להשתמש רק במזהי תפריטים לנייד ולאינטרנט
{
    "message": "Only mobile and web menu IDs are permitted"
}

קוד סטטוס: 400

יצירת שיחה מתוזמנת עם מזהה תפריט

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: יצירת שיחה מתוזמנת עם מזהה תפריט
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": null,
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

קוד סטטוס: 201

איך יוצרים שיחה מתוזמנת עם מזהה שיחה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "call_id": 514,
    "end_user_number": "+82-10-6861-2345",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: יצירת שיחה מתוזמנת עם מזהה שיחה
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": null,
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

קוד סטטוס: 201

שגיאה : התפריט במצב "אחרי שעות הפעילות", אי אפשר לקבל שיחות נכנסות

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : התפריט במצב "אחרי שעות הפעילות", אי אפשר לקבל שיחות נכנסות
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

קוד סטטוס: 400

שגיאה : השפה לא זמינה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תשובה: שגיאה : השפה לא זמינה
{
    "message": "Language 'fr' is not available"
}

קוד סטטוס: 400

שגיאה : השפה לא נמצאה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : השפה לא נמצאה
{
    "message": "Language 'xy' is not found"
}

קוד סטטוס: 400

שגיאה : מזהה התפריט לא נמצא

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : מזהה התפריט לא נמצא
{
    "message": "menu_id 9999 is not found"
}

קוד סטטוס: 400

שגיאה : מזהה התפריט לא תקין

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : menu_id לא תקין
{
    "message": "menu_id is not well formed"
}

קוד סטטוס: 400

שגיאה : חובה להזין את מספר משתמש הקצה

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

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : חובה להזין את end_user_number
{
    "message": "end_user_number is required"
}

קוד סטטוס: 400

שגיאה : חובה להזין את scheduled_at

בדוגמה הזו אנחנו מראים תרחיש של כשל שבו נוצרת שיחה מתוזמנת, אבל הערך של scheduled_at חסר למרות שהוא נדרש.

בקשה

כותרות:

מפתח ערך תיאור
סוג התוכן application/json

גוף ההודעה:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
תגובה: שגיאה : חובה להזין את scheduled_at
{
    "message": "scheduled_at is required"
}

קוד סטטוס: 400

קבלת מאפייני נתונים שמורים במהלך שיחה

נקודת קצה (endpoint)

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag

דוגמה לבקשה ולתשובות

בקטע הזה יש דוגמה לבקשה ולתגובה של נקודת הקצה.

הפעולה הצליחה

בדוגמה הזו מוצגת קריאה מוצלחת.

בקשה

משתנים של כתובות URL

מפתח ערך תיאור
id מספר שלם (חובה)
תשובה
{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

קוד סטטוס 0

עדכון מאפייני נתונים שמורים במהלך שיחה

נקודת קצה (endpoint)

Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag

משתנים של כתובות URL

מפתח ערך תיאור
id מספר שלם (חובה)

גוף ההודעה

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customers": "boolean"
}

העברת פרמטרים של נתונים לנציגים וירטואליים באמצע הסשן

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