Messages d'appel vocal
SpeechCall est un type de message de réponse vocale interactive (IVR) qui vous permet de passer des appels vocaux automatisés avec des options de menu et des interactions DTMF (double tonalité multifréquence).
Aperçu
SpeechCall permet aux entreprises de :
- Passer des appels vocaux automatisés aux clients
- Lire des messages audio d’introduction
- Présenter les options de menu interactives
- Gérer les réponses aux touches DTMF (0-9, *, #)
- Définir un comportement personnalisé pour les entrées invalides/délai d’expiration
- Déclenchez des webhooks avec des corps et des en-têtes personnalisés en fonction des sélections de l’utilisateur
- Gérer le flux d’appels de manière dynamique (naviguer entre les menus)
Cas d’utilisation
- Enquêtes clients - Recueillez des commentaires via les options du menu du téléphone
- Rappels de rendez-vous - Confirmez ou reprogrammez avec une interaction vocale
- Suivi des commandes - Fournir des mises à jour sur l’état des commandes
- Notifications interactives - Fournissez des informations importantes avec des options d’action
- Vérification vocale - Authentification multifacteur via des appels vocaux
Format de la demande
Structure de base
{
"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"
}
]
}
}
]
}
]
}
Description du paramètre
| Paramètre | Tapez | Obligatoire | Descriptif |
|---|---|---|---|
de | chaîne | Oui | Identifiant de l’expéditeur (nom alphabétique ou identifiant) |
à | chaîne | Oui | Numéro de téléphone du destinataire au format international |
texte | chaîne | Oui | Valeur de texte, généralement « ivr » pour SpeechCall |
type | chaîne | Oui | Doit être « « appel vocal » » |
menu | tableau | Oui | Tableau de configurations de menu pour l’appel |
Configuration des menus
Chaque objet de menu contient :
| Paramètre | Tapez | Obligatoire | Descriptif |
|---|---|---|---|
introUrl | chaîne | Oui | URL ou identifiant du fichier audio d’introduction |
idleTimeoutMsec | entier | Non | Délai d’attente en millisecondes pour attendre une pression sur une touche (par exemple, « 10 000 »). Si l’utilisateur ne répond pas, les actions configurées sous la touche « mauvaise » seront exécutées |
dtmfActions | objet | Oui | Carte des clés d’actions DTMF |
### Actions DTMF
L’objet dtmfActions mappe les clés DTMF ou les conditions spéciales à des tableaux d’actions :
| Clé DTMF | Descriptif |
|---|---|
d0 | Appuyez sur 0 |
d1 | Appuyez sur 1 |
| ’d2’ | Appuyez sur 2 |
| … | … |
| ‘d9’ | Appuyez sur 9 |
d* | Appuyez sur * |
d# | Appuyez sur # |
| ‘faux’ | Se déclenche lorsqu’une touche invalide est enfoncée ou lorsque idleTimeoutMsec est atteint sans aucune entrée |
Chaque clé/condition DTMF correspond à un tableau d’actions qui seront exécutées en séquence.
Actions prises en charge
| Actions | Paramètres | Descriptif |
|---|---|---|
webhook | url (chaîne, obligatoire)body (objet, facultatif)headers (objet, facultatif) | Envoie une requête HTTP POST au format JSON à l’URL spécifiée. L’objet body sera imbriqué sous le champ action dans la requête webhook. Les en-têtes personnalisés sont inclus en tant qu’en-têtes HTTP. |
raccrocher | Aucun | Termine l’appel |
aller au Menu | menu (chaîne ou entier) | Navigue l’appel vers un autre menu du tableau menu en utilisant son index basé sur 0 (par exemple, "1") |
Comportement d’action détaillé
Action Webhook (webhook)
L’action webhook envoie une requête HTTP POST à votre URL de rappel avec les métadonnées de l’appel et des données personnalisées facultatives :
- Si un « corps » est fourni, ses paires clé-valeur sont envoyées dans le champ « action » du corps de la charge utile.
- Si des « en-têtes » sont fournis, ils sont envoyés en tant qu’en-têtes HTTP personnalisés dans la requête.
Action de raccrochage (« raccrochage »)
L’action « raccrocher » met immédiatement fin à l’appel actif. Aucune autre action dans la séquence ou dans les menus ne sera traitée après une action de « raccrochage ».
Aller à l’action du menu (gotoMenu)
L’action gotoMenu redirige le flux de l’appel vers une structure de menu différente au sein du tableau menu. Il prend un seul paramètre menu qui spécifie l’index basé sur 0 du menu cible (par exemple, "1" pour aller au deuxième menu, ou "0" pour redémarrer le premier menu).
Inactivité et gestion des erreurs (« faux »)
La « mauvaise » clé dans « dtmfActions » est un gestionnaire de secours spécial. Il exécute sa séquence d’actions dans deux scénarios :
- Entrée invalide : L’appelant appuie sur une touche DTMF qui n’est pas définie dans
dtmfActions(par exemple, il appuie sur3mais le menu ne définit qued1etd2). - Idle Timeout : L’appelant n’appuie sur aucune touche pendant la durée spécifiée par
idleTimeoutMsec.
Si « faux » n’est pas défini et que l’appelant appuie sur une touche invalide ou expire, le flux d’appels raccrochera par défaut. Définir wrong vous permet de créer des menus en boucle (par exemple revenir au même menu avec "action": "gotoMenu", "menu": "0") ou de rediriger l’utilisateur vers un menu d’aide.
Format de livraison des webhooks
Lorsque l’action webhook est déclenchée, le système envoie une requête HTTP POST à l’url configurée avec Content-Type : application/json.
En-têtes de requête de webhook
Si l’action est configurée avec le paramètre « headers », ces paires clé-valeur sont incluses en tant qu’en-têtes HTTP dans la requête.
Corps de la demande de webhook
La charge utile JSON envoyée à l’URL de votre webhook a la structure suivante :
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| Champ | Tapez | Descriptif |
|---|---|---|
de | chaîne | Numéro de téléphone de l’appelant / ID de l’expéditeur |
à | chaîne | Numéro de téléphone du destinataire |
milieu | chaîne | Identifiant du message |
| ’action’ | objet | L’objet JSON personnalisé défini dans le champ body de l’action |
Exemple complet
IVR simple avec délai d’attente et validation des entrées
{
"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 complexe avec plusieurs menus et routage DTMF
Cet exemple montre comment définir plusieurs menus et naviguer entre eux à l’aide de l’action « gotoMenu » lorsque l’utilisateur saisit une clé non valide ou lorsque l’appel expire. Il affiche également les corps personnalisés et les en-têtes HTTP personnalisés envoyés avec les déclencheurs 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"
}
]
}
}
]
}
]
}
Format de réponse
Réponse réussie
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Gestion des erreurs
| Statut HTTP | Descriptif |
|---|---|
| 200 | Demande réussie |
| 400 | Format de demande invalide |
| 401 | Échec de l’authentification |
| 429 | Limite de débit dépassée |
| 500 | Erreur de serveur interne |
Exemple d’URL
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"
}
]
}
}
]
}
]
}'
## meilleures pratiques
- Fichiers audio : assurez-vous que les URL d’introduction sont accessibles et que les fichiers audio sont dans les formats pris en charge.
- Fiabilité des webhooks – Concevez des webhooks pour répondre rapidement (dans les 2 secondes)
- Options DTMF - Limitez les options de menu à 4 à 6 choix pour une meilleure expérience utilisateur
- Gestion des délais d’attente - Utilisez
idleTimeoutMsecpour spécifier des limites d’inactivité personnalisées (par exemple 10 000 ms) et configurez une solution de secours gracieuse sous lamauvaiseclé DTMF (comme répéter le menu ou raccrocher) - Flux d’appels multi-menus - Utilisez
gotoMenuavec précaution pour éviter des boucles infinies lors du routage des utilisateurs vers les menus précédents - Stratégie de secours – Utilisez des messages de secours pour les utilisateurs qui ne répondent pas ou ne se déconnectent pas
Sujets connexes
- Envoyer un message - Guide général d’envoi de messages - Appel Flash – Appels de vérification vocale simples
- Vérifier l’état - Suivre l’état de livraison des messages
- Types de messages - Aperçu de tous les types de messages pris en charge