Transcrição no HubSpot: Caminhos de Integração Verificados

O caminho mais rápido para ter transcrições de chamadas no HubSpot depende de onde suas chamadas se originam. Se sua equipe faz ligações pela ferramenta de chamadas nativa do HubSpot, pelo Zoom ou pelo Google Meet, a Conversation Intelligence integrada do HubSpot cuida da transcrição automaticamente nos planos Professional e Enterprise. Se você usa um discador externo, recebe chamadas de entrada em uma plataforma de terceiros ou quer importar gravações do Gong, do Zoom Cloud ou de um bucket S3, será preciso enviar as transcrições via Calls API por conta própria.

Este guia cobre os dois caminhos.

Quando a Conversation Intelligence Nativa É Suficiente

O HubSpot Sales Hub Professional (US$ 90 por usuário por mês, faturado anualmente) inclui a Conversation Intelligence, que oferece até 1.500 horas de transcrição por conta por mês. As chamadas são transcritas automaticamente quando feitas por meio de:

• Ferramenta de chamadas integrada do HubSpot
• Integração nativa com o Zoom (gravações de reuniões sincronizam automaticamente)
• Google Meet (Professional e Enterprise)
• Alguns provedores de chamadas de terceiros listados no marketplace do HubSpot

Nesses cenários, você obtém transcrições anexadas à linha do tempo do contato sem escrever uma linha de código. O gestor abre um contato, rola o feed de atividades e lê ou pesquisa a transcrição logo após a chamada.

As limitações: a CI exige um assento pago no Sales ou Service Hub por usuário, não transcreve chamadas de discadores fora da lista de suportados e não consegue processar gravações que você envia manualmente de um sistema de arquivos.

Minha opinião: se toda a sua equipe já usa o discador do HubSpot ou o Zoom pelo HubSpot, a CI nativa é a escolha óbvia. O caminho via API abaixo é para os casos que caem nessas lacunas.

Quando Você Precisa do Caminho via API

A receita via API cobre:

1. Chamadas gravadas fora do HubSpot (exportações do Gong, Zoom Cloud autônomo, discadores externos, gravações presenciais).
2. Importação em massa de gravações históricas.
3. Idiomas ou quantidades de falantes em que você quer controlar o motor de transcrição.
4. Equipes que não podem arcar com o preço por usuário do Sales Hub Professional para cada vendedor.

O fluxo de trabalho é direto:

1. O vendedor grava uma chamada (Zoom autônomo, discador externo, áudio enviado).
2. A gravação chega a um armazenamento acessível (S3, Cloudflare R2, Google Drive).
3. Seu sistema envia o arquivo para uma API de transcrição.
4. Ao concluir, um webhook dispara para o seu handler.
5. O handler associa a chamada a um contato e a um negócio no HubSpot.
6. A transcrição é anexada como um Call Engagement do HubSpot na linha do tempo do contato.
7. Opcionalmente, propriedades do negócio são atualizadas com sinais extraídos (próximos passos, sentimento, objeções).

Cerca de 200 linhas de código. A maioria das equipes de revenue ops coloca isso rodando no mesmo dia.

Passo 1: Configuração do App Privado no HubSpot

No HubSpot: Configurações, Integrações, Apps Privados, Criar app privado.

Dê a ele o nome "Integração de Transcrição" e solicite estes escopos:

• crm.objects.contacts.read
• crm.objects.contacts.write
• crm.objects.deals.read
• crm.objects.deals.write
• crm.objects.calls.write
• crm.schemas.calls.read

Salve o token de acesso e defina-o como HUBSPOT_TOKEN no seu ambiente.

Passo 2: Receber o Webhook de Transcrição

O handler que dispara quando a transcrição é concluída. Veja webhook vs polling para transcrições para entender as vantagens e desvantagens.

import express from 'express';
import { Client as HubSpotClient } from '@hubspot/api-client';
import crypto from 'crypto';

const app = express();
const hubspot = new HubSpotClient({ accessToken: process.env.HUBSPOT_TOKEN });

