O canal Respond by API permite conectar etapas Human-in-the-Loop (HITL) em Fin Procedures aos seus próprios sistemas usando webhooks e a API do Intercom. Quando o Fin alcança uma etapa HITL, o Intercom envia um webhook para seu endpoint. Seu sistema processa a solicitação, preenche os atributos necessários e envia uma resposta de volta, permitindo que o procedimento continue automaticamente.
Nota: Este recurso está atualmente em disponibilidade gerenciada. Para usá-lo, seu app Developer Hub deve estar configurado para a versão Preview da API.
Exemplos
Aqui estão algumas formas de usar este recurso:
Workflows de aprovação automatizados: Direcione aprovações de reembolso ou desconto para uma ferramenta interna que aplica regras de negócio e responde automaticamente
Painéis personalizados para colegas: Exiba solicitações HITL em suas próprias ferramentas de suporte ou portal interno junto com outras tarefas
Escalonamento para equipes externas: Encaminhe perguntas para equipes que não usam Intercom — como engenharia, jurídico ou finanças — e capture a resposta deles
Registro de auditoria e conformidade: Registre cada decisão HITL em um sistema de conformidade antes de responder, criando uma trilha automática de papel
Antes de começar
Para configurar o Respond by API, você precisará de:
Um Fin Procedure com pelo menos uma etapa Human-in-the-Loop
Um app Developer Hub — crie um em Configurações > Developer Hub se ainda não tiver um
Um endpoint HTTPS que possa receber solicitações webhook
Seu app Developer Hub deve ter os escopos OAuth read_conversations e write_conversations
Passo 1: Ative Ask via webhook em seu procedimento
Abra o procedimento que deseja configurar no editor de Procedures.
Selecione sua etapa Human-in-the-Loop.
Abra o painel de Configurações da etapa clicando no ícone de engrenagem.
Selecione a aba Mais canais.
Expanda a seção Ask via webhook.
Ative Habilitar para este procedimento.
Clique em Verificar configuração do webhook para confirmar que seu app Developer Hub está corretamente inscrito.
Salve seu procedimento.
Após clicar em Verificar configuração do webhook, você verá uma das seguintes mensagens:
"Webhook conectado." — seu webhook está configurado corretamente
"Nenhum webhook encontrado." — você precisa configurar seu webhook no Developer Hub (veja o Passo 2)
Se a verificação falhar, clique em Developer Hub para abrir a configuração do seu app em uma nova aba.
Nota: O canal Ask via webhook funciona junto com os canais Inbox e Slack. Quando uma etapa HITL é alcançada, todos os canais habilitados são notificados ao mesmo tempo. O canal que responder primeiro vence — respostas subsequentes são rejeitadas.
Passo 2: Configure seu webhook no Developer Hub
Vá para Configurações > Developer Hub, ou navegue diretamente para as configurações do seu app.
Selecione seu app, ou crie um novo.
Vá para Versão da API e mude para Preview.
Vá para Webhooks na configuração do seu app.
Digite a URL do endpoint do seu webhook (deve ser HTTPS).
Adicione o tópico procedure.hitl_notification.created aos seus tópicos inscritos.
Certifique-se de que seu app tenha os escopos OAuth necessários: read_conversations (necessário para receber notificações webhook) e write_conversations (necessário para enviar respostas de callback via API).
Salve a configuração do seu webhook.
Importante: O tópico webhook HITL está disponível apenas na versão Preview da API enquanto este recurso está em disponibilidade gerenciada. Você deve mudar para esta versão antes que o tópico apareça na lista de tópicos webhook.
Passo 3: Trate a carga útil do webhook
Quando um procedimento alcança uma etapa Human-in-the-Loop com Ask via webhook ativado, o Intercom envia uma requisição POST para o endpoint do seu webhook. A carga útil 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 especificações completas da carga útil e dos campos, veja a referência da API de procedures.
Passo 4: Envie uma resposta de callback
Depois que seu sistema processar a solicitação HITL, envie uma requisição POST para a callback_url fornecida na carga útil do webhook. Inclua o step_id e os valores para cada atributo listado em attributes_to_collect. Autentique com um token Bearer que tenha o escopo OAuth write_conversations.
Após uma resposta bem-sucedida, o Fin retoma o procedimento usando os valores dos atributos que você forneceu. O colega associado ao seu token OAuth é registrado como quem respondeu.
Para o formato completo da requisição de callback, detalhes de autenticação, tipos de dados suportados e códigos de erro, veja a referência da API de procedures.
Melhores práticas
Tenha estas dicas em mente ao construir sua integração:
Verifique assinaturas webhook: O Intercom assina cargas úteis webhook com HMAC. Sempre verifique a assinatura para confirmar que a solicitação é autêntica. Veja a referência da API de procedures para detalhes.
Responda antes do tempo limite: Solicitações HITL têm um tempo de espera configurável definido no editor de Procedures. Se nenhuma resposta for recebida antes de expires_at, o procedimento executa seu comportamento de timeout configurado (mensagem de escalonamento, reatribuição, etc.).
Não envie respostas duplicadas: O callback não é idempotente. Se você enviar uma resposta mais de uma vez para a mesma etapa, requisições subsequentes retornam 409 Conflict. Se receber um 409, sua resposta original já foi processada.
Para atributos de lista, envie o id da opção: Não envie o rótulo exibido da opção — envie seu id do array de opções.
Rastreie quem responde: O colega associado ao seu token OAuth é registrado como o respondente. Considere usar uma conta de serviço dedicada se quiser uma identidade consistente.
Trate corridas multi-canal com cuidado: Se o canal API estiver habilitado junto com Inbox ou Slack, a primeira resposta vence. Seu sistema pode receber um 409 se um colega responder por outro canal primeiro.