Help Center Mensajes de llamada de voz

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

Descripción del parámetro

ParámetroTipoRequeridoDescripción
decadenaSíIdentificador del remitente (nombre alfabético o ID)
acadenaSíNúmero de teléfono del destinatario en formato internacional
textocadenaSíValor de texto, normalmente “ivr” para SpeechCall
tipocadenaSíDebe ser "llamada de voz"
menúmatrizSíConjunto de configuraciones de menú para la llamada

Configuración del menú

Cada objeto de menú contiene:

ParámetroTipoRequeridoDescripción
URL de introduccióncadenaSíURL o identificador del archivo de audio introductorio
idleTimeoutMsecenteroNoTiempo 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
dtmfAccionesobjetoSíMapa de claves de acciones DTMF

Acciones DTMF

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

Clave DTMFDescripción
d0Presione 0
d1Presione 1
d2Presione 2
……
d9Presione 9
d*Presione *
d#Presione #
incorrectoSe 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ónParámetrosDescripción
webhookurl (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.
colgarNingunoFinaliza 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")

Comportamiento de acción detallado

Acción de webhook (webhook)

La acción webhook envía una solicitud HTTP POST a su URL de devolución de llamada con los metadatos de la llamada y datos personalizados opcionales:

  • Si se proporciona un “cuerpo”, sus pares clave-valor se envían dentro del campo “acción” del cuerpo de la carga útil.
  • Si se proporcionan “encabezados”, se envían como encabezados HTTP personalizados en la solicitud.

Acción de colgar (colgar)

La acción “colgar” finaliza la llamada activa inmediatamente. No se procesarán más acciones en la secuencia o menús después de una acción de “colgar”.

Ir a la acción del menú (gotoMenu)

La acción gotoMenu redirige el flujo de la llamada a una estructura de menú diferente dentro de la matriz menu. Se necesita un único parámetro menu que especifica el índice basado en 0 del menú de destino (por ejemplo, "1" para ir al segundo menú, o "0" para reiniciar el primer menú).

Inactividad y manejo de errores (incorrecto)

La clave “incorrecta” dentro de “dtmfActions” es un controlador de falla especial. Ejecuta su secuencia de acciones en dos escenarios:

  1. Entrada no válida: La persona que llama presiona una tecla DTMF que no está definida en dtmfActions (por ejemplo, presiona 3 pero el menú solo define d1 y d2).
  2. Tiempo de espera de inactividad: la persona que llama no presiona ninguna tecla dentro del tiempo especificado por idleTimeoutMsec.

Si no se define “incorrecto” y la persona que llama presiona una tecla no válida o se agota el tiempo de espera, el flujo de llamada se colgará de forma predeterminada. Definir incorrecto le permite crear menús en bucle (por ejemplo, volver al mismo menú con "action": "gotoMenu", "menu": "0") o redirigir al usuario a un menú de ayuda.

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
  }
}
CampoTipoDescripción
decadenaNúmero de teléfono de la persona que llama / ID del remitente
acadenaNúmero de teléfono del destinatario
mediocadenaID de mensaje
acciónobjetoEl 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": "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 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_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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Formato de respuesta

Respuesta exitosa

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

Manejo de errores

Estado HTTPDescripción
200Solicitud exitosa
400Formato de solicitud no válido
401Error de autenticación
429Límite de tarifa excedido
500Error 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_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"
                }
              ]
            }
          }
        ]
      }
    ]
  }'

Mejores prácticas

  1. 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.
  2. Confiabilidad del webhook: diseñe webhooks para responder rápidamente (en 2 segundos)
  3. Opciones DTMF: limite las opciones del menú a 4-6 opciones para una mejor experiencia de usuario
  4. 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).
  5. 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.
  6. Estrategia alternativa: use mensajes alternativos para los usuarios que no responden o se desconectan

Temas relacionados