Mensajes de llamada de voz

SpeechCall es un tipo de mensaje de respuesta de voz interactiva (IVR) que le permite realizar llamadas de voz automatizadas con opciones de menú e interacciones DTMF (multifrecuencia de doble tono).

Descripción general

SpeechCall permite a las empresas: - Realizar llamadas de voz automatizadas a los clientes. - Reproducir mensajes de audio introductorios. - Presentar opciones de menú interactivo. - Manejar respuestas de pulsación de tecla DTMF (0-9, *, #) - Definir comportamiento personalizado para entradas no válidas/tiempo de espera - Activar webhooks con cuerpos y encabezados personalizados según las selecciones del usuario. - Administrar el flujo de llamadas dinámicamente (navegar entre menús)

Casos de uso

Encuestas para clientes - Recopile comentarios a través de las opciones del menú del teléfono
Recordatorios de citas - Confirme o reprograme con interacción de voz
Seguimiento de pedidos - Proporcionar actualizaciones del estado del pedido
Notificaciones interactivas - Entrega información importante con opciones de acción
Verificación por voz - Autenticación multifactor mediante llamadas de voz

Formato de solicitud

Estructura básica

{
  "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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Descripción del parámetro

Parámetro	Tipo	Requerido	Descripción
`de`	cadena	Sí	Identificador del remitente (nombre alfabético o ID)
`a`	cadena	Sí	Número de teléfono del destinatario en formato internacional
`texto`	cadena	Sí	Valor de texto, normalmente "ivr" para SpeechCall
`tipo`	cadena	Sí	Debe ser `"llamada de voz"`
`menú`	matriz	Sí	Conjunto de configuraciones de menú para la llamada

Cada objeto de menú contiene:

Parámetro	Tipo	Requerido	Descripción
`URL de introducción`	cadena	Sí	URL o identificador del archivo de audio introductorio
`idleTimeoutMsec`	entero	No	Tiempo de espera en milisegundos para esperar a que se presione una tecla (por ejemplo, "10000"). Si el usuario no responde, se ejecutarán las acciones configuradas bajo la tecla `incorrecta`
`dtmfAcciones`	objeto	Sí	Mapa de claves de acciones DTMF

Acciones DTMF

El objeto dtmfActions asigna claves DTMF o condiciones especiales a matrices de acciones:

Clave DTMF	Descripción
`d0`	Presione 0
`d1`	Presione 1
`d2`	Presione 2
...	...
`d9`	Presione 9
`d*`	Presione *
`d#`	Presione #
`incorrecto`	Se activa cuando se presiona una tecla no válida o cuando se alcanza `idleTimeoutMsec` sin ninguna entrada

Cada clave/condición DTMF se asigna a una serie de acciones que se ejecutarán en secuencia.

Acciones admitidas

Acción	Parámetros	Descripción
`webhook`	`url` (cadena, obligatoria) `cuerpo` (objeto, opcional) `encabezados` (objeto, opcional)	Envía una solicitud HTTP POST en formato JSON a la URL especificada. El objeto "cuerpo" se anidará en el campo "acción" en la solicitud del webhook. Los encabezados personalizados se incluyen como encabezados HTTP.
`colgar`	Ninguno	Finaliza la llamada
`gotoMenú`	`menú` (cadena o número entero)	Navega la llamada a otro menú en la matriz `menu` usando su índice basado en 0 (por ejemplo, `"1"`)

Formato de entrega de webhook

Cuando se activa la acción webhook, el sistema envía una solicitud HTTP POST a la url configurada con Content-Type: application/json.

Encabezados de solicitud de webhook

Si la acción está configurada con el parámetro "encabezados", esos pares clave-valor se incluyen como encabezados HTTP en la solicitud.

Cuerpo de solicitud de webhook

La carga útil JSON enviada a la URL de su webhook tiene la siguiente estructura:

{
  "from": "0443914272",
  "to": "50001",
  "mid": "7748021",
  "action": {
    "confirm": true
  }
}

Campo	Tipo	Descripción
`de`	cadena	Número de teléfono de la persona que llama / ID del remitente
`a`	cadena	Número de teléfono del destinatario
`medio`	cadena	ID de mensaje
`acción`	objeto	El objeto JSON personalizado definido en el campo "cuerpo" de la acción

Ejemplo completo

IVR simple con tiempo de espera y validación de entrada

{
  "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 complejo con múltiples menús y enrutamiento DTMF

Este ejemplo demuestra cómo definir varios menús y navegar entre ellos usando la acción "gotoMenu" cuando el usuario ingresa una clave no válida o cuando se agota el tiempo de espera de la llamada. También muestra cuerpos personalizados y encabezados HTTP personalizados enviados con los activadores de 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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Formato de respuesta

Respuesta exitosa

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

Manejo de errores

Estado HTTP	Descripción
200	Solicitud exitosa
400	Formato de solicitud no válido
401	Error de autenticación
429	Límite de tarifa excedido
500	Error interno del servidor

Ejemplo de rizo

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"
                }
              ]
            }
          }
        ]
      }
    ]
  }'

Mejores prácticas

Archivos de audio: asegúrese de que las URL de introducción sean accesibles y que los archivos de audio estén en formatos compatibles.
Confiabilidad del webhook: diseñe webhooks para responder rápidamente (en 2 segundos)
Opciones DTMF: limite las opciones del menú a 4-6 opciones para una mejor experiencia de usuario
Manejo de tiempo de espera: use idleTimeoutMsec para especificar límites de inactividad personalizados (por ejemplo, 10000 ms) y configure un respaldo elegante bajo la clave DTMF incorrecta (como repetir el menú o colgar).
Flujo de llamadas de menús múltiples - Utilice gotoMenu con cuidado para evitar bucles infinitos al redirigir a los usuarios a menús anteriores.
Estrategia alternativa: use mensajes alternativos para los usuarios que no responden o se desconectan

Temas relacionados

Enviar mensaje - Guía general de envío de mensajes
Llamada flash - Llamadas simples de verificación de voz
Verificar estado - Seguimiento del estado de entrega del mensaje
Tipos de mensajes - Descripción general de todos los tipos de mensajes admitidos