Integração com Helpdesk personalizado

Visão geral

A integração de Helpdesk personalizado permite que o Virtual-Call Cloud PABX se conecte com praticamente qualquer sistema de helpdesk ou ticketing que suporte REST API. Este framework de integração flexível permite que você estenda a funcionalidade do seu sistema de helpdesk com recursos avançados de telecomunicações, criando uma experiência unificada de comunicação e suporte.

Através de templates personalizados, você pode configurar como o Virtual-Call Cloud PABX se comunica com sua plataforma de helpdesk. Isso permite interação perfeita entre seu sistema de telefonia e ferramentas de suporte, eliminando a necessidade de múltiplas aplicações e reduzindo a entrada de dados manual.

Principais recursos

• Click-to-Call: Inicie chamadas diretamente da sua interface de helpdesk utilizando o botão de telefone virtual
• Call Popup: O popup automático exibe informações relevantes do cliente ao receber ou fazer chamadas
• Contact Synchronization: Sincronize automaticamente contatos do seu helpdesk para o Virtual-Call UC Client
• Contact Creation: Crie automaticamente novos contatos em seu helpdesk conforme necessário
• Call Journal: Registre detalhes de chamadas e notas diretamente em seu sistema de helpdesk
• Automatic Ticket Creation: Crie tickets de suporte automaticamente com base em eventos de chamada

Pré-requisitos

• Plan Requirements: Plano de assinatura Enterprise ou Ultimate
• API Support: Seu sistema de helpdesk deve suportar integração de REST API
• Template Limit: Até 10 templates de integração personalizados podem ser criados por sistema
• Firmware Version: Versão de firmware Virtual-Call Cloud PABX 84.21.0.66 ou posterior
• API Documentation: Documentação completa dos endpoints de REST API e métodos de autenticação do seu helpdesk
• Network Access: Cloud PABX deve ter acesso de rede aos endpoints da API do seu helpdesk

Crie um template de integração

Templates de integração definem como o Virtual-Call Cloud PABX se comunica com seu sistema de helpdesk. Crie e configure templates para corresponder aos requisitos da API do seu helpdesk.

Etapa 1: Navegue até a integração de Helpdesk

Faça login no console de gerenciamento do Virtual-Call Cloud PABX e navegue até:

CRM > Integrations > Helpdesk

Selecione a opção Custom para criar um novo template de integração de helpdesk personalizado.

Etapa 2: Crie um novo template

Clique no botão Add para criar um novo template de integração personalizado. Você será solicitado a configurar várias seções.

Etapa 3: Configure as configurações gerais

Na seção General, configure os parâmetros básicos para sua integração:

• Template Name: Digite um nome descritivo para este template de integração (por exemplo, "Zendesk Support", "Jira Service Management")
• Logo URL: Forneça a URL para uma imagem de logo do seu sistema de helpdesk (exibida na interface do usuário)
• Max Concurrent Requests: Defina o número máximo de solicitações de API simultâneas para seu sistema de helpdesk. Comece com um valor conservador e ajuste com base no monitoramento de desempenho.
• Enable Testing Mode: Alterne para ativar o modo de teste para validar configurações antes da implantação

Etapa 4: Configure a autenticação

Selecione o método de autenticação exigido pela API do seu helpdesk. Virtual-Call Cloud PBX suporta múltiplos esquemas de autenticação:

• None: Nenhuma autenticação necessária (apenas endpoints de API pública)
• Basic Authentication: Credenciais de nome de usuário e senha
  • Digite os campos de Nome de Usuário e Senha
  • As credenciais são codificadas em Base64 no cabeçalho de Autorização
• OAuth 2.0: Autenticação baseada em token
  • Configure URL do Token, Client ID e Client Secret
  • Suporta tipos de concessão de código de autorização e credenciais do cliente
  • Os tokens são atualizados automaticamente conforme necessário
• Bearer Token: Autenticação de token estático
  • Digite seu token ou chave de API
  • Os tokens são incluídos no cabeçalho de Autorização para todas as solicitações

