Home Integrations with Helpdesks [HubSpot] Nova Lógica de Transbordo — Eventos Personalizados e Workflows

[HubSpot] Nova Lógica de Transbordo — Eventos Personalizados e Workflows

Last updated on Mar 30, 2026

1. O que mudou na lógica de transbordo do HubSpot?

Em fevereiro de 2026, o HubSpot lançou novas funcionalidades que nos permitem evoluir a lógica de transferência de tickets para N2. Com isso, migramos o fluxo de transbordo para essa nova abordagem, tornando a funcionalidade mais resiliente, rastreável e observável.

As principais melhorias que essa evolução traz:

  • Maior resiliência: o fluxo agora passa inteiramente por APIs e automações oficiais do HubSpot, reduzindo pontos de falha.

  • Rastreabilidade: cada transferência gera eventos auditáveis diretamente na plataforma, facilitando a investigação de qualquer ocorrência.

  • Observabilidade: conseguimos monitorar com mais precisão quantas transferências são concluídas com sucesso e identificar rapidamente qualquer desvio.

2. Como funciona a nova lógica de transbordo?

Quando a ClaudIA decide transbordar o ticket para N2, o sistema agora:

  1. Busca o ID do ticket associado à conversa no HubSpot.

  2. Dispara um Evento Personalizado via API oficial do HubSpot, referenciando esse ticket.

  3. Um Workflow configurado no HubSpot é ativado automaticamente ao receber esse evento.

  4. O Workflow executa a transferência, atribuindo o ticket ao agente ou equipe de N2 configurados.

Nenhuma autenticação extra é necessária, todo o fluxo passa pelas APIs e automações oficiais da plataforma.

3. Preciso fazer algo no meu HubSpot?

Sim. Para que o novo fluxo funcione, é necessário criar no seu HubSpot:

  • 1 Workflow de notificação de criação de ticket — envia o ID do ticket ao nosso sistema no momento em que ele é criado (único por integração).

  • 1 Evento Personalizado por fluxo de transbordo — recebe o sinal da ClaudIA para iniciar a transferência.

  • 1 Workflow de transbordo baseado nesse evento por fluxo de transbordo — executa a atribuição para o agente ou equipe de N2.

⚠️ Para clientes que utilizam a versão Inbox (e não Helpdesk), são necessários dois workflows adicionais. Veja a seção 7 para mais detalhes.

4. Por que precisamos de um evento de criação de ticket enviado ao nosso webhook?

Para disparar o transbordo corretamente, o sistema precisa conhecer o ID do ticket no HubSpot (hs_ticket_id) associado à conversa em andamento.

O HubSpot não disponibiliza um método oficial na API para obter o ID do ticket a partir do ID de uma conversa (threadId). Ou seja: quando a ClaudIA está atendendo e precisa transbordar o ticket, não é possível simplesmente consultar a API do HubSpot e perguntar "qual ticket está associado a essa conversa?" de forma direta e confiável.

Para resolver isso, utilizamos um evento enviado pelo próprio HubSpot ao nosso webhook no momento em que o ticket é criado. Esse evento carrega o threadId da conversa e o hs_ticket_id do ticket recém-criado, permitindo que armazenemos essa associação do nosso lado e a utilizemos durante o transbordo.

⚠️ Sem esse evento, o sistema não consegue identificar com certeza o ticket correto e o transbordo via evento personalizado pode falhar.

4.1. Como configurar o Workflow de notificação de criação de ticket

  • Acesse Automações → Fluxos de Trabalho.

    • Crie um workflow baseado em Ticket.

  • Configure o gatilho: "Quando um ticket é criado".

  • Adicione a ação "Enviar webhook" e configure com a URL fornecida pela Cloud Humans.

  • O payload deve incluir o ID do ticket (hs_ticket_id) e o ID da conversa associada (threadId).

  • Ative o Workflow.

Esse workflow precisa existir uma única vez por integração, independentemente de quantos fluxos de transbordo você tiver.

5. Como configurar o Evento Personalizado de transbordo no HubSpot

O Evento Personalizado é o gatilho que a Cloud Humans utiliza para avisar o HubSpot que um transbordo deve acontecer.

