Help Center Μηνύματα ομιλίας

Μηνύματα ομιλίας

Το SpeechCall είναι ένας τύπος μηνύματος διαδραστικής φωνητικής απόκρισης (IVR) που σας επιτρέπει να πραγματοποιείτε αυτοματοποιημένες φωνητικές κλήσεις με επιλογές μενού και αλληλεπιδράσεις DTMF (διπλής συχνότητας πολλαπλών συχνοτήτων).

Επισκόπηση

Το SpeechCall επιτρέπει στις επιχειρήσεις να:

  • Πραγματοποιήστε αυτοματοποιημένες φωνητικές κλήσεις σε πελάτες
  • Αναπαραγωγή εισαγωγικών ηχητικών μηνυμάτων
  • Παρουσίαση διαδραστικών επιλογών μενού
  • Χειριστείτε τις απαντήσεις πατήματος DTMF (0-9, *, #)
  • Καθορίστε προσαρμοσμένη συμπεριφορά για μη έγκυρες εισόδους/χρονικό όριο
  • Ενεργοποίηση 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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Περιγραφή παραμέτρου

ΠαράμετροςΤύποςΑπαιτείταιΠεριγραφή
«από»χορδήΝαιΑναγνωριστικό αποστολέα (άλφα όνομα ή αναγνωριστικό)
«προς»χορδήΝαιΑριθμός τηλεφώνου παραλήπτη σε διεθνή μορφή
”κείμενο”χορδήΝαιΤιμή κειμένου, συνήθως “ivr” για SpeechCall
«τύπος»χορδήΝαιΠρέπει να είναι ""speechcall""
«μενού»συστοιχίαΝαιΣειρά διαμορφώσεων μενού για την κλήση

Διαμόρφωση μενού

Κάθε αντικείμενο μενού περιέχει:

ΠαράμετροςΤύποςΑπαιτείταιΠεριγραφή
introUrlχορδήΝαιURL ή αναγνωριστικό του εισαγωγικού αρχείου ήχου
idleTimeoutMsecακέραιοςΌχιΛήξη χρονικού ορίου σε χιλιοστά του δευτερολέπτου για να περιμένετε ένα πάτημα πλήκτρων (π.χ. 10000). Εάν ο χρήστης δεν ανταποκριθεί, οι ενέργειες που έχουν ρυθμιστεί κάτω από το κλειδί “λάθος” θα εκτελεστούν
dtmfActionsαντικείμενοΝαιΧάρτης των κλειδιών DTMF για ενέργειες

Ενέργειες DTMF

Το αντικείμενο dtmfActions αντιστοιχίζει κλειδιά DTMF ή ειδικές συνθήκες σε πίνακες ενεργειών:

Κλειδί DTMFΠεριγραφή
d0Πατήστε 0
d1Πατήστε 1
d2Πατήστε 2
……
d9Πατήστε 9
d*Πατήστε *
d#Πατήστε #
“λάθος”Ενεργοποιείται όταν πατιέται ένα μη έγκυρο πλήκτρο ή όταν επιτυγχάνεται «idleTimeoutMsec» χωρίς καμία εισαγωγή

Κάθε κλειδί/συνθήκη DTMF αντιστοιχίζεται σε μια σειρά ενεργειών που θα εκτελεστούν με τη σειρά.

Υποστηριζόμενες ενέργειες

ΔράσηΠαράμετροιΠεριγραφή
webhookurl (συμβολοσειρά, απαιτείται)
body (αντικείμενο, προαιρετικό)
κεφαλίδες (αντικείμενο, προαιρετικό)		Στέλνει ένα αίτημα HTTP POST σε μορφή JSON στην καθορισμένη διεύθυνση URL. Το αντικείμενο “body” θα είναι ένθετο κάτω από το πεδίο “action” στο αίτημα webhook. Οι προσαρμοσμένες κεφαλίδες περιλαμβάνονται ως κεφαλίδες HTTP.
hangupΚανέναΤερματίζει την κλήση
gotoMenuμενού (συμβολοσειρά ή ακέραιος αριθμός)Πλοηγεί την κλήση σε άλλο μενού στον πίνακα “μενού” χρησιμοποιώντας το ευρετήριό του που βασίζεται στο 0 (π.χ. “1”)

Λεπτομερής συμπεριφορά δράσης

Ενέργεια Webhook (‘webhook’)

Η ενέργεια “webhook” στέλνει ένα αίτημα HTTP POST στη διεύθυνση URL επιστροφής κλήσης με τα μεταδεδομένα κλήσης και προαιρετικά προσαρμοσμένα δεδομένα:

  • Εάν παρέχεται ένα «σώμα», τα ζεύγη κλειδιού-τιμής του αποστέλλονται μέσα στο πεδίο «ενέργεια» του σώματος ωφέλιμου φορτίου.
  • Εάν παρέχονται “κεφαλίδες”, αποστέλλονται ως προσαρμοσμένες κεφαλίδες HTTP στο αίτημα.

Ενέργεια Hangup (“hangup”)

Η ενέργεια «κλείσιμο» τερματίζει την ενεργή κλήση αμέσως. Καμία περαιτέρω ενέργεια στην ακολουθία ή στα μενού δεν θα υποβληθεί σε επεξεργασία μετά από μια ενέργεια “παύσης”.

Μετάβαση στο μενού Ενέργεια (“gotoMenu”)

Η ενέργεια «gotoMenu» ανακατευθύνει τη ροή της κλήσης σε μια διαφορετική δομή μενού εντός του πίνακα «μενού». Χρειάζεται μία μόνο παράμετρος μενού που καθορίζει το ευρετήριο με βάση το 0 του μενού προορισμού (π.χ. "1" για να μεταβείτε στο δεύτερο μενού ή “0” για επανεκκίνηση του πρώτου μενού).

Αδράνεια και χειρισμός σφαλμάτων («λάθος»)

Το “λάθος” κλειδί μέσα στο “dtmfActions” είναι ένας ειδικός χειριστής πτώσης. Εκτελεί τη σειρά ενεργειών του σε δύο σενάρια:

  1. Μη έγκυρη είσοδος: Ο καλών πατά ένα πλήκτρο DTMF που δεν ορίζεται στο dtmfActions (για παράδειγμα, πατάει το 3 αλλά το μενού ορίζει μόνο τα d1 και d2).
  2. Idle Timeout: Ο καλών δεν πατάει κανένα πλήκτρο εντός της διάρκειας που καθορίζεται από το idleTimeoutMsec.

Εάν δεν έχει οριστεί το “λάθος” και ο καλών πατήσει ένα μη έγκυρο πλήκτρο ή λήξει το χρονικό όριο, η ροή κλήσης θα τερματιστεί από προεπιλογή. Ο ορισμός του “λάθος” σάς επιτρέπει να δημιουργήσετε μενού βρόχου (π.χ. να επιστρέψετε στο ίδιο μενού με ""ενέργεια”: “gotoMenu”, “μενού”: “0"") ή να ανακατευθύνετε τον χρήστη σε ένα μενού βοήθειας.

Μορφή παράδοσης Webhook

Όταν ενεργοποιείται η ενέργεια “webhook”, το σύστημα στέλνει ένα αίτημα HTTP POST στη διαμορφωμένη “url” με “Content-Type: application/json”.

Κεφαλίδες αιτήματος Webhook

Εάν η ενέργεια έχει διαμορφωθεί με την παράμετρο «κεφαλίδες», αυτά τα ζεύγη κλειδιών-τιμών περιλαμβάνονται ως κεφαλίδες HTTP στο αίτημα.

Σώμα αιτήματος Webhook

Το ωφέλιμο φορτίο JSON που αποστέλλεται στη διεύθυνση URL του webhook σας έχει την ακόλουθη δομή:

{
  "from": "0443914272",
  "to": "50001",
  "mid": "7748021",
  "action": {
    "confirm": true
  }
}
ΠεδίοΤύποςΠεριγραφή
«από»χορδήΑριθμός τηλεφώνου καλούντος / Αναγνωριστικό αποστολέα
«προς»χορδήΑριθμός τηλεφώνου παραλήπτη
«μέσα»χορδήΑναγνωριστικό μηνύματος
«δράση»αντικείμενοΤο προσαρμοσμένο αντικείμενο JSON που ορίζεται στο πεδίο «body» της ενέργειας

Πλήρες παράδειγμα

Απλό IVR με Timeout & Input Validation

{
  "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. Αρχεία ήχου - Βεβαιωθείτε ότι οι εισαγωγικές διευθύνσεις URL είναι προσβάσιμες και τα αρχεία ήχου είναι σε υποστηριζόμενες μορφές
  2. Αξιοπιστία Webhook - Σχεδιάστε webhook για γρήγορη απόκριση (εντός 2 δευτερολέπτων)
  3. Επιλογές DTMF - Περιορίστε τις επιλογές μενού σε 4-6 επιλογές για καλύτερη εμπειρία χρήστη
  4. Χειρισμός χρονικού ορίου - Χρησιμοποιήστε το “idleTimeoutMsec” για να καθορίσετε προσαρμοσμένα όρια αδράνειας (π.χ. 10000 ms) και διαμορφώστε μια χαριτωμένη εναλλακτική κάτω από το “λάθος” πλήκτρο DTMF (όπως επανάληψη του μενού ή κλείσιμο)
  5. Ροή κλήσης πολλαπλών μενού - Χρησιμοποιήστε προσεκτικά το “gotoMenu” για να αποτρέψετε άπειρους βρόχους κατά τη δρομολόγηση των χρηστών πίσω στα προηγούμενα μενού
  6. Στρατηγική επιστροφής - Χρησιμοποιήστε εναλλακτικά μηνύματα για χρήστες που δεν απαντούν ή αποσυνδέονται

Σχετικά θέματα