Etapa 5: Configure a pesquisa de contatos (obrigatório para a maioria dos recursos)

A configuração de Pesquisa de Contatos é essencial para ativar Contact Synchronization, Call Popup e outros recursos que recuperam dados de clientes do seu helpdesk.

API Endpoint Configuration:

• Search API URL: Digite o endpoint de REST API usado para pesquisar contatos (por exemplo, `https://api.example-helpdesk.com/v2/contacts/search`)
• Request Method: Selecione GET ou POST dependendo do design da API do seu helpdesk
• Request Parameters: Defina como as consultas de pesquisa são enviadas (cadeia de consulta, corpo da solicitação, cabeçalhos).
• Test Search: Use a funcionalidade de teste para validar o endpoint de API com dados de exemplo

Contact Field Mapping:

Mapeie os campos de resposta da API do seu helpdesk para os campos do Virtual-Call Cloud PABX. Os mapeamentos obrigatórios permitem a exibição adequada das informações do cliente:

• Contact ID: O identificador único de cada contato
• First Name: Primeiro nome do contato
• Last Name: Sobrenome do contato
• Display Name: Nome como aparece na interface do usuário
• Phone Number: Número de telefone de contato principal
• Email: Endereço de e-mail
• Company: Nome da organização
• Additional Fields: Adicione campos personalizados específicos do seu sistema de helpdesk

Etapa 6: Configure a criação de contatos (Opcional)

Se você quiser que o Virtual-Call Cloud PABX crie automaticamente contatos em seu sistema de helpdesk, configure as configurações de Criação de Contatos.

• API Endpoint: Digite o endpoint de REST API para criar novos contatos (por exemplo, `https://api.example-helpdesk.com/v2/contacts`)
• Request Method: Normalmente POST para criar recursos
• Field Mapping: Defina quais campos de Virtual-Call Cloud PABX mapeiam para campos de contato de helpdesk.
• Enable Contact Creation: Alterne para ativar a criação automática de contatos durante chamadas

Etapa 7: Configure o Call Journal (opcional)

A integração de Call Journal registra detalhes de chamadas em seu sistema de helpdesk, criando um histórico completo de comunicações dentro de sua plataforma de suporte.

• API Endpoint: O endpoint de REST para criar entradas de diário ou notas (por exemplo, `https://api.example-helpdesk.com/v2/contacts/{id}/notes`)
• Request Method: POST para criar novas entradas de diário
• Field Mapping: Mapeie dados de chamada (chamador, data, duração, notas) para os campos de diário do seu helpdesk
• Include Call Recording Link: Opção de incluir links para gravações de chamadas, se disponível
• Auto-Log Calls: Ativar o registro automático de todas as chamadas ou exigir seleção manual

Etapa 8: Configure a criação automática de tickets (opcional)

Configure a criação automática de tickets para gerar tickets de suporte com base em eventos de chamada específicos, garantindo que nenhuma interação com o cliente seja perdida.

Ticket Creation API Configuration:

• API Endpoint: O endpoint de REST para criar tickets (por exemplo, `https://api.example-helpdesk.com/v2/tickets`)
• Request Method: POST
• Enable Automatic Ticket Creation: Alterne para ativar este recurso
• Trigger Events: Selecione quais eventos de chamada devem disparar a criação de ticket:
  • Missed calls
  • Voicemail received
  • Call transfer completed
  • Manual ticket creation during call.

Ticket Template Configuration:

• Subject Template: Defina o formato para assuntos de tickets (por exemplo, "Call from {{contact_name}} on {{call_date}}")
• Description Template: Template para corpo de descrição do ticket
• Priority Field: Mapeie níveis de prioridade do ticket
• Category/Type Field: Atribua categorias de ticket
• Assignment Rules: Defina como os tickets são roteados (por usuário, fila, departamento)
• Custom Fields: Inclua campos personalizados obrigatórios para seu helpdesk

Etapa 9: Salve o template

