Integração do CRM HubSpot

Introdução

O 3CX oferece integração com o HubSpot por meio da API do 3CX para CRM, com os seguintes recursos:

• Identificação de Chamadas para Nome do Contato – as chamadas recebidas acionam uma pesquisa de contato no HubSpot.
• Pesquisa de Contatos no HubSpot com base em Nome, Número ou E-mail, caso você pesquise um nome no Cliente Web 3CX.
• Registro de Chamadas e Chats – as chamadas e os chats são registrados no Cartão de Contato do HubSpot como registros de chamadas do CRM.
• Crie um novo contato no HubSpot a partir do cliente 3CX para chamadas provenientes de novos números.
• Clique para Ligar – faça chamadas diretamente do HubSpot pelo 3CX, usando as extensões de Navegador 3CX Click2Call para Google Chrome e Microsoft Edge.

Configurar o HubSpot CRM com a CLI do HubSpot

A HubSpot descontinuou a criação de novos aplicativos públicos legados pela interface da Plataforma de Desenvolvedores. Agora, os novos aplicativos da HubSpot devem ser criados usando a estrutura de Projetos da HubSpot e a CLI da HubSpot.

Este guia explica como criar o aplicativo OAuth da HubSpot necessário para a integração do 3CX com o CRM da HubSpot.

Observação: os Aplicativos Públicos legados existentes continuam funcionando.

Etapa 1: Determinar a URL de Redirecionamento OAuth do 3CX

Antes de criar o projeto no HubSpot, determine a URL pública usada para acessar o sistema 3CX.

Por exemplo, se o Console de Admin 3CX for acessado por meio de:

https://mypbx.3cx-example.com

...nesse caso, a URL de redirecionamento do OAuth da HubSpot deve ser:

https://mypbx.3cx-example.com/api/oauth2crm

Etapa 2: Instalar a CLI do HubSpot

A CLI do HubSpot é um aplicativo Node.js, portanto o Node.js com npm deve primeiro ser instalado.

O HubSpot CLI 8 requer o Node.js 20 ou uma versão posterior.

• Abra um novo Prompt de Comando.
• No Prompt de Comando, execute:

npm install -g @hubspot/cli@latest



• Quando a instalação for concluída, verifique a versão da CLI do HubSpot:

hs --version



• Deve ser exibida uma versão da CLI do HubSpot.

Etapa 3: Faça Login no HubSpot pela CLI

• No Prompt de Comando, execute:

hs account auth

A CLI irá orientá-lo durante o processo de autenticação da sua conta do HubSpot. Siga as instruções:

• Atribua à conta da HubSpot um nome local que seja fácil de reconhecer, se solicitado.
• Uma janela do navegador será aberta, ou a CLI exibirá instruções para abrir o HubSpot.
• Faça login na conta da HubSpot na qual o projeto/aplicativo será criado.

• Gere a Chave de Acesso Pessoal solicitada.
• A chave deve ser exibida automaticamente na janela do terminal.

• Se a CLI solicitar que você cole a Chave de Acesso Pessoal no terminal, cole-a e pressione Enter.

• Digite um nome de conta, se solicitado.
• Se for perguntado se essa deve ser a conta padrão, selecione “Sim”.

Etapa 4: Criar o Projeto OAuth do HubSpot

• No Prompt de Comando

• Crie uma pasta para o projeto, por exemplo:

mkdir C:\HubSpotProjects

cd /d C:\HubSpotProjects



• Nesta pasta, execute:

hs project create --project-base app --distribution private --auth oauth



• A CLI solicitará informações adicionais.

• Nome do projeto, exemplo: “Integração do 3CX com o HubSpot”
• Pasta local, padrão ou use algo simples, como: “3cx-hubspot”
• Recursos

• A integração do 3CX com o CRM, por si só, não requer um App Card do HubSpot, webhook, ação de fluxo de trabalho, página de configurações ou qualquer outro recurso do projeto. Se a CLI solicitar que você escolha recursos, deixe todos os recursos desmarcados e continue pressionando Enter.

• Após a conclusão do comando, deve haver um novo diretório, por exemplo: “C:\HubSpotProjects\3cx-hubspot”
• Vá para esse diretório:

cd /d C:\HubSpotProjects\3cx-hubspot



• Os arquivos importantes devem incluir:

