Para usar a telefonia TotalVoice no Mavibot, você precisa obter um Access Token no painel da TotalVoice e inseri-lo nas configurações de integração. A TotalVoice é um serviço de telefonia brasileiro que agora faz parte do grupo Zenvia.

O bot pode conectar um funcionário a um cliente, transferir e encerrar chamadas, recuperar gravações de chamadas e enviar eventos de chamada para a conversa. A TotalVoice também fornece o custo de cada chamada.

Obtendo os dados necessários

  1. Crie uma conta Zenvia Voice e adicione créditos ao seu saldo.

  1. Faça login no painel. No canto inferior esquerdo da tela principal, ao lado de Access Token, clique no ícone de copiar.

Access Token é a única chave que fornece acesso a toda a sua conta, incluindo fazer chamadas pagas. Não o publique nem o compartilhe fora da sua empresa.

Conexão

Nas configurações de telefonia, selecione TotalVoice e insira:

  • Access Token — a chave do painel da TotalVoice.
  • Número de exibição para o cliente — o número que o cliente verá, no formato +551140028922. Este campo é opcional. Se deixado vazio, o número padrão da sua conta TotalVoice será usado.


Após salvar, uma URL de notificação aparecerá na página de conexão. Você precisa adicioná-la ao painel da TotalVoice — veja a próxima seção.

A integração agora está conectada. Para desconectá-la, limpe o campo Access Token e salve as configurações.

Configuração de notificações

Diferente de outras integrações de telefonia, a URL de notificação deve ser configurada manualmente porque a TotalVoice não fornece uma maneira para o Mavibot fazer isso automaticamente.

  1. Copie a URL mostrada na página de conexão.

  1. No painel da TotalVoice, abra Desenvolvedores → Configurações da API.
  2. Cole a mesma URL em todos os três campos de webhook:
    • Status Tempo Real — mudanças de status da chamada enquanto ela está em andamento;
    • Chamada - Fim — fim de uma chamada;
    • DID - Fim de Chamada — fim de uma chamada recebida no seu número.

⏳ As notificações podem levar até 20 minutos para começar a chegar após salvar as configurações. Esta é uma limitação da TotalVoice. Se nenhum evento aparecer na conversa imediatamente após a configuração, basta aguardar.

Se você regenerar seu Access Token, a URL de notificação mudará. Salve o novo token no Mavibot e atualize a URL no painel da TotalVoice, caso contrário, os eventos de chamada pararão de chegar.

Funcionários

Nas configurações do funcionário, insira o número TotalVoice do funcionário.


Você pode usar um ramal interno (ramal, geralmente 3–4 dígitos) ou um número de celular comum no formato +5511987654321. Esta é uma das poucas integrações onde o formato é flexível: se o funcionário não usa um ramal de PABX interno, insira o número do celular dele.

Ligando do cartão do cliente

Um botão de chamada aparecerá ao lado do número de telefone do cliente no cartão da conversa. A TotalVoice primeiro liga para o funcionário, e somente depois que o funcionário atende, ela liga para o cliente.

Esta ordem é intencional: o cliente não ouvirá silêncio na linha porque o funcionário já está conectado quando o telefone do cliente começa a tocar.

Funções da Calculadora

Chamada de Funcionário para Cliente

totalvoice_employee_call(client_phone, employee_number, bina, gravar_audio)

Parâmetros:

  • client_phone — o número de telefone do cliente no formato +5511987654321. Obrigatório.
  • employee_number — o número do funcionário: um ramal interno ou um número de celular. Obrigatório.
  • bina — o número que o cliente verá. Opcional. Se omitido, o número das configurações de conexão é usado.
  • gravar_audio — se deve gravar a chamada. Opcional. A gravação está habilitada por padrão.

Transferir Chamada

totalvoice_transfer_call(number, call_id, leg)

Parâmetros:

  • number — o número para o qual a chamada deve ser transferida. Obrigatório.
  • call_id — o identificador da chamada. Opcional. Se omitido, a chamada mais recente do cliente é usada.
  • leg — qual lado da chamada transferir: destino (o cliente, valor padrão) ou origem (o funcionário).

Encerrar Chamada