Revise todas as seções de configuração para garantir a precisão e clique em Save para criar o template de integração. O template será validado contra seus endpoints da API de helpdesk antes de ser salvo.

Conecte e configure

Associe a integração com usuários

Após criar um template de integração, associe-o com usuários que se beneficiarão dos recursos de integração de helpdesk.

Navegue até Contacts & CRM > Settings > CRM Integration e:

• Selecione o template de helpdesk personalizado na lista suspensa
• Escolha quais recursos ativar para cada usuário ou grupo
• Configure autenticação por usuário se seu helpdesk exigir credenciais individuais
• Salve as configurações

Teste a conexão

Verifique se a integração está funcionando corretamente:

1. Procure por um contato em seu helpdesk utilizando a funcionalidade de pesquisa do Virtual-Call UC Client.
2. Verifique se as informações do cliente são exibidas corretamente
3. Tente uma chamada de teste para validar a funcionalidade de Call Popup
4. Verifique se os dados de chamada estão sendo registrados adequadamente em seu sistema de helpdesk

Configure os recursos de integração

Contact Synchronization

Os contatos do seu sistema de helpdesk são sincronizados no Virtual-Call UC Client, tornando as informações do cliente prontamente disponíveis durante as comunicações.

Sync Configuration:

• Navegue até Contacts & CRM > Contact Sync
• Selecione sua integração de helpdesk personalizado.
• Escolha a frequência de sincronização (tempo real, horária, diária)
• Selecione quais contatos sincronizar (todos os contatos, grupos específicos, filtrados por critérios).
• Ativar sincronização bidirecional para permitir que as atualizações fluam de volta para seu helpdesk
• Salve e inicie a sincronização

Contact Creation

Quando ativado, este recurso permite que o Virtual-Call Cloud PBX crie novos contatos em seu sistema de helpdesk diretamente de chamadas recebidas ou entrada manual.

Activation:

• Ativar Contact Creation na configuração do seu template de integração
• Configure o mapeamento de campo para definir quais informações do chamador criam quais campos de helpdesk
• Os usuários verão uma opção para criar um contato no helpdesk ao chamar um número desconhecido
• Novos contatos são imediatamente adicionados ao seu sistema de helpdesk e sincronizados de volta com o Virtual-Call UC Client

Call Popup

Call Popup exibe informações do cliente do seu helpdesk automaticamente ao receber ou fazer chamadas, fornecendo aos agentes acesso instantâneo aos dados relevantes.

Enabling Call Popup:

• Navegue até CRM > Popup Settings
• Selecione sua integração de helpdesk personalizado
• Configure os eventos de disparo do popup (chamada recebida, chamada feita ou ambas)
• Personalize as informações exibidas na janela do popup

Custom Helpdesk URL Format:

Para sistemas de helpdesk personalizados, a URL de Call Popup deve ser configurada para iniciar a página de contato ou registro do cliente de seu helpdesk. O formato da URL deve incluir um espaço reservado para o identificador de contato:

Exemplos de formatos de URL:

• https://helpdesk.example.com/contacts/{{contact_id}}
• https://crm.example.com/customer?id={{contact_id}}&view=details
• https://support.example.com/accounts/{{account_id}}/contacts/{{contact_id}}

Contact Field Configuration:

Configure quais campos de contato do seu helpdesk são exibidos no popup:

• Selecione até 8-10 campos relevantes
• Organize os campos por ordem de importância
• Escolha entre nome, e-mail, telefone, empresa, status da conta, campos personalizados
• Visualize o layout do popup antes de salvar

Call Journal

Call Journal registra automaticamente detalhes de chamadas em seu sistema de helpdesk, criando uma linha do tempo completa de comunicação para cada cliente.

Configuration Steps:

1. Ativar Call Journal em seu template de integração
2. Configure o endpoint da API para criar notas/entradas de diário
3. Defina quais informações de chamada são registradas:
   • Nome do chamador e número
   • Data e hora da chamada
   • Duração da chamada
   • Direção da chamada (entrada/saída)
   • Link de gravação de chamada (se aplicável)
   • Notas de chamada do agente