5.1. Criar o Evento Personalizado

  • Acesse Configurações → Gerenciamento de dados → Eventos personalizados.

  • Clique em "Criar evento personalizado".

  • Dê um nome claro ao evento (ex.: transbordo_para_n2).

  • Adicione a propriedade obrigatória: objectId (tipo: Número).

  • Salve o evento.

⚠️ Após criar o evento, copie o nome interno gerado pelo HubSpot (formato pe12345_nome_do_evento) e envie para o time da Cloud Humans — ele é necessário para a configuração do nosso lado.

5.2. Informar o nome interno do evento à Cloud Humans

Após a criação, envie para o seu Customer Success:

  • O nome interno do Evento Personalizado criado.

  • Confirmação de que o evento está ativo.

6. Como configurar o Workflow de Transbordo no HubSpot

O Workflow é a automação responsável por mover o ticket para a equipe humana quando o evento de transbordo é recebido.

6.1. Criar o Workflow

  • Acesse Automações → Fluxos de Trabalho.

  • Clique em "Criar fluxo de trabalho" e selecione "Baseado em evento personalizado".

  • Selecione o evento criado na seção 5.

6.2. Configurar a ação de atribuição

  • Adicione a ação "Atribuir proprietário do ticket".

  • Selecione o agente ou equipe de N2 de destino.

  • Ative obrigatoriamente a opção "Substituir qualquer proprietário do ticket existente".

⚠️ Sem ativar essa opção, tickets que já possuem um proprietário atribuído não serão transferidos.

6.3. Ativar o Workflow

  • Salve e clique em "Ativar".

7. Configuração adicional para clientes que usam a versão Inbox

A nova lógica de transbordo funciona com a versão Helpdesk do HubSpot, que já associa automaticamente um ticket a cada conversa. Clientes que ainda utilizam a versão Inbox precisam configurar dois workflows adicionais para garantir essa associação.

⚠️ Na versão Inbox, cada conversa deve ter no máximo um ticket associado. Se houver mais de um ticket por conversa, o sistema não conseguirá identificar qual utilizar e o transbordo poderá falhar.

7.1. Workflow: criar ticket ao iniciar uma conversa

  • Acesse Automações → Fluxos de Trabalho.

  • Crie um workflow baseado em Conversa.

  • Configure o gatilho para criar o ticket assim que a conversa entrar pra a Claudia ou caso já tenha um fluxo que faça essa criação, deve ser ajustado pra nos enviar o webhook de criação.

  • Adicione a ação "Criar ticket" e configure os campos necessários (pipeline, estágio inicial, etc.).

  • Ative o Workflow.

7.2. Workflow: associar conversa ao proprietário do ticket

  • Crie um segundo workflow baseado em conversas.

  • Configure o gatilho: Ticket (Objeto Associado)".

    • A última mensagem é um comentário do thread é igual a Verdadeiro

    • Proprietário do ticket sempre foi qualquer um dos Claudia Cloud Humans

  • Adicione a ação "Revezar registro para o proprietário" e escolha suas opções de transferência.

  • Ative o Workflow.

8. E se eu tiver mais de um fluxo de transbordo?

Operações com múltiplos destinos de N2 (ex.: suporte técnico, financeiro, comercial) precisam de um Evento Personalizado e um Workflow para cada fluxo de transbordo.

  • Repita as configurações das seções 5 e 6 para cada fluxo.

  • Informe todos os nomes internos dos eventos criados para o time da Cloud Humans.

O Workflow de notificação de criação de ticket (seção 4) não precisa ser duplicado — ele é único por integração.

9. Uso de "ticket infinito" — reinscrição no Workflow

Alguns clientes utilizam a configuração de ticket infinito, onde um mesmo ticket é reutilizado em múltiplos atendimentos ao longo do tempo. Nesse cenário, o fluxo de transbordo pode precisar ser acionado mais de uma vez para o mesmo ticket.

Por padrão, os Workflows do HubSpot não permitem que o mesmo registro seja inscrito novamente após já ter passado pelo fluxo. Para habilitar isso:

  • Abra o Workflow de Transbordo.

  • Acesse Configurações (ícone de engrenagem).

  • Ative a opção "Permitir que registros sejam reinscritos".

É necessário falar com o nosso time se a sua operação utiliza ticket infinito e se essa configuração se aplica ao seu caso.