Ir para o conteúdo

Mensagens SpeechCall

SpeechCall é um tipo de mensagem de resposta de voz interativa (IVR) que permite fazer chamadas de voz automatizadas com opções de menu e interações DTMF (multifrequência de tom duplo).

Visão geral

SpeechCall permite que as empresas: - Faça chamadas de voz automatizadas para clientes - Reproduzir mensagens de áudio introdutórias - Apresentar opções de menu interativo - Lidar com respostas de pressionamento de tecla DTMF (0-9, *, #) - Definir comportamento personalizado para entradas inválidas/tempo limite - Acione webhooks com corpos e cabeçalhos personalizados com base nas seleções do usuário - Gerencie o fluxo de chamadas dinamicamente (navegue entre os menus)

Casos de uso

  • Pesquisas com clientes - Colete feedback por meio das opções do menu do telefone
  • Lembretes de compromissos - Confirme ou reagende com interação de voz
  • Rastreamento de pedidos - Fornece atualizações de status do pedido
  • Notificações interativas - Forneça informações importantes com opções de ação
  • Verificação de voz - Autenticação multifator por meio de chamadas de voz

Formato de solicitação

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

Descrição do parâmetro

Parâmetro Tipo Obrigatório Descrição
de corda Sim Identificador do remetente (nome alfa ou ID)
para corda Sim Número de telefone do destinatário em formato internacional
texto corda Sim Valor de texto, normalmente "ivr" para SpeechCall
tipo corda Sim Deve ser "speechcall"
menu matriz Sim Conjunto de configurações de menu para a chamada

Configuração do Menu

Cada objeto de menu contém:

Parâmetro Tipo Obrigatório Descrição
introUrl corda Sim URL ou identificador do arquivo de áudio introdutório
idleTimeoutMsec inteiro Não Tempo limite em milissegundos para aguardar o pressionamento de uma tecla (por exemplo, 10000). Caso o usuário não responda, as ações configuradas na tecla errada serão executadas
dtmfAções objeto Sim Mapa de chaves de ações DTMF

Ações DTMF

O objeto dtmfActions mapeia chaves DTMF ou condições especiais para matrizes de ações:

Chave DTMF Descrição
d0 Pressione 0
d1 Pressione 1
d2 Pressione 2
... ...
d9 Pressione 9
d* Pressione *
d# Pressione #
errado Dispara quando uma tecla inválida é pressionada ou quando idleTimeoutMsec é alcançado sem qualquer entrada

Cada chave/condição DTMF é mapeada para uma série de ações que serão executadas em sequência.

Ações suportadas

Ação Parâmetros Descrição
webhook url (string, obrigatório)
body (objeto, opcional)
headers (objeto, opcional)		 Envia uma solicitação HTTP POST no formato JSON para o URL especificado. O objeto body será aninhado no campo action na solicitação do webhook. Cabeçalhos personalizados são incluídos como cabeçalhos HTTP.
desligar Nenhum Termina a chamada
gotoMenu menu (string ou inteiro) Navega a chamada para outro menu na matriz menu usando seu índice baseado em 0 (por exemplo, "1")

Formato de entrega do webhook

Quando a ação webhook é acionada, o sistema envia uma solicitação HTTP POST para o url configurado com Content-Type: application/json.

Cabeçalhos de solicitação de webhook

Se a ação estiver configurada com o parâmetro headers, esses pares chave-valor serão incluídos como cabeçalhos HTTP na solicitação.

Corpo da solicitação do webhook

A carga JSON enviada para o URL do seu webhook tem a seguinte estrutura:

{
  "from": "0443914272",
  "to": "50001",
  "mid": "7748021",
  "action": {
    "confirm": true
  }
}
Campo Tipo Descrição
de corda Número de telefone do chamador/ID do remetente
para corda Número de telefone do destinatário
meio corda ID da mensagem
ação objeto O objeto JSON personalizado definido no campo body da ação

Exemplo completo

IVR simples com tempo limite e validação 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 complexo com vários menus e roteamento DTMF

Este exemplo demonstra como definir vários menus e navegar entre eles usando a ação gotoMenu quando o usuário insere uma chave inválida ou quando a chamada atinge o tempo limite. Ele também mostra corpos e cabeçalhos HTTP personalizados enviados com os gatilhos de webhook.

CODE_BLOCO_3

Formato de resposta

Resposta de sucesso

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

Tratamento de erros

Status HTTP Descrição
200 Solicitação bem-sucedida
400 Formato de solicitação inválido
401 Falha na autenticação
429 Limite de taxa excedido
500 Erro interno do servidor

Exemplo de cURL

CODE_BLOCO_5

Melhores práticas

  1. Arquivos de áudio – Certifique-se de que os URLs de introdução estejam acessíveis e que os arquivos de áudio estejam em formatos compatíveis
  2. Confiabilidade do Webhook - Projete webhooks para responder rapidamente (dentro de 2 segundos)
  3. Opções DTMF - Limite as opções do menu a 4 a 6 opções para melhor experiência do usuário
  4. Tratamento de tempo limite - Use idleTimeoutMsec para especificar limites de inatividade personalizados (por exemplo, 10.000 ms) e configure um substituto elegante sob a chave DTMF errada (como repetir o menu ou desligar)
  5. Fluxo de chamada multimenu - Use gotoMenu com cuidado para evitar loops infinitos ao direcionar os usuários de volta aos menus anteriores
  6. Estratégia substituta – Use mensagens substitutas para usuários que não atendem ou desconectam

Tópicos Relacionados