Integração com CRM personalizado

A integração Custom CRM da Virtual-Call Cloud PABX fornece uma solução flexível para conectar qualquer sistema de Gerenciamento de Relacionamento com Cliente que suporte REST API. Diferentemente das integrações pré-construídas, a integração Custom CRM permite que você defina exatamente os pontos de extremidade da API, métodos de autenticação e mapeamentos de dados necessários pela sua plataforma CRM específica. Isso oferece à sua organização controle total sobre como os dados de chamadas, informações de contatos e interações com clientes são sincronizados entre sua central e seu sistema CRM.

Visão geral

A integração Custom CRM funciona criando templates reutilizáveis que definem como sua Virtual-Call Cloud PBX se comunica com a REST API do seu CRM. Cada template especifica:

• Método de autenticação — Como a central autentica com seu CRM (Basic Auth, OAuth 2.0, Bearer Token ou Nenhum)
• Configuração de busca de contatos — Ponto de extremidade da API e mapeamentos de campos para procurar contatos durante chamadas
• Criação de contato/lead — Ponto de extremidade opcional para criar novos contatos ou leads da central
• Registro de diário de chamadas — Ponto de extremidade opcional para registrar atividades de chamadas e resultados em seu CRM

Depois que um template é criado, você pode atribuí-lo a usuários ou ramais específicos e configurar como ele se integra aos recursos de sua central, como pop-ups de chamadas, sincronização de contatos e registro de diário de chamadas.

Pré-requisitos

Criar um template de integração

Os templates de integração definem a configuração de API e mapeamentos de dados para seu CRM personalizado. Conclua os seguintes passos para criar seu primeiro template:

Passo 1: Navegue até Custom CRM

1. Faça login no console de administrador de sua Virtual-Call Cloud PABX
2. Vá para Integrations > CRM
3. Na lista de integrações CRM, localize e clique em Custom

Passo 2: Crie um novo template

1. Clique no botão Add para criar um novo template CRM personalizado
2. Um formulário de configuração com várias seções aparecerá

Passo 3: Configure configurações gerais

Na seção General, digite as seguintes informações:

• Template Name — Um nome descritivo para esta integração (por exemplo, “Salesforce Production” ou "HubSpot CRM")
• Logo URL — Opcional. A URL para uma imagem de logotipo que representa seu CRM. Este logotipo aparece na interface da central quando este template é selecionado.
• Max Concurrent Requests — O número máximo de solicitações de API simultâneas que a central enviará para seu CRM. O valor recomendado é entre 5-20 dependendo dos limites de taxa da API do seu CRM. Comece com 10 se não tiver certeza.

Passo 4: Configure autenticação

A seção Autenticação define como sua central se autentica com sua API CRM. Selecione o método que corresponde aos requisitos da API do seu CRM:

• None — Nenhuma autenticação necessária. Use apenas se sua API CRM for acessível publicamente sem credenciais (incomum)
• Basic Authentication — Credenciais de nome de usuário e senha. Digite seu nome de usuário e senha da API CRM
• OAuth 2.0 — Autenticação baseada em token. Você precisará:
  • Obter autorização do seu CRM usando seus pontos de extremidade OAuth 2.0
  • Digitar o token de acesso e o token de atualização fornecidos pelo seu CRM
  • Especificar a URL de atualização de token para que a central possa atualizar automaticamente tokens expirados
• Bearer Token — Chave de API ou token de acesso fornecido pelo seu CRM. Digite o valor do token diretamente

Passo 5: Configure busca de contatos (obrigatório)

A configuração de busca de contatos é obrigatória para que todos os outros recursos de integração funcionem. Ela define como a central consulta seu CRM para procurar informações de contatos durante chamadas.

API Endpoint URL: Digite o ponto de extremidade REST API do seu CRM que realiza a busca de contatos. Isso normalmente se parece com:

• https://your-crm.com/api/v1/contacts/search
• https://api.salesforce.com/services/data/v57.0/sobjects/Contact
• https://api.hubapi.com/crm/v3/objects/contacts/search

Mapeamento de Campos para Busca de Contatos: Defina quais campos seu CRM usa para buscar e quais campos a central deve extrair da resposta:

• Search Field (CRM) — O nome do campo em seu CRM que será pesquisado (geralmente um campo de número de telefone). Por exemplo: phone, phoneNumber ou mobile_phone
• Match Field (PBX) — Qual campo de número de telefone da chamada deve ser utilizado para buscar: caller (ID do chamador de entrada), called (número discado) ou both (buscar ambos)

• Result Field Mapping — Defina quais informações devem ser extraídas da resposta do CRM e como aparecem na central:

  • contact_id — Identificador exclusivo do contato em seu CRM
  • contact_name — Nome de exibição do contato
  • contact_phone — Número de telefone a exibir
  • contact_email — Endereço de e-mail (para popup de chamada ou registro)
  • contact_company — Nome da empresa
  • contact_department — Departamento ou unidade de negócios
  • contact_notes — Notas adicionais ou descrição

  Para cada campo, especifique o caminho JSON exato para o valor correspondente na resposta da API do seu CRM

{
  "id": "12345",
  "fullName": "John Smith",
  "workPhone": "+1-555-0100",
  "email": "john@company.com",
  "company": "Acme Corp"
}

Passo 6: Configure criação de contato/Lead (opcional)

Se sua organização cria novos contatos ou leads em seu CRM de chamadas de entrada, ative e configure esta seção:

• Enable Contact Creation — Alterne para ativar este recurso
• API Endpoint URL — O ponto de extremidade REST API para criar novos contatos em seu CRM. Por exemplo: https://api.hubapi.com/crm/v3/objects/contacts

• Field Mapping for New Contacts — Defina quais campos do CRM devem ser preenchidos ao criar um novo contato:

  • phone — Número de telefone da chamada
  • firstName, lastName — Campos de nome do contato
  • email — Endereço de e-mail (se disponível)
  • company — Nome da empresa (se disponível)
  • source — De onde o contato veio (por exemplo, "PABX")
  • callDate, callDuration — Metadados de chamada

  Mapeie esses campos da central para os nomes de campo exatos do seu CRM

Passo 7: Configure o diário de chamadas (opcional)

O registro de diário de chamadas registra os detalhes de cada chamada em seu CRM para um histórico completo de interações com clientes. Ative esta seção se seu CRM suportar atividade ou registro de chamadas:

• Enable Call Journal — Alterne para ativar registro de chamadas
• API Endpoint URL — O ponto de extremidade REST API para criar registros de chamadas ou atividades em seu CRM. Por exemplo: https://api.hubapi.com/crm/v3/objects/calls

• Field Mapping for Call Data — Defina quais informações de chamada devem ser registradas em seu CRM:

  • contact_id — O identificador de contato exclusivo para associar à chamada
  • call_direction — Direção da chamada: recebida ou realizada
  • call_type — Tipo de chamada: recebida, realizada, perdida ou correio de voz
  • duration — Duração da chamada em segundos
  • start_time — Quando a chamada começou (timestamp Unix ou formato ISO)
  • from_number — Número de telefone da parte que chama
  • to_number — Número de telefone da parte chamada
  • recording_url — URL para a gravação da chamada (se aplicável)
  • notes — Notas de chamada ou descrição

  Mapeie esses para os campos de atividade do seu CRM

Passo 8: Salve e teste o template

1. Clique em Save para criar o template
2. O template está agora disponível para atribuição a usuários e ramais
3. Após atribuir o template aos usuários, teste a integração fazendo uma chamada de teste e verificando:
   • Informações de contato aparecem no pop-up de chamada (se ativado).
   • Novos contatos podem ser criados de chamadas perdidas (se ativado).
   • Detalhes de chamada são registrados em seu CRM (se ativado)

Conecte e configure

Atribua o template Custom CRM aos usuários

Após criar um template, você deve atribuí-lo a usuários ou ramais específicos para que a integração funcione:

1. Vá para Integrations > CRM
2. Selecione seu template CRM personalizado na lista
3. Na seção Associated Users/Extensions, clique em Add para atribuir o template
4. Selecione quais usuários ou ramais devem usar esta integração CRM
5. Clique em Save

Verifique as configurações de autenticação

Algumas integrações de CRM exigem reautenticação periódica ou atualização de credenciais. Verifique se:

• Suas credenciais de autenticação estão corretas e ativas em seu CRM
• Chaves de API ou tokens não expiraram
• Tokens de atualização OAuth 2.0 estão devidamente configurados se usando autenticação baseada em token

Configure recursos de integração

Sincronização de contatos