app.post(
  '/webhooks/transcript',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const sig = req.header('X-CATT-Signature');
    const expected = crypto
      .createHmac('sha256', process.env.TRANSCRIPT_WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
      return res.status(401).send('Bad signature');
    }

    const event = JSON.parse(req.body.toString());
    if (event.event !== 'job.completed') return res.sendStatus(200);

    await processCompletedTranscription(event.data);
    res.sendStatus(200);
  }
);

Transcrição concluída pronta para ser vinculada a um contato ou negócio no CRM.

Passo 3: Associar a Chamada a um Contato do HubSpot

A correspondência de contatos é a parte que a maioria das equipes subestima. Três sinais funcionam:

Número de telefone. O melhor sinal quando seu discador captura o número de origem da ligação. Normalize antes de buscar: remova todos os caracteres que não sejam dígitos, para que "+55 11 99999-8888" e "551199998888" correspondam ao mesmo registro.

async function findContactByPhone(phone) {
  const digits = phone.replace(/\D/g, '');
  const result = await hubspot.crm.contacts.searchApi.doSearch({
    filterGroups: [{
      filters: [{ propertyName: 'phone', operator: 'EQ', value: digits }]
    }],
    limit: 1
  });
  return result.results[0] ?? null;
}

Endereço de e-mail. Quando a chamada foi agendada pelo calendário, o convite traz os e-mails dos participantes. Use-os para localizar o contato:

async function findContactByEmail(email) {
  const result = await hubspot.crm.contacts.searchApi.doSearch({
    filterGroups: [{
      filters: [{ propertyName: 'email', operator: 'EQ', value: email }]
    }],
    limit: 1
  });
  return result.results[0] ?? null;
}

Fallback de vendedor e horário. Quando não há telefone nem e-mail disponíveis (cold calls, linhas compartilhadas), recorra aos negócios abertos do vendedor que estavam ativos por volta do horário da chamada. É menos confiável, mas útil para não perder a transcrição por completo.

Passo 4: Criar um Call Engagement no HubSpot

Depois de encontrar a correspondência, grave a transcrição como um Call Engagement. O ID correto do tipo de associação de chamada para contato é 194. Para chamada para negócio, o ID correto é 220 (e não 195, que está errado e vai falhar silenciosamente ou criar associações incorretas).

async function attachTranscriptToContact(contactId, dealId, data) {
  const durationMs = data.duration_seconds * 1000;

  const call = await hubspot.crm.objects.calls.basicApi.create({
    properties: {
      hs_timestamp: new Date().toISOString(),
      hs_call_title: `Recorded call (${Math.round(data.duration_seconds / 60)} min)`,
      hs_call_body: data.transcript,
      hs_call_duration: String(durationMs),
      hs_call_status: 'COMPLETED',
      hs_call_direction: 'OUTBOUND',
      hs_call_summary: data.summary ?? ''
    },
    associations: [
      {
        to: { id: contactId },
        types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 194 }]
      },
      ...(dealId
        ? [{
            to: { id: dealId },
            types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 220 }]
          }]
        : [])
    ]
  });

  return call.id;
}

O campo hs_call_body guarda o texto da transcrição. Em chamadas longas, teste se o texto permanece dentro do limite de caracteres por propriedade do HubSpot (segundo a documentação do HubSpot, consulte a API de propriedades para verificar o teto atual do fieldType: textarea). Para transcrições muito longas, use uma segunda propriedade personalizada ou armazene o texto completo externamente e insira um link para ele.

Passo 5: Extrair Sinais do Negócio (Opcional)

Se a resposta da transcrição incluir um resumo, ou se você quiser rodar uma passagem de LLM pelo texto, é possível enviar sinais estruturados para as propriedades do negócio. Primeiro crie as propriedades personalizadas no HubSpot (Configurações, Propriedades, Negócios) e depois atualize:

async function updateDealFromTranscript(dealId, transcript, summary) {
  await hubspot.crm.deals.basicApi.update(dealId, {
    properties: {
      last_call_summary: summary ?? '',
      last_call_date: new Date().toISOString().split('T')[0]
      // Add your custom properties here: last_call_sentiment, next_steps, etc.
    }
  });
}

Para extração estruturada (sinais BANT, objeções, tomadores de decisão), execute uma chamada de LLM separada sobre o texto da transcrição antes deste passo. A ferramenta de transcrição de reuniões consegue gerar resumos formatados que entram diretamente nessa atualização.