C:\HubSpotProjects\3cx-hubspot\hsproject.json

C:\HubSpotProjects\3cx-hubspot\src\app\app-hsmeta.json

Etapa 5: Configurar o OAuth e os Escopos Necessários para o 3CX

Abra o seguinte arquivo no Bloco de Notas: "C:\HubSpotProjects\3cx-hubspot\src\app\app-hsmeta.json".

O arquivo gerado pode conter propriedades adicionais que podem ser ignoradas; a seção importante é a config do aplicativo e, em especial, a seção auth.

Configure o aplicativo com sua distribution, requiredScopes e redirectUrls conforme mostrado abaixo, substituindo "https://pabx.example.com/api/oauth2crm" pela URL pública real do 3CX determinada na Etapa 1.

{

  "uid": "3CXHubSpotIntegration_app",

  "type": "app",

  "config": {

    "description": "OAuth application for the 3CX HubSpot CRM integration",

    "name": "3CX HubSpot Integration-App",

    "distribution": "private",

    "auth": {

      "type": "oauth",

      "redirectUrls": [

        "https://pbx.example.com/api/oauth2crm"

      ],

      "requiredScopes": [

      "oath",

           "crm.objects.contacts.read",

                "crm.objects.contacts.write",

                "crm.objects.companies.read",

                "crm.objects.owners.read",

                "timeline"

      ],

      "optionalScopes": [],

      "conditionallyRequiredScopes": []

    },

    "permittedUrls": {

      "fetch": [

        "https://api.hubapi.com"

      ],

      "iframe": [],

      "img": []

    },

    "support": {

      "supportEmail": "[email protected]",

      "documentationUrl": "https://example.com/docs",

      "supportUrl": "https://example.com/support",

      "supportPhone": "+18005555555"

    }

  }

}

Etapa 6: Validar e Enviar o Projeto para o HubSpot

• No diretório do projeto, execute:

hs project validate



• Se a validação for bem-sucedida, continue.

• Se a validação indicar um erro, corrija a propriedade JSON indicada e execute o comando novamente.

• Em seguida, execute:

hs project upload



1. Na primeira vez em que o projeto for enviado, o HubSpot poderá exibir uma mensagem semelhante a esta:

2. "O projeto não existe nesta conta. Deseja criá-lo?"

1. Responda “Y” e continue.

3. A CLI irá:

1. fazer o upload dos arquivos
2. criar uma build do HubSpot
3. implantar o aplicativo

Etapa 7: Obter o ID do Cliente e o Segredo do Cliente no HubSpot

• No seu navegador, faça login na sua conta do HubSpot e acesse Desenvolvimento > Projetos
• Abra a integração do 3CX com o HubSpot (ou o nome do projeto que você criou).
• Em “Componentes do Projeto”, clique no nome do aplicativo.
• Abra a guia “Auth”.

• O HubSpot exibirá as seguintes credenciais do cliente:

• ID do cliente
• Segredo do cliente

• Anote os dois valores em um local seguro.

Etapa 8: Adicionar Contas Adicionais do HubSpot CRM ao Aplicativo OAuth Privado (Opcional)

Este é um novo passo importante em comparação com o antigo procedimento de Aplicativos Públicos.

Como o projeto foi criado com “distribution”: “private”, o HubSpot permite autorização apenas via OAuth para contas explicitamente aprovadas. Por padrão, apenas a conta que criou o App tem acesso (“private”).

No HubSpot:

• Desenvolvimento Aberto.
• Projetos em andamento.
• Abra o projeto 3CX.
• Em “Componentes do Projeto”, selecione o aplicativo 3CX.

• Abra a guia “Distribuição”.

• Clique em “Adicionar conta(s) aprovada(s)”.
• Entre as contas de produção disponíveis, selecione a conta do HubSpot CRM que contém os contatos e as empresas que serão integrados ao 3CX.

• Se o seu login no HubSpot tiver acesso tanto a uma conta de desenvolvimento quanto à conta normal de CRM da empresa, certifique-se de que a conta de CRM que contém os dados reais dos clientes esteja aprovada.

• Clique em Salvar alterações.

Configure e Autorize o HubSpot no 3CX

