Help Center הודעות שיחת דיבור

הודעות שיחת דיבור

SpeechCall הוא סוג של תגובה קולית אינטראקטיבית (IVR) המאפשרת לך לבצע שיחות קוליות אוטומטיות עם אפשרויות תפריט ואינטראקציות DTMF (Dual-Tone Multi-frequency).

סקירה כללית

SpeechCall מאפשרת לעסקים:

  • בצע שיחות קוליות אוטומטיות ללקוחות
  • השמעת הודעות שמע מבוא
  • הצג אפשרויות תפריט אינטראקטיביות
  • טיפול בתגובות DTMF של לחיצת מקש (0-9, *, #)
  • הגדר התנהגות מותאמת אישית עבור כניסות לא חוקיות/פסק זמן
  • הפעל webhooks עם גופים וכותרות מותאמות אישית על סמך בחירת המשתמש
  • נהל את זרימת השיחות באופן דינמי (נווט בין תפריטים)

מקרי שימוש

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

פורמט בקשה

מבנה בסיסי

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_XXXXX",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                },
                "headers": {
                  "test-header": "test"
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "gotoMenu",
                "menu": "1"
              }
            ]
          }
        }
      ]
    }
  ]
}

תיאור פרמטר

פרמטרהקלדחובהתיאור
ממחרוזתכןמזהה השולח (שם אלפא או מזהה)
אלמחרוזתכןמספר טלפון של הנמען בפורמט בינלאומי
טקסטמחרוזתכןערך טקסט, בדרך כלל “ivr” עבור SpeechCall
סוגמחרוזתכןחייב להיות "שיחת דיבור"
תפריטמערךכןמערך תצורות תפריט לשיחה

תצורת תפריט

כל אובייקט תפריט מכיל:

פרמטרהקלדחובהתיאור
introUrlמחרוזתכןכתובת אתר או מזהה של קובץ האודיו המבוא
idleTimeoutMsecמספר שלםלאפסק זמן באלפיות שניות להמתנה ללחיצת מקש (לדוגמה, 10000). אם המשתמש לא יגיב, הפעולות שהוגדרו תחת המקש ‘שגוי’ יבוצעו
dtmfActionsחפץכןמפה של מפתחות DTMF לפעולות

פעולות DTMF

האובייקט dtmfActions ממפה מפתחות DTMF או תנאים מיוחדים למערכים של פעולות:

מפתח DTMFתיאור
d0הקש 0
d1הקש 1
d2הקש 2
……
d9הקש 9
d*הקש *
d#הקש #
לא נכוןמופעל כאשר מקש לא חוקי נלחץ או כאשר ‘idleTimeoutMsec’ מושג ללא כל קלט

כל מפתח/תנאי DTMF ממפה למערך של פעולות שיבוצעו ברצף.

פעולות נתמכות

| פעולה | פרמטרים | תיאור | |--------|---------------------------| | webhook | כתובת אתר (מחרוזת, חובה)
גוף (אובייקט, אופציונלי)
כותרות (אובייקט, אופציונלי) | שולח בקשת HTTP POST בפורמט JSON לכתובת ה-URL שצוינה. האובייקט ‘גוף’ יקנן מתחת לשדה ‘פעולה’ בבקשת ה-webhook. כותרות מותאמות אישית נכללות ככותרות HTTP. | | ניתוק | אין | מסיים את השיחה | | gotoMenu | תפריט (מחרוזת או מספר שלם) | מנווט את השיחה לתפריט אחר במערך תפריט באמצעות האינדקס המבוסס על 0 (לדוגמה, "1") |

התנהגות פעולה מפורטת

Webhook Action (webhook)

פעולת ה-webhook שולחת בקשת HTTP POST לכתובת האתר שלך להתקשרות חוזרת עם מטא נתונים של השיחה ונתונים מותאמים אישית אופציונליים:

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

פעולת ניתוק (ניתוק)

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

עבור אל פעולת תפריט (gotoMenu)

פעולת gotoMenu מפנה את זרימת השיחה למבנה תפריט אחר בתוך מערך התפריט. נדרש פרמטר אחד תפריט אשר מציין את האינדקס המבוסס על 0 של תפריט היעד (למשל, "1" כדי לעבור לתפריט השני, או "0" כדי להפעיל מחדש את התפריט הראשון).

חוסר פעילות וטיפול בשגיאות (שגוי)

המפתח ה’שגוי’ בתוך ‘dtmfActions’ הוא מטפל מיוחד של נפילה. הוא מבצע את רצף הפעולות שלו בשני תרחישים:

  1. קלט לא חוקי: המתקשר לוחץ על מקש DTMF שאינו מוגדר ב-dtmfActions (לדוגמה, הם לוחצים על 3 אך התפריט מגדיר רק d1 ו-d2).
  2. פסקת זמן סרק: המתקשר לא לוחץ על מקש כלשהו במהלך שנקבע על ידי idleTimeoutMsec.

