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": "BazarCOM",
      "to": "+380936670003",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://api.example.com/callback/option1",
                "body": {
                  "confirm": true
                },
                "headers": {
                  "X-Custom-Header": "value"
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://api.example.com/callback/option2",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "hangup"
              }
            ]
          }
        }
      ]
    }
  ]
}

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"`)

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": "BazarCOM",
      "to": "+380936670003",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://api.example.com/callback/option1",
                "body": {
                  "confirm": true
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://api.example.com/callback/option2",
                "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_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "http://api.smsbat.local/gatereq/temp/hook",
                "body": {
                  "confirm": true
                },
                "headers": {
                  "test-header": "test"
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "http://api.smsbat.local/gatereq/temp/hook",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "gotoMenu",
                "menu": "1"
              }
            ]
          }
        },
        {
          "introUrl": "ivr_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "http://localhost/1"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "http://localhost/1"
              }
            ],
            "wrong": [
              {
                "action": "hangup"
              }
            ]
          }
        }
      ]
    }
  ]
}

Format de réponse

Réponse réussie

{
  "messages": [
    {
      "messageId": "unique-message-id",
      "recipient": "+380936670003",
      "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_651854",
            "idleTimeoutMsec": 10000,
            "dtmfActions": {
              "d1": [
                {
                  "action": "webhook",
                  "url": "http://api.smsbat.local/gatereq/temp/hook",
                  "body": {
                    "confirm": true
                  },
                  "headers": {
                    "test-header": "test"
                  }
                },
                {
                  "action": "hangup"
                }
              ],
              "d2": [
                {
                  "action": "webhook",
                  "url": "http://api.smsbat.local/gatereq/temp/hook",
                  "body": {
                    "confirm": false
                  }
                },
                {
                  "action": "hangup"
                }
              ],
              "wrong": [
                {
                  "action": "gotoMenu",
                  "menu": "1"
                }
              ]
            }
          },
          {
            "introUrl": "ivr_651854",
            "idleTimeoutMsec": 10000,
            "dtmfActions": {
              "d1": [
                {
                  "action": "webhook",
                  "url": "http://localhost/1"
                }
              ],
              "d2": [
                {
                  "action": "webhook",
                  "url": "http://localhost/1"
                }
              ],
              "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 idleTimeoutMsec pour spécifier des limites d'inactivité personnalisées (par exemple 10 000 ms) et configurez une solution de secours gracieuse sous la mauvaise clé DTMF (comme répéter le menu ou raccrocher)
Flux d'appels multi-menus - Utilisez gotoMenu avec 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