• No Console de Admin 3CX, acesse “Integrações” > “CRM”.
• Selecione “HubSpot” na lista suspensa.
• Selecione a ordem de pesquisa de contatos desejada
• Insira os valores do OAuth copiados anteriormente do seu aplicativo nos campos “ID do Cliente” e “Segredo do Cliente”.
• Clique em “Salvar”
• Clique em “Autorizar”

• Uma página de autorização da HubSpot deve ser exibida.

• Faça login no HubSpot, se necessário.
• Selecione a conta do HubSpot CRM que contém os contatos e as empresas que devem ser utilizados pelo 3CX.
• Verifique as permissões solicitadas.
• O HubSpot pode exibir um aviso informando que o aplicativo não foi verificado. Isso é esperado para um aplicativo criado para sua própria conta e que não foi enviado ao HubSpot Marketplace.
• Confirme a instalação/autorização.

• O 3CX agora recebe o código de autorização OAuth e o troca por tokens OAuth do HubSpot.
• Verifique se o campo “Token de atualização” é preenchido automaticamente para o HubSpot CRM no Console de Admin 3CX.
• Se você deseja habilitar a criação de contatos a partir do cliente 3CX, marque esta opção. Quando o número do chamador não puder ser associado a um contato, o cliente 3CX permitirá que o usuário crie o contato preenchendo os detalhes em uma caixa de diálogo.

Configurar Contatos E164 e Identificador de Chamadas

• Para que haja uma correspondência com o HubSpot, o Identificador de Chamadas recebido deve ser idêntico ao registro no CRM, incluindo qualquer prefixo, pois o HubSpot realiza consultas com o número completo. Consultar o HubSpot usando apenas uma parte dos dígitos não retorna nenhum dado.
• Para que a integração com o HubSpot funcione, você deve armazenar os números no HubSpot no formato E164, e seu Tronco SIP também deve fornecer o número do chamador no formato E164, para que ambos coincidam. Caso isso não ocorra, você pode usar a Reformatação do Identificador de Chamadas para ajustar o número do chamador antes que ele seja encaminhado para o CRM.
• Agora vá em Sistema > Lista Telefônica > Opções, defina a estratégia de correspondência como “Correspondência exata” e clique em “OK”.

Configurar o Registro de Chamadas e Chats, Incluindo Transcrição

• Para reportar chamadas e conversas externas ao HubSpot, o endereço de e-mail configurado para o ramal do 3CX deve corresponder ao endereço de e-mail de um usuário do HubSpot. Dessa forma, o 3CX pode associar o ramal do 3CX que recebe a chamada ou a conversa ao usuário do HubSpot.
• Marque a opção “Ativar registro de chamadas” para relatar chamadas externas ao CRM e configure estes parâmetros de “Registro de chamadas”:

• Assunto da Chamada — o assunto da chamada.
• Chamada Recebida Atendida — descrição para chamadas recebidas atendidas.
• Chamada Perdida - descrição das chamadas perdidas.
• Chamada Efetuada Atendida — descrição das chamadas efetuadas atendidas.
• Chamada Efetuada Não Atendida — descrição das chamadas efetuadas não atendidas.

• Observação: é possível usar variáveis nos parâmetros do “Registro de Chamadas”, indicadas como
  [nome_da_variável]
  ; por exemplo, o número externo é especificado como
  [Número]
  . As variáveis disponíveis para uso estão listadas aqui.

• Se você quiser registrar as conversas no CRM, marque a caixa de seleção “Ativar registro de conversas” e configure os parâmetros abaixo:

• Assunto do Chat — o assunto da sessão de chat.

• Observação: é possível usar variáveis nos parâmetros do “Chat Journaling”, indicadas como
  [nome_da_variável]
  ; por exemplo, o número externo é especificado como
  [Número]
  . As variáveis disponíveis para uso estão listadas aqui.

Veja também

• Veja como integrar seu CRM com a API do 3CX.
• Saiba como configurar a integração Bitrix24.
• Saiba como configurar a integração ConnectWise.
• Saiba como configurar a Integração Microsoft 365.
• Saiba como configurar a integração Jetpack CRM.
• Saiba como configurar a integração Salesforce.
• Saiba como configurar a integração Zoho.

Última atualização

Este documento foi atualizado pela última vez em 21 de agosto de 2026

https://www.3cx.com.br/docs/integracao-crm-hubspot-pabx/