O Handler Ponta a Ponta

async function processCompletedTranscription(data) {
  const meta = await getCallMetadata(data.audio_filename);

  const contact =
    (await findContactByPhone(meta.phone)) ??
    (await findContactByEmail(meta.email));

  if (!contact) {
    await logUnmatchedCall(data, meta);
    return;
  }

  const deal = await getActiveDealForContact(contact.id);

  await attachTranscriptToContact(contact.id, deal?.id ?? null, data);

  if (deal && data.summary) {
    await updateDealFromTranscript(deal.id, data.transcript, data.summary);
  }

  await notifyRep(meta.rep_email, contact, data);
}

A função getCallMetadata extrai telefone, e-mail e vendedor do nome do arquivo da gravação ou de um arquivo sidecar de metadados. A fonte exata depende da sua plataforma de chamadas.

Lidando com Chamadas Sem Correspondência

Espere que de 5% a 15% das chamadas falhem na correspondência de contatos: prospecção fria, leads novos que ainda não estão no HubSpot ou chamadas em linhas compartilhadas.

Opção A: Crie um novo contato a partir da chamada. Defina o telefone como primeira propriedade, o estágio do ciclo de vida como "Lead" e deixe o SDR enriquecer depois.

Opção B: Registre as chamadas sem correspondência em um objeto personalizado "Transcrições sem correspondência" e direcione para uma fila de SDRs para triagem semanal.

Opção C: Salve a transcrição no seu próprio banco de dados e deixe o HubSpot de fora dessa chamada. Algumas chamadas (números errados, robodiscagens) são ruído genuíno.

O Que a CI Nativa Deixa Passar e Isso Corrige

Para equipes que já estão no Sales Hub Professional, o caminho via API agrega valor em lacunas específicas:

• Discadores externos: Chamadas feitas pelo Outreach, Salesloft ou um sistema VoIP que não esteja na lista de parceiros do HubSpot ficam completamente de fora da CI. O caminho via API as captura.
• Importação histórica: A CI só processa chamadas dali para frente. O caminho via API permite importar um ano de gravações do Zoom Cloud em uma única noite.
• Cobertura de idiomas: O suporte de idiomas de transcrição da CI é mais restrito do que o de APIs dedicadas de transcrição. Para equipes cujas chamadas não são majoritariamente em inglês, uma camada de transcrição separada (veja melhores APIs de speech-to-text para 2026) entrega melhor precisão.
• Chamadas de usuários fora do HubSpot: A CI exige um assento pago por usuário. Funcionários contratados, operadores offshore ou vendedores parceiros que usam ferramentas separadas não geram transcrições da CI. O caminho via API processa as gravações deles independentemente disso.

Quanto Isso Custa vs. Gong

Antes desta integração, equipes que queriam inteligência de transcrição de chamadas geralmente avaliavam:

• Gong: Taxa de plataforma de US$ 5.000 a US$ 50.000 por ano, mais aproximadamente US$ 1.400 a US$ 2.000 por usuário por ano (valor não publicado, cotado sob consulta empresarial). Para uma equipe de 10 vendedores, planeje de US$ 20.000 a US$ 35.000 por ano.
• Anotações manuais: Os vendedores digitam resumos após cada chamada. Incompleto, lento e enviesado para os detalhes favoráveis.

O caminho via API custa:

• Uma assinatura de API de transcrição (opções de taxa fixa começam abaixo de US$ 15/mês para um usuário individual, escalando a partir daí).
• O HubSpot que você já tem.
• Um dia de configuração de engenharia.

A troca é honesta: o Gong e o Chorus constroem análises de coaching, rastreamento de palavras-chave e previsão de negócios em cima das transcrições. O caminho via API entrega a base e deixa a camada de análises por sua conta (ou para um complemento mais barato, como as próprias ferramentas de IA do HubSpot).

Se você só precisa de transcrições limpas anexadas a contatos e negócios, sem uma assinatura dedicada de conversation intelligence, a ferramenta de transcrição de reuniões do ConvertAudioToText aceita envio direto de arquivo ou URL e retorna uma saída estruturada que se encaixa perfeitamente no handler acima.

Alternativa com Zapier

O Zapier tem um app nativo do HubSpot listado no marketplace do HubSpot. Para equipes sem perfil técnico, o fluxo é:

1. Gatilho: Webhook (evento job.completed da transcrição).
2. Filtro ou Formatter: normalize o número de telefone.
3. Busca: encontre o contato do HubSpot por telefone ou e-mail.
4. Ação: crie um Call Engagement do HubSpot com o texto da transcrição.

Isso cobre o caso simples. Código personalizado lida melhor com os casos extremos, especialmente a correspondência de contatos em cold calls e a lógica de fallback para chamadas sem correspondência.

Armadilhas em Produção

Normalização do número de telefone. Números internacionais como "+55 11 99999-8888" precisam ter os dígitos extraídos antes de buscar no HubSpot. Crie um helper normalizePhone(str) e passe todos os números por ele antes de qualquer consulta.

Linhas telefônicas multiusuário ou compartilhadas. Se vários vendedores compartilham um número, a correspondência por telefone fica ambígua. Recorra ao e-mail ou ao contexto do calendário.

Confiabilidade do webhook. Monte um job diário de reconciliação que verifique jobs de transcrição concluídos e ainda não registrados no HubSpot. Sem isso, indisponibilidades do seu handler podem criar lacunas.

Permissões de chamadas no HubSpot. Por padrão, os registros de chamadas ficam visíveis para qualquer pessoa com acesso aos contatos. Para chamadas de vendas sensíveis, restrinja o acesso via equipes e funções do HubSpot antes de colocar no ar.

Testando os IDs de associação. Rode uma criação de chamada de teste contra um contato e um negócio em sandbox antes de conectar à produção. Registre o ID da chamada retornado e confirme que o engagement aparece tanto na linha do tempo do contato quanto na do negócio.

Perguntas Frequentes

O HubSpot transcreve chamadas nativamente?

Sim, mas apenas nos planos Sales Hub Professional (US$ 90/usuário/mês faturado anualmente) ou Enterprise. Chamadas feitas pelo discador nativo do HubSpot, pela integração Zoom, pela integração Google Meet e por provedores de chamadas de terceiros selecionados são transcritas automaticamente. Chamadas de discadores externos ou arquivos de áudio enviados exigem um caminho separado de envio via API.

Posso enviar uma gravação externa para o HubSpot transcrever?

Sim, mas com restrições. A API de extensões de chamadas do HubSpot aceita arquivos WAV, FLAC e MP4 para transcrição, o áudio precisa ser multicanal (cada falante em um canal separado) e a transcrição só roda para usuários com assento pago no Sales ou Service Hub. O fluxo exige registrar um endpoint autenticado para a URL da sua gravação, registrar a chamada com hs_call_source definido como INTEGRATIONS_PLATFORM e, em seguida, chamar o endpoint /recordings/ready para disparar o processamento.

Qual é o ID correto do tipo de associação do HubSpot para vincular uma chamada a um negócio?

O ID correto do tipo de associação de chamada para negócio é 220, e não 195. Chamada para contato é 194. Ambos usam associationCategory definido como HUBSPOT_DEFINED. Usar 195 vai falhar silenciosamente ou criar uma associação incorreta.

Existe uma forma sem código de enviar transcrições para o HubSpot?

O Zapier tem um app nativo do HubSpot listado no marketplace do HubSpot. Você pode configurar um gatilho de webhook ao concluir a transcrição e usar a ação do HubSpot para criar um engagement. A limitação está na correspondência de contatos: o Zapier resolve buscas simples por e-mail ou telefone, mas casos extremos como cold calls ou linhas telefônicas compartilhadas pedem código personalizado com lógica de fallback.

Fontes

• Preços do HubSpot Sales Hub - verificado em julho de 2026
• Revisar gravações e transcrições de chamadas - Base de Conhecimento do HubSpot - verificado em julho de 2026
• Extensões de Chamadas do HubSpot: API de Gravações e Transcrições - verificado em julho de 2026
• API v3 de Engagements de Chamadas do HubSpot - IDs de Tipos de Associação - verificado em julho de 2026
• Preços do Gong 2026 - verificado em julho de 2026
• Integração Zapier com HubSpot - Marketplace do HubSpot - verificado em julho de 2026