totalvoice_hangup_call(call_id)

Parâmetros:

  • call_id — o identificador da chamada. Opcional. Se omitido, a chamada mais recente do cliente é usada.
totalvoice_get_record_link(call_id)

Normalmente, o link de gravação é recebido automaticamente com o evento de fim de chamada. Esta função é útil se a notificação não foi recebida ou se você precisa de uma gravação de uma chamada mais antiga.

Parâmetros:

  • call_id — o identificador da chamada. Opcional. Se omitido, a chamada mais recente do cliente é usada.

Callbacks Durante uma Chamada

Conforme a chamada progride, callbacks são enviados para a conversa no seguinte formato:

totalvoice_call_event atendida

Eventos possíveis:

Evento Quando é acionado
chamando A chamada está tocando
preparando A linha está sendo preparada para conexão
atendida A chamada foi atendida
sem_resposta Sem resposta
ocupado Ocupado
cancelada A chamada foi cancelada
congestionado Congestionamento na rede da operadora
falha A chamada não pôde ser completada
nao_existe O número não existe

Os nomes dos status são recebidos em português porque esses são os nomes de status usados pela TotalVoice.

Um cenário típico de "sem resposta → enviar uma mensagem no mensageiro" pode ser construído verificando a variável totalvoice_call_answered.

As notificações de status de chamada são enviadas no máximo uma vez a cada 2 segundos por chamada. Para chamadas muito curtas, alguns status intermediários podem não chegar a tempo. O evento de fim de chamada é sempre enviado.

Variáveis do Cliente Após uma Chamada

Variável Valor
totalvoice_call_id Identificador da chamada
totalvoice_call_status Status da chamada conforme definido pela TotalVoice
totalvoice_call_answered 1 — a chamada foi atendida, 0 — não foi
totalvoice_call_duration Duração da chamada em segundos
totalvoice_call_price Custo da chamada em reais brasileiros
totalvoice_hangup_reason Motivo do fim da chamada
totalvoice_record_link Link para a gravação da chamada

Duração significa tempo real de conversa, excluindo o tempo gasto esperando a chamada ser atendida. Lembre-se de que a TotalVoice calcula a cobrança de forma diferente: o tempo faturável é arredondado para o próximo minuto inteiro, então uma chamada de 24 segundos será cobrada como um minuto. Para verificar cobranças, use o relatório de faturamento no painel da TotalVoice em vez desta variável.

Gravações de Chamadas

A gravação é configurada separadamente para cada chamada e está habilitada por padrão. Você pode desativá-la para uma chamada específica usando o parâmetro gravar_audio na função de chamada.

Quando a chamada termina, o link de gravação é recebido com o evento e salvo na variável totalvoice_record_link. Você não precisa solicitá-lo separadamente.

A gravação de chamadas é regulamentada por lei. No Brasil, está sujeita aos requisitos da LGPD: o cliente deve ser informado de que a chamada está sendo gravada, e deve haver uma base legal para armazenar os dados. O proprietário da conta TotalVoice é responsável por cumprir esses requisitos.

Solução de Problemas

Erro Causa / Solução
A chamada não é criada e a mensagem de erro está em português A TotalVoice retorna o motivo como texto. As causas mais comuns são saldo insuficiente ou formato de número de telefone inválido.
As chamadas funcionam, mas nenhum callback aparece na conversa A URL de notificação não foi adicionada ao painel da TotalVoice, não foi adicionada a todos os três webhooks, ou 20 minutos não se passaram desde a configuração.
Tudo funcionava antes, mas os eventos pararam de repente O Access Token foi regenerado, o que mudou a URL de notificação. Salve o novo token no Mavibot e atualize a URL no painel da TotalVoice.
"Número TotalVoice não especificado" O número TotalVoice do funcionário está faltando nas configurações dele.
Status nao_existe O número do cliente não existe. Verifique o formato. Números de celular brasileiros usam +55 + DDD + 9 dígitos.
Status congestionado Há um problema com a rede da operadora e não está relacionado ao número do cliente. Se o problema persistir, entre em contato com o suporte da TotalVoice.
Sem link de gravação A chamada foi criada com gravação desativada, ou a chamada não foi atendida.