אם ‘לא נכון’ לא מוגדר והמתקשר לוחץ על מקש לא חוקי או פסק זמן, זרימת השיחה תנתק כברירת מחדל. הגדרת ‘לא נכון’ מאפשרת לך לבנות תפריטי לולאה (למשל לחזור לאותו תפריט עם `“פעולה”: “גוטו תפריט”, “תפריט”: “0”) או הפניית המשתמש לתפריט עזרה.

פורמט מסירה של Webhook

כאשר פעולת ה-webhook מופעלת, המערכת שולחת בקשת HTTP POST אל ה-URL המוגדר עם ‘Content-Type: application/json’.

כותרות בקשת Webhook

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

גוף בקשת Webhook

למטען ה-JSON שנשלח לכתובת ה-webhook שלך יש את המבנה הבא:

{
  "from": "0443914272",
  "to": "50001",
  "mid": "7748021",
  "action": {
    "confirm": true
  }
}
שדההקלדתיאור
ממחרוזתמספר טלפון של המתקשר / מזהה השולח
אלמחרוזתמספר טלפון של הנמען
אמצעמחרוזתמזהה הודעה
פעולהחפץאובייקט JSON המותאם אישית שהוגדר בשדה ‘גוף’ של הפעולה

דוגמה מלאה

IVR פשוט עם פסק זמן ואימות קלט

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "hangup"
              }
            ]
          }
        }
      ]
    }
  ]
}

IVR מורכב עם תפריטים מרובים וניתוב DTMF

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

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_XXXXX",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                },
                "headers": {
                  "test-header": "test"
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "gotoMenu",
                "menu": "1"
              }
            ]
          }
        },
        {
          "introUrl": "ivr_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "hangup"
              }
            ]
          }
        }
      ]
    }
  ]
}

פורמט תגובה

תגובת הצלחה

{
  "messages": [
    {
      "messageId": "unique-message-id",
      "recipient": "+380XXXXXXXXX",
      "status": "sent"
    }
  ]
}

טיפול בשגיאות

מצב HTTPתיאור
200הבקשה הצליחה
400פורמט בקשה לא חוקי
401האימות נכשל
429חריגה ממגבלת התעריף
500שגיאת שרת פנימית

דוגמה של curl

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "from": "YourSender",
        "to": "+380XXXXXXXXX",
        "text": "ivr",
        "type": "speechcall",
        "menu": [
          {
            "introUrl": "ivr_XXXXX",
            "idleTimeoutMsec": 10000,
            "dtmfActions": {
              "d1": [
                {
                  "action": "webhook",
                  "url": "https://YourWebhookURL/0",
                  "body": {
                    "confirm": true
                  },
                  "headers": {
                    "test-header": "test"
                  }
                },
                {
                  "action": "hangup"
                }
              ],
              "d2": [
                {
                  "action": "webhook",
                  "url": "https://YourWebhookURL/1",
                  "body": {
                    "confirm": false
                  }
                },
                {
                  "action": "hangup"
                }
              ],
              "wrong": [
                {
                  "action": "gotoMenu",
                  "menu": "1"
                }
              ]
            }
          },
          {
            "introUrl": "ivr_651854",
            "idleTimeoutMsec": 10000,
            "dtmfActions": {
              "d1": [
                {
                  "action": "webhook",
                  "url": "https://YourWebhookURL/0",
                  "body": {
                    "confirm": true
                  }
                },
                {
                  "action": "hangup"
                }
              ],
              "d2": [
                {
                  "action": "webhook",
                  "url": "https://YourWebhookURL/1",
                  "body": {
                    "confirm": false
                  }
                },
                {
                  "action": "hangup"
                }
              ],
              "wrong": [
                {
                  "action": "hangup"
                }
              ]
            }
          }
        ]
      }
    ]
  }'

שיטות עבודה מומלצות

  1. קובצי אודיו - ודא שכתובות האתרים היכרויות נגישות וקובצי אודיו בפורמטים נתמכים
  2. מהימנות Webhook - עיצוב Webhook שיגיב במהירות (בתוך 2 שניות)
  3. אפשרויות DTMF - הגבל את אפשרויות התפריט ל-4-6 אפשרויות לחוויית משתמש טובה יותר
  4. טיפול בפסק זמן - השתמש ב-‘idleTimeoutMsec’ כדי לציין מגבלות מותאמות אישית של חוסר פעילות (לדוגמה, 10000 אלפיות השנייה), והגדר סתירה חיננית תחת מקש DTMF ‘שגוי’ (כמו חזרה על התפריט או ניתוק)
  5. זרימת שיחה מרובה תפריטים - השתמש בזהירות ב-‘gotoMenu’ כדי למנוע לולאות אינסופיות בעת ניתוב משתמשים חזרה לתפריטים קודמים
  6. אסטרטגיית חילוץ - השתמשו בהודעות חילוף למשתמשים שאינם עונים או מתנתקים

נושאים קשורים