A etapa Loop na etapa de colega/agente permite que o Fin pause no meio do procedimento e aguarde uma decisão humana antes de continuar. O Fin envia uma notificação para um sistema externo de sua escolha — alguém revisa a solicitação, uma decisão é enviada de volta, e o Fin retoma de onde parou.
Os dados de relatório para etapas Human-in-the-Loop aplicam-se apenas a e-mails e não a chats.
Quando usar o webhook HITL independente
A etapa Loop na etapa de colega/agente tem dois usos principais:
Supervisão humana — para ações de alto risco ou alto valor onde um humano deve revisar e aprovar antes que o Fin prossiga. Exemplos: aprovações de reembolso ou exceção, solicitações sensíveis a conformidade (ex.: encerramento de contas, exclusão de dados), escalonamentos de clientes de alto valor, gestos de boa vontade ou qualquer situação onde a política exige aprovação humana.
Teste de procedimento — para substituir um conector de dados ou ação de backend que ainda não foi construído. Um humano pode executar a etapa manualmente, permitindo testar o fluxo completo do procedimento antes que a integração esteja pronta.
O que você vai precisar
Antes de começar, certifique-se de que você tem:
Um Procedimento Fin com pelo menos uma etapa Loop na etapa de colega/agente
Uma URL (endpoint webhook) onde seu sistema pode receber e responder notificações do Fin
A permissão Gerenciar apps e integrações nas Configurações
Nota: Você não precisa de ferramentas de desenvolvedor de terceiros ou credenciais de app para configurar isso — tudo é configurado diretamente no editor de procedimentos.
Como funciona
Quando a conversa de um cliente alcança uma etapa Loop na etapa de colega/agente em um Procedimento Fin:
1. O Fin pausa a conversa
Antes de pausar, o Fin pode enviar uma mensagem ao cliente — informando que a solicitação está sendo revisada.
O Fin envia uma notificação para seu sistema externo.
O Fin espera e não continua até que uma resposta seja recebida ou a etapa expire.
2. Seu sistema é notificado
Seu sistema recebe uma notificação com os detalhes da conversa e as informações necessárias para tomar uma decisão.
Um revisor humano vê a solicitação — ou seu sistema aplica sua própria lógica para responder automaticamente.
Quando o Fin alcança a etapa Loop na etapa de colega/agente, ele envia uma notificação para seu sistema externo com os detalhes da conversa e a ação necessária. Neste exemplo, um revisor recebe uma solicitação de redefinição de 2FA e instruções para verificar a identidade do cliente antes de responder.
3. A decisão é enviada de volta
Seu sistema envia a decisão de volta para o Fin.
4. O Fin continua o procedimento
O Fin retoma de onde parou.
A resposta do seu sistema está disponível em etapas posteriores via uma etapa Ler atributo.
Use uma condição SE/SENÃO para ramificar com base no resultado — por exemplo: aprovado, continuar; recusado, enviar uma mensagem ao cliente.
Importante: Um procedimento com uma etapa Loop na etapa de colega/agente não pode ser publicado até que a conexão webhook esteja configurada. Você será solicitado a concluir a configuração antes da publicação.
Etapa 1: Adicionar e configurar a etapa
Vá para Treinar > Procedimento e abra o procedimento ao qual deseja adicionar a etapa.
No bloco de instruções, digite @ e selecione Loop na etapa de colega/agente.
A etapa aparece no editor de procedimentos. Você verá uma contagem Coletar mostrando quantos campos de resposta estão definidos, e um Tempo de espera mostrando quanto tempo o Fin vai esperar — ambos configurados no painel de configurações da etapa.
Clique no ícone de engrenagem para abrir as configurações da etapa. O painel de configurações tem três seções: Perguntar via webhook (para a conexão webhook), Resposta a coletar (os campos que seu revisor preenche), e Tempo de espera (quanto tempo o Fin espera antes de expirar).
Em Perguntar via webhook, clique em Configurar. Insira sua URL de entrega — o endereço web onde o Intercom envia a notificação quando esta etapa é alcançada — e clique em Salvar.
O modal Loop na etapa de colega/agente webhook revela suas credenciais de desenvolvedor uma vez conectado.
Em Resposta a coletar, clique em + Adicionar para definir os campos que seu revisor precisa preencher. Dê a cada campo um formato e um nome — por exemplo, um campo de texto 'Motivo da rejeição' ou um booleano 'Aprovado'.
Cada campo de resposta tem um formato — dropdown, texto ou booleano (verdadeiro/falso) — um nome e uma descrição opcional. Quando um colega é incluído no loop, ele preenche esses campos diretamente na conversa.
Em Tempo de espera, defina quanto tempo o Fin deve esperar por uma resposta antes de expirar. O mínimo é 1 minuto — não há máximo. Você pode escolher minutos ou horas. Edite a mensagem abaixo para controlar o que o Fin diz ao cliente se o tempo de espera for excedido.
Salve seu Procedimento. Continue para a Etapa 2 para obter suas credenciais de desenvolvedor — o procedimento não pode ser publicado até que a conexão webhook esteja configurada.
Nota: Para a etapa Loop na etapa de colega/agente com entrega via webhook, este é o único canal de entrega — não há opção para rotear para um inbox ou equipe.
Etapa 2: Obtenha suas credenciais de desenvolvedor
Após salvar a URL de entrega no modal Loop na etapa de colega/agente webhook, o modal mostra Webhook conectado e revela três credenciais que seu desenvolvedor precisa. Se mostrar Não configurado, verifique se sua URL de entrega está salva e se nenhum token de acesso emitido anteriormente expirou ou foi revogado — um token revogado também impede que o Procedimento Fin seja publicado.
Token de acesso — autentica as respostas que seu sistema envia de volta para o Fin.
Segredo de assinatura — confirma que as notificações recebidas são genuinamente do Intercom.
URL de callback de exemplo — uma URL única é gerada para cada conversa. Seu sistema envia a decisão do revisor para essa URL para retomar o procedimento.
Nota: Você pode visualizar essas credenciais a qualquer momento clicando em Configurar na seção Perguntar via webhook do painel de configurações da etapa. Apenas colegas com permissão Gerenciar apps e integrações podem abrir este diálogo — colegas sem essa permissão verão um prompt para solicitar permissão.
Etapa 3: Manipule o payload do webhook
Quando o modal mostrar Webhook conectado, compartilhe o Token de acesso, Segredo de assinatura e a URL de callback de exemplo do modal Loop na etapa de colega/agente webhook com o desenvolvedor que está construindo a integração. Ele criará o endpoint que:
Recebe a notificação do Fin quando a etapa é alcançada
Apresenta a solicitação a um revisor, ou aplica lógica automatizada
Envia a decisão de volta para que o Fin possa continuar
Payload do webhook
Quando o procedimento alcança a etapa Loop na etapa de colega/agente, o Intercom envia uma requisição POST para sua URL de entrega. O payload inclui:
O ID da conversa
A pergunta que o Fin está fazendo
Os atributos que seu sistema precisa preencher
Uma URL de callback para enviar sua resposta
Mensagens recentes da conversa para contexto
Para o payload completo e especificações de campo, formato de requisição de callback, detalhes de autenticação, tipos de dados suportados e códigos de erro, veja a referência da API de procedimentos.
Como testar o webhook HITL independente
Use Simulações — execuções de teste automatizadas no editor de procedimentos — para testar a etapa Loop na etapa de colega/agente sem disparar uma notificação webhook real para seu sistema.
Abra uma simulação para o procedimento e procure a seção Entrada do colega disponível para o Fin. Adicione os valores que você esperaria de um revisor — por exemplo, Aprovado: verdadeiro — e execute a simulação. O Fin usa esses valores como se seu sistema tivesse respondido.
Nota: Se você não adicionar valores antes de executar, o Fin trata a etapa como expirada.
Limitações
Há uma URL de entrega por workspace. Alterá-la atualiza a conexão webhook para todos os Procedimentos Fin que usam a etapa Loop na etapa de colega/agente.
Se o tempo de espera expirar e nenhuma resposta for recebida, o Fin envia ao cliente a mensagem de timeout que você configurou — o procedimento termina e a conversa é escalada.
A mensagem de timeout padrão se refere a ‘a equipe’ — atualize-a antes de publicar para corresponder à sua configuração real.
Webhook HITL independente vs abordagem API Developer Hub
Ambos os métodos pausam um procedimento em uma etapa HITL e notificam seu sistema via webhook — mas diferem em como são configurados e para quem são:
Webhook HITL independente: Configurado diretamente no editor de procedimentos — não requer app Developer Hub ou escopos OAuth. Uma URL de entrega por workspace. Disponível apenas para workspaces Fin Standalone. O canal webhook é ativado automaticamente em todas as etapas HITL em procedimentos Standalone.
Abordagem API Developer Hub: Requer um app Developer Hub, versão Preview da API e os escopos OAuth read_conversations e write_conversations. Ativado por etapa e funciona junto com os canais Intercom Inbox e Slack. Disponível para workspaces não-Standalone. Veja Aprovações Human-in-the-loop via API.
Do ponto de vista do cliente, ambas as abordagens são invisíveis — a conversa continua sem interrupção assim que seu sistema responde.
Perguntas frequentes
Posso usar uma URL webhook diferente para procedimentos diferentes?
Posso usar uma URL webhook diferente para procedimentos diferentes?
Você não pode usar uma URL webhook diferente para procedimentos diferentes — há uma URL de entrega por workspace. Todo Procedimento Fin que usa a etapa Loop na etapa de colega/agente envia notificações para o mesmo endpoint. Se precisar rotear solicitações de forma diferente por procedimento, seu sistema externo pode fazer isso com base nos detalhes incluídos na notificação.
O que acontece com o cliente enquanto ele espera por uma resposta?
O que acontece com o cliente enquanto ele espera por uma resposta?
Enquanto espera por uma resposta, o Fin pausa a conversa silenciosamente, a menos que você tenha adicionado uma mensagem de espera. Você pode configurar isso na seção Tempo de espera das configurações da etapa — por exemplo, “Estamos revisando sua solicitação e entraremos em contato em breve.” Se nenhuma resposta for recebida a tempo, o Fin envia a mensagem de timeout que você configurou, o procedimento termina e a conversa é escalada.
Posso adicionar mais de uma etapa Loop na etapa de colega/agente ao mesmo procedimento?
Posso adicionar mais de uma etapa Loop na etapa de colega/agente ao mesmo procedimento?
Sim, você pode adicionar mais de uma etapa Loop na etapa de colega/agente ao mesmo procedimento. Múltiplas etapas são suportadas para coletar entrada humana em diferentes pontos do fluxo. Todas as etapas compartilham a mesma conexão webhook do workspace.
Posso alterar a URL de entrega depois de configurá-la?
Posso alterar a URL de entrega depois de configurá-la?
Sim, você pode alterar a URL de entrega depois de configurá-la. Clique em Configurar na seção Perguntar via webhook do painel de configurações da etapa e insira uma nova URL. Lembre-se de que alterá-la atualiza a conexão webhook para todos os Procedimentos Fin que usam esta etapa, não apenas para o que você está editando no momento.
Existe uma forma de rastrear quais decisões foram tomadas?
Existe uma forma de rastrear quais decisões foram tomadas?
Não há como rastrear decisões tomadas por meio desta etapa no Intercom — não há relatórios ou análises para decisões individuais. Seu sistema externo é responsável por registrar e rastrear as respostas.