Para usar a telefonia Aircall no Mavibot, você precisa criar um par de chaves de API na sua conta Aircall e inseri-las nas configurações de integração.

Aircall é um sistema telefônico baseado em nuvem para equipes de vendas e suporte, oferecendo números de telefone em mais de 100 países. Ele é projetado para empresas cujos funcionários já usam o aplicativo Aircall: o bot faz chamadas em nome de um funcionário, em vez de usar um número separado do bot.

O bot pode conectar um funcionário a um cliente, recuperar gravações de chamadas e enviar eventos de chamada para a conversa.

Obtendo os dados necessários

  1. Cadastre-se em aircall.io, compre um número de telefone no país desejado e crie usuários Aircall para seus funcionários.
  2. Abra Dashboard → Configurações → Integrações e API → Chaves de API e crie um par de chaves:
    • API ID
    • API Token
  3. Encontre o Number ID para o número que será usado para chamadas de saída e os User IDs para seus funcionários. Esses IDs são visíveis na barra de endereço quando você abre as páginas correspondentes no painel do Aircall.

API Token é mostrado apenas uma vez quando é criado. Se você o perder, crie um novo par de chaves de API e revogue o antigo.

Conexão

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

  • API ID — o identificador da chave de API.
  • API Token — o token secreto da API.
  • Number ID — o ID numérico da linha Aircall que será usada para chamadas de saída.

A integração agora está conectada.


Para desconectar a integração, limpe o campo API ID e salve as configurações.

Funcionários

Nas configurações do funcionário, preencha o campo Aircall User ID com o ID numérico da conta Aircall do funcionário.

Insira o ID do usuário, não o número de telefone do funcionário. Sem esse ID, o botão de chamada no cartão do cliente não funcionará para esse funcionário.

Chamada a partir 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 Aircall primeiro inicia a chamada no aplicativo Aircall do funcionário — no desktop ou celular. Quando o funcionário atende, a Aircall liga para o cliente e conecta ambas as partes.

A chamada não será concluída se o funcionário estiver offline, já em outra chamada ou não atribuído ao número selecionado no Aircall. Esta é uma limitação do Aircall: as chamadas só podem ser feitas por meio de um usuário disponível.

Funções da Calculadora

Chamada de Funcionário para Cliente

aircall_employee_call(client_phone, employee_user_id, number_id)

Parâmetros:

  • client_phone — o número de telefone do cliente no formato internacional E.164. Obrigatório.
  • employee_user_id — o ID de usuário Aircall do funcionário que receberá a chamada no aplicativo Aircall. Obrigatório.
  • number_id — o ID do número Aircall usado para fazer a chamada. Opcional. Se omitido, o número configurado nas configurações de integração é usado.

aircall_get_record_link(call_id)

Solicita um link novo para a gravação da chamada.

Parâmetros:

  • call_id — o ID da chamada Aircall. 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:

aircall_call_event call.answered

Eventos possíveis:

Evento Quando é acionado
call.created A chamada foi criada
call.ringing_on_agent O funcionário está recebendo a chamada
call.answered A chamada foi atendida
call.hungup Uma das partes desligou
call.ended A chamada terminou completamente
call.voicemail_left O cliente deixou um correio de voz

Um cenário típico de "sem resposta → enviar mensagem no mensageiro" pode ser acionado por call.ended e verificando a variável aircall_missed_reason.

Variáveis do Cliente Após uma Chamada

Após uma chamada, as seguintes variáveis estão disponíveis para o cliente:

Variável Valor
aircall_call_id ID da chamada Aircall
aircall_call_direction Direção da chamada: inbound ou outbound
aircall_call_status Status da chamada: initial, answered ou done
aircall_call_duration Duração da chamada em segundos
aircall_missed_reason Motivo pelo qual a chamada não foi concluída
aircall_record_link Link para a gravação da chamada

Gravações de Chamadas

A gravação de chamadas deve estar habilitada nas suas configurações do Aircall. As gravações são armazenadas na sua conta Aircall.

⏳ Os links de gravação do Aircall estão disponíveis por tempo limitado — normalmente apenas por algumas horas após a chamada. Depois disso, os links param de funcionar. Isso é como o Aircall funciona e não é uma limitação do Mavibot.

O que isso significa:

  • Em um cenário que envia uma gravação de chamada, chame aircall_get_record_link() no momento em que a gravação é enviada em vez de usar um link salvo anteriormente.
  • Se você precisar manter uma gravação permanentemente, salve o arquivo no seu próprio armazenamento imediatamente após a chamada.
  • O arquivo de gravação permanece disponível no painel do Aircall, onde as gravações podem ser reproduzidas e baixadas posteriormente.

A gravação de chamadas é regulamentada por lei. Na Alemanha, França, Espanha e em muitos estados dos EUA, o consentimento de ambas as partes pode ser necessário, e em algumas jurisdições, uma notificação verbal no início da chamada também pode ser necessária. O proprietário da conta Aircall é responsável por cumprir as leis e regulamentos aplicáveis.

Solução de Problemas

Erro Causa / Solução
Erro de autorização ao fazer uma chamada O par API ID / API Token está incorreto. O token é mostrado apenas uma vez quando é criado. Se foi perdido, crie um novo par em Chaves de API e revogue o antigo.
A chamada não é criada ou o funcionário não recebe a chamada O funcionário está offline no aplicativo Aircall, já está em outra chamada ou não está atribuído ao número selecionado nas configurações do Aircall.
"Aircall User ID não especificado" O campo Aircall User ID nas configurações do funcionário está vazio, ou um número de telefone foi inserido em vez do ID numérico do usuário.
As chamadas funcionam, mas nenhum callback aparece na conversa O webhook não foi registrado. Salve as configurações de integração do Aircall novamente para registrá-lo.
O link de gravação não abre O link expirou. Solicite um novo link usando aircall_get_record_link() ou abra a gravação diretamente no painel do Aircall.