Help Center Mensagens SpeechCall

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

Descrição do parâmetro

ParâmetroTipoObrigatórioDescrição
decordaSimIdentificador do remetente (nome alfa ou ID)
paracordaSimNúmero de telefone do destinatário em formato internacional
textocordaSimValor de texto, normalmente “ivr” para SpeechCall
tipocordaSimDeve ser "speechcall"
menumatrizSimConjunto de configurações de menu para a chamada

Configuração do Menu

Cada objeto de menu contém:

ParâmetroTipoObrigatórioDescrição
introUrlcordaSimURL ou identificador do arquivo de áudio introdutório
idleTimeoutMsecinteiroNãoTempo 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çõesobjetoSimMapa 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 DTMFDescrição
d0Pressione 0
d1Pressione 1
d2Pressione 2
……
d9Pressione 9
d*Pressione *
d#Pressione #
erradoDispara 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çãoParâmetrosDescrição
webhookurl (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.
desligarNenhumTermina a chamada
gotoMenumenu (string ou inteiro)Navega a chamada para outro menu na matriz menu usando seu índice baseado em 0 (por exemplo, "1")

Comportamento de ação detalhado

Ação do webhook (webhook)

A ação webhook envia uma solicitação HTTP POST para sua URL de retorno de chamada com os metadados da chamada e dados personalizados opcionais:

  • Se um body for fornecido, seus pares de valores-chave serão enviados dentro do campo action do corpo da carga útil.
  • Se forem fornecidos cabeçalhos, eles serão enviados como cabeçalhos HTTP personalizados na solicitação.

Ação de desligar (desligar)

A ação hangup encerra a chamada ativa imediatamente. Nenhuma outra ação na sequência ou nos menus será processada após uma ação hangup.

Vá para a ação do menu (gotoMenu)

A ação gotoMenu redireciona o fluxo da chamada para uma estrutura de menu diferente dentro do array menu. É necessário um único parâmetro menu que especifica o índice baseado em 0 do menu de destino (por exemplo, "1" para ir para o segundo menu, ou "0" para reiniciar o primeiro menu).

Inatividade e tratamento de erros (errado)

A chave wrong dentro de dtmfActions é um manipulador alternativo especial. Ele executa sua sequência de ações em dois cenários:

  1. Entrada inválida: O chamador pressiona uma tecla DTMF que não está definida em dtmfActions (por exemplo, ele pressiona 3 mas o menu define apenas d1 e d2).
  2. Idle Timeout: O chamador não pressiona nenhuma tecla dentro da duração especificada por idleTimeoutMsec.

Se errado não for definido e o chamador pressionar uma tecla inválida ou atingir o tempo limite, o fluxo de chamada será interrompido por padrão. Definir wrong permite construir menus em loop (por exemplo, voltar ao mesmo menu com "action": "gotoMenu", "menu": "0") ou redirecionar o usuário para um menu de ajuda.

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
  }
}
CampoTipoDescrição
decordaNúmero de telefone do chamador/ID do remetente
paracordaNúmero de telefone do destinatário
meiocordaID da mensagem
açãoobjetoO objeto JSON personalizado definido no campo body da ação

Exemplo completo

IVR simples com tempo limite e validação 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 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": "+380XXXXXXXXX",
      "status": "sent"
    }
  ]
}

Tratamento de erros

Status HTTPDescrição
200Solicitação bem-sucedida
400Formato de solicitação inválido
401Falha na autenticação
429Limite de taxa excedido
500Erro 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