4. Defina o comportamento do registro automático (sempre registrar, solicitar ao usuário, apenas manual)
5. Salve a configuração

Durante chamadas ativas, os agentes podem opcionalmente adicionar notas incluídas na entrada de diário enviada para seu sistema de helpdesk.

Automatic Ticket Creation

Gere automaticamente tickets de suporte em seu helpdesk com base em eventos de chamada, garantindo que nenhum problema do cliente fique sem ser abordado.

Setup Process:

1. Ativar Automatic Ticket Creation em seu template de integração
2. Configure o template de ticket com formatos de assunto e descrição
3. Selecione eventos de disparo (chamadas perdidas, caixas de voz, transferências, criação manual)
4. Defina o roteamento de ticket (atribuição de fila, prioridade, categoria)
5. Teste a criação de ticket com uma chamada de teste

Ticket Template Variables:

Use essas variáveis em seus templates de ticket para preencher informações dinâmicas:

• {{caller_name}} — Nome da pessoa que está chamando
• {{caller_number}} — Número de telefone do chamador
• {{call_date}} — Data da chamada
• {{call_time}} — Hora da chamada
• {{call_duration}} — Duração da chamada em segundos
• {{answering_agent}} — Nome do agente que atendeu
• {{call_direction}} — Entrada ou Saída
• {{voicemail_transcript}} — Transcrição automática de voz (se ativada)

Exemplo de assunto de ticket: "Missed call from {{caller_name}} ({{caller_number}}) on {{call_date}}"

Exemplo de descrição de ticket: "Customer {{caller_name}} called on {{call_date}} at {{call_time}} but the call was not answered. Call duration: {{call_duration}} seconds. Please contact the customer to address their inquiry."

Solução de problemas

Call Popup não está aparecendo

Problema: O pop-up de informações do cliente não é exibido ao receber chamadas.

Soluções:

• Verifique se a API de Pesquisa de Contatos está configurada corretamente e acessível
• Verifique se o número de telefone da chamada recebida corresponde a um contato em seu sistema de helpdesk
• Confirme se os mapeamentos de campos Contact ID e Phone Number estão corretos
• Verifique o console do navegador para avisos de bloqueador de pop-up.
• Verifique se as credenciais de autenticação são válidas e não expiraram
• Teste a API de Pesquisa de Contatos diretamente utilizando uma ferramenta de cliente de REST para isolar o problema.
• Revise os registros do Cloud PABX para erros de conexão da API

Falhas de Contact Synchronization

Problema: Os contatos não estão sendo sincronizados do helpdesk com o Virtual-Call UC Client.

Soluções:

• Verifique se a URL do endpoint da Contact Search API está correta.
• Teste a autenticação da API com credenciais corretas
• Verifique se existem contatos em seu sistema de helpdesk
• Revise o mapeamento de campo para garantir que os campos obrigatórios (Contact ID, Display Name, Phone) estejam mapeados corretamente
• Verifique a conectividade de rede com o servidor da API de helpdesk
• Revise os registros do sistema para erros de sincronização e códigos de resposta da API
• Verifique se a configuração Max Concurrent Requests não é muito baixa
• Verifique os registros do sistema de helpdesk para erros de API ou limitação de taxa

Erros de autenticação

Problema: Erros “Authentication failed” ou “Unauthorized” ao acessar a API de helpdesk.

Soluções:

• Verifique se as credenciais de autenticação estão corretas e atualizadas
• Para OAuth 2.0, certifique-se de que a URL do Token e o Client ID/Secret estão corretos
• Verifique se a conta de usuário da API tem permissões apropriadas em seu sistema de helpdesk
• Verifique se os tokens de API ou senhas não expiraram
• Para Basic Auth, certifique-se de que o nome de usuário e a senha estejam codificados corretamente
• Teste a autenticação utilizando as ferramentas de teste de API do seu helpdesk
• Regenere as chaves/tokens de API em seu sistema de helpdesk e atualizar a configuração de integração.

Respostas lentas da API