A sincronização de contatos mantém as informações de contato em seu Virtual-Call UC Client sincronizadas com seu CRM. Este recurso habilita:

• Busca automática de contatos — Quando uma chamada chega, a central consulta automaticamente seu CRM para encontrar informações de contato correspondentes
• Exibir informações do chamador — Nome do contato, empresa e outros detalhes aparecem em seu UC Client durante a chamada
• Rotulação de contatos — Contatos do seu CRM são rotulados com a fonte do CRM para fácil identificação

Para ativar a sincronização de contatos:

1. Vá para Integrations > CRM
2. Selecione seu template CRM personalizado
3. Localize a seção Contact Synchronization e alterne Enable
4. Verifique se a configuração Contact Search está devidamente configurada (necessária para sincronização)
5. Clique em Save

Criação de contato/lead

O recurso de criação de contato permite que usuários criem novos contatos ou leads em seu CRM diretamente do Virtual-Call UC Client quando encontram um novo chamador:

1. Vá para Integrations > CRM
2. Selecione seu template CRM personalizado
3. Na seção Contact Creation, verifique se:
   • Enable Contact Creation está ativado
   • A URL do ponto de extremidade da API está corretamente configurada
   • O mapeamento de campos inclui pelo menos os campos de número de telefone e nome
4. Clique em Save

Após ativado, usuários verão uma opção “Create Contact” em seu UC Client ao visualizar chamadas de contatos desconhecidos.

Popup de chamada

Pop-ups de chamada exibem informações do cliente na tela quando uma chamada de entrada chega. A integração Custom CRM suporta dois modos de popup de chamada:

Modo 1: Popup com Resultados de Busca de Contatos

Este modo utiliza a configuração de busca de contatos para procurar automaticamente informações de contato de seu CRM e exibi-las em uma janela pop-up.

1. Vá para Integrations > CRM
2. Selecione seu template CRM personalizado
3. Na seção Call Popup, selecione Enable Call Popup
4. Escolha o evento de disparo do popup:
   • When incoming call arrives — Popup aparece imediatamente para chamadas de entrada
   • When answering call — Popup aparece após você atender a chamada
   • Always Query CRM — Atualiza continuamente informações de contato durante a chamada
5. Verifique se a configuração de busca de contatos está devidamente configurada
6. Clique em Save

Modo 2: Popup HTML Personalizado com String de Formato URL

Para personalização avançada, você pode definir um formato de URL personalizado que abre seu CRM para um registro de cliente específico quando uma chamada chega:

1. Vá para Integrations > CRM
2. Selecione seu template CRM personalizado
3. Na seção Call Popup, selecione Enable Custom URL Popup
4. Digite o Popup URL Format. Deve ser um template de URL que inclua placeholders para informações de chamada:
   • {caller_id} — Número de telefone da parte que chama
   • {contact_id} — ID de contato do CRM (se encontrado pela busca de contatos)
   • {contact_name} — Nome do contato (se encontrado)
   • {company} — Nome da empresa (se encontrado)
5. Exemplos de formatos de URL:
   • https://salesforce.com/lightning/r/Contact/{contact_id}/view
   • https://hubspot.com/contacts/{contact_id}
   • https://your-crm.com/search?phone={caller_id}
6. Clique em Save

Diário de chamadas

O registro de diário de chamadas registra automaticamente todos os detalhes de chamada em seu CRM para histórico completo de interações com clientes:

1. Vá para Integrations > CRM
2. Selecione seu template CRM personalizado
3. Na seção Call Journal, alterne Enable Call Journal
4. Verifique se a URL do ponto de extremidade da API e os mapeamentos de campos estão corretamente configurados.
5. Selecione quais tipos de chamada devem ser registrados:
   • Chamadas atendidas
   • Chamadas perdidas
   • Mensagens de correio de voz
6. Opcionalmente, ative Include Call Recording para anexar URLs de gravação aos registros de diário de chamadas.
7. Clique em Save

Depois que as chamadas são registradas, você pode revisar a atividade de chamada em seu CRM navegando até o registro de contato. O diário de chamadas fornece um rastro de auditoria completo de todas as interações com clientes.

Editar e gerenciar templates

Para modificar um template CRM personalizado existente após sua criação:

1. Vá para Integrations > CRM
2. Localize seu template CRM personalizado na lista
3. Clique no ícone Edit (lápis) ao lado do nome do template
4. Atualize quaisquer configurações, como pontos de extremidade de API, mapeamentos de campos ou credenciais de autenticação
5. Clique em Save para aplicar as alterações

As alterações aos templates entram em vigor imediatamente para todos os usuários atribuídos.

Solução de problemas

Busca de contatos não retorna resultados

Problema: Pop-ups de chamada não estão aparecendo ou informações de contato não estão sendo exibidas durante chamadas.

Soluções:

• Verifique se a URL do ponto de extremidade da API de busca de contatos está correta e acessível de sua central
• Teste o ponto de extremidade da API manualmente usando uma ferramenta como Postman ou curl para garantir que retorna dados de contato no formato JSON esperado
• Verifique se o mapeamento de campos está correto — o caminho JSON deve corresponder à estrutura real da resposta da API do seu CRM
• Verifique se o número de telefone em seu CRM corresponde ao formato do número de chamada (alguns CRMs exigem números com códigos de país como +1-555-0100, enquanto outros utilizam formato de 10 dígitos).
• Garanta que a autenticação está funcionando corretamente, verificando se suas credenciais são válidas e se o token não expirou.
• Verifique os logs da central (Administration > System > Logs) para erros da API ou mensagens de timeout

Falhas de autenticação

Problema: Chamadas da API falham com erros 401 (Não Autorizado) ou 403 (Proibido).

Soluções:

• Verifique se suas credenciais de autenticação (nome de usuário, senha, chave de API ou token) estão corretas e não expiraram.
• Para integrações OAuth 2.0, garanta que o token de acesso seja válido. Se expirado, o token de atualização deve ser utilizado para obter um novo token de acesso.
• Verifique a documentação da API do seu CRM para confirmar o formato correto do cabeçalho de autenticação exigido pelo seu CRM
• Verifique se a conta do usuário da API tem as permissões necessárias para executar operações de busca, criação e registro de chamadas de contatos
• Alguns CRMs exigem lista de permissões de IP — confirme que o endereço IP de sua central está autorizado a acessar a API
• Teste o ponto de extremidade da API com as mesmas credenciais usando uma ferramenta como Postman para isolar se o problema está na configuração da central ou na API do CRM.

Criação de contato não funciona

Problema: Novos contatos não podem ser criados no UC Client ou chamadas perdidas não estão sendo registradas como novos contatos.

Soluções:

• Verifique se a URL do ponto de extremidade da API de criação de contatos está correta
• Verifique se o mapeamento de campos inclui os campos obrigatórios para seu CRM (no mínimo, o campo de número de telefone deve ser mapeado)
• Garanta que a conta do usuário da API tenha permissões de "Criar Contato" ou "Criar Lead" em seu CRM
• Revise a documentação da API do seu CRM para confirmar os campos obrigatórios e opcionais para criação de contatos
• Teste o ponto de extremidade manualmente enviando uma solicitação POST com dados de contato de amostra para verificar se funciona
• Verifique os logs da central para mensagens de erro relacionadas a falhas na criação de contatos

Registros de diário de chamadas não aparecem

Problema: Detalhes de chamada não estão sendo registrados em seu CRM após as chamadas serem concluídas.

Soluções:

• Verifique se o registro de diário de chamadas está ativado nas configurações de integração do CRM
• Verifique se a URL do ponto de extremidade da API do diário de chamadas está correta e acessível
• Garanta que os mapeamentos de campos para dados de chamada estejam corretos e correspondam aos nomes dos campos de atividade do seu CRM
• Verifique se a busca de contatos (Contact Search) está funcionando corretamente — o registro de diário de chamadas normalmente exige um contact_id válido para vincular a atividade de chamada a um contato
• Verifique as permissões do seu CRM para garantir que o usuário da API pode criar registros de atividade ou chamada
• Revise os logs da central (Administration > System > Logs) para falhas de API ou erros de timeout durante o registro de chamadas
• Alguns CRMs têm pontos de extremidade de API diferentes para tipos de atividade diferentes — verifique se está usando o ponto de extremidade correto para registro de chamadas

Janela Popup não abre

Problema: Pop-ups de URL personalizada não estão aparecendo quando as chamadas chegam.

Soluções:

• Verifique se seu navegador da web tem bloqueio de pop-up habilitado. Adicione seu domínio CRM à lista de permissões de pop-up do navegador.
• Verifique se o Popup URL Format está corretamente formatado com os placeholders apropriados ({caller_id}, {contact_id}, etc.)
• Teste o formato de URL construindo manualmente uma URL com dados de amostra e visitando-a em seu navegador
• Garanta que o site do CRM suporte ser aberto em uma janela separada (algumas aplicações bloqueiam framing ou popups por razões de segurança)
• Verifique se a URL não contém caracteres especiais ou espaços que possam torná-la malformada
• Algumas plataformas CRM têm bloqueio de iframe habilitado — verifique se seu CRM permite pop-ups externos.

Limite de taxa de API excedido

Problema: Você está recebendo erros de limite de taxa (HTTP 429) de sua API CRM.

Soluções:

• Reduza a configuração Max Concurrent Requests nas configurações gerais do template. Reduza este valor se seu CRM tiver limites de taxa rigorosos (tente 5 em vez de 20)
• Revise a documentação da API do seu CRM para políticas e cotas de limite de taxa
• Contate seu provedor CRM para solicitar uma cota de limite de taxa mais alta, se necessário
• Desative recursos que não são necessários (como "Always Query CRM" durante a chamada) para reduzir a frequência de chamadas de API
• Verifique se seu CRM oferece pontos de extremidade de API em lote que permitem consultar múltiplos contatos em uma única solicitação, que pode ser mais eficiente

Desativar ou desconectar

Desativar temporariamente a integração para usuários específicos

Para interromper a integração CRM para certos usuários enquanto mantém o template configurado:

1. Vá para Integrations > CRM
2. Selecione seu template CRM personalizado
3. Na seção Associated Users/Extensions, localize os usuários que deseja remover
4. Clique no botão Remove ao lado de cada usuário ou ramal
5. Clique em Save

O template permanece salvo e pode ser reatribuído aos usuários a qualquer momento.

Deletar um template

Para remover permanentemente um template CRM personalizado:

1. Vá para Integrations > CRM
2. Localize o template que deseja deletar
3. Clique no ícone Delete (lixeira) ao lado do nome do template
4. Confirme a exclusão quando solicitado

Desativar a Integração Custom CRM Inteira

Para desligar toda a funcionalidade CRM personalizada em sua central:

1. Vá para Integrations > CRM
2. Localize a seção Custom CRM
3. Alterne Enable Custom CRM para desligado
4. Clique em Save

Todos os recursos de busca de contatos, pop-ups de chamada, criação de contatos e registro de diário de chamadas serão desativados. Templates e dados de configuração são retidos e podem ser reativados a qualquer momento.

Melhores práticas

• Teste completamente antes da implantação — Primeiro, configure um template de teste com uma instância CRM de não-produção para verificar se todos os pontos de extremidade de API e mapeamentos de campos funcionam corretamente antes de lançar para usuários finais.
• Documente seus pontos de extremidade de API — Mantenha notas detalhadas sobre quais pontos de extremidade de CRM você está usando e como os campos são mapeados. Isso ajudará na solução de problemas e futuras atualizações
• Monitore limites de taxa de API — Comece com configurações conservadoras de Max Concurrent Requests e aumente gradualmente se necessário enquanto monitora erros de limite de taxa
• Atualize regularmente tokens OAuth — Se usando OAuth 2.0, verifique se tokens de atualização estão devidamente configurados e teste periodicamente para garantir que tokens não expirem inesperadamente
• Utilize busca de contatos para todos os recursos — Garanta que a busca de contatos esteja devidamente configurada antes de ativar pop-ups de chamada ou diário de chamadas, pois esses recursos dependem de buscas de contatos bem-sucedidas.
• Teste com números de telefone reais — Verifique se os números de telefone em seu CRM correspondem ao formato utilizado pela sua central (alguns sistemas utilizam formato internacional +1-555-0100 enquanto outros utilizam formato de 10 dígitos 555-0100).
• Proteja credenciais de API — Nunca compartilhe chaves de API, tokens ou senhas. Trate-os com o mesmo nível de segurança que as senhas de usuário
• Revise dados do diário de chamadas — Verifique periodicamente se as chamadas estão sendo registradas corretamente em seu CRM para garantir qualidade e completude dos dados.
• Mantenha templates atualizados — Se seu CRM atualizar seus pontos de extremidade de API ou adicionar novos recursos, atualize seus templates CRM personalizados de acordo.

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.