Problema: Os pop-ups de chamada aparecem lentamente ou as pesquisas de contato demoram muito tempo.

Soluções:

• Reduza o número de campos de contato sendo recuperados em consultas de API
• Adicione filtros ou critérios de pesquisa à solicitação de API para reduzir conjuntos de resultados
• Verifique o desempenho do sistema de helpdesk e a eficiência de consultas de banco de dados
• Monitore a latência de rede entre Cloud PABX e API de helpdesk.
• Otimize as consultas de API (use campos indexados para buscas)
• Reduza Max Concurrent Requests se o helpdesk estiver sendo sobrecarregado
• Considere armazenar em cache dados de contato acessados com frequência localmente
• Revise os registros de API do helpdesk para consultas lentas ou problemáticas

Mapeamento de campo incorreto

Problema: As informações de contato são exibidas incorretamente ou os campos estão em branco nos popups.

Soluções:

• Revise o formato de resposta da API do seu sistema de helpdesk
• Verifique se os nomes de campos na resposta da API correspondem aos da sua configuração de mapeamento de campo
• Verifique se os tipos de dados correspondem (certifique-se de que IDs numéricos estejam mapeados corretamente)
• Teste a API de Pesquisa de Contatos com uma solicitação de exemplo utilizando sua ferramenta de teste
• Compare nomes de campos esperados com nomes de campos reais da resposta da API
• Atualize os mapeamentos de campo para utilizar caminhos de campo corretos (por exemplo, para objetos aninhados: "customer.contact_id")

Criação de ticket não funcionando

Problema: Os tickets não estão sendo criados automaticamente quando eventos de disparo ocorrem.

Soluções:

• Verifique se a Automatic Ticket Creation está ativada no template de integração
• Verifique se os eventos de disparo estão configurados corretamente
• Confirme se o endpoint da API de criação de ticket está correto e acessível
• Verifique se as credenciais de autenticação têm permissões para criar tickets
• Teste o endpoint da API de Ticket manualmente com dados de exemplo
• Revise a sintaxe das variáveis de template — certifique-se de que as variáveis estejam formatadas corretamente com {{ }}
• Verifique os registros do sistema de helpdesk para erros de criação de ticket
• Verifique se os campos de ticket obrigatórios estão sendo preenchidos pelo template

Desativar ou desconectar

Desativar temporariamente a integração

Para pausar os recursos de integração sem remover a configuração:

1. Navegue até CRM > Integrations > Helpdesk
2. Selecione seu template de integração de helpdesk personalizado
3. Clique na alternância ou caixa de seleção para desativar o template
4. Todos os recursos relacionados (Contact Popup, Sync, Journal) deixarão de funcionar imediatamente
5. Para reativar, simplesmente alterne o template de volta

Desconectar do sistema de helpdesk

Para remover completamente a integração e excluir o template:

1. Navegue até CRM > Integrations > Helpdesk
2. Encontre o template de helpdesk personalizado a ser removido.
3. Clique no botão de exclusão/remoção (normalmente um ícone de lixeira)
4. Confirme a remoção quando solicitado
5. O template de integração é excluído permanentemente, e todos os contatos sincronizados e configurações são removidos
6. Os recursos de integração são interrompidos imediatamente para todos os usuários

Removendo associações de usuários

Para desativar os recursos de integração para usuários específicos sem remover o template:

1. Navegue até CRM > User Integration Settings
2. Selecione a conta de usuário a ser modificada
3. Desmarque a integração de helpdesk personalizado
4. Clique em Salvar
5. Esse usuário não terá mais acesso aos recursos de integração, mas outros usuários mantêm o acesso.

Novo Método de Autenticação a partir da Versão 84.23.0.24

Suporte a OAuth2 PKCE

Os modelos de integração CRM/Helpdesk personalizados agora suportam o método de autenticação Authorization Code Flow with Proof Key for Code Exchange (PKCE). Este método utiliza um par challenge-verifier em vez de um client secret, melhorando assim a segurança da autenticação OAuth 2.0.