El canal Respond by API te permite conectar los pasos Human-in-the-Loop (HITL) en Fin Procedures a tus propios sistemas usando webhooks y la API de Intercom. Cuando Fin llega a un paso HITL, Intercom envía un webhook a tu endpoint. Tu sistema procesa la solicitud, completa los atributos requeridos y envía una respuesta, permitiendo que el procedimiento continúe automáticamente.
Nota: Esta función está actualmente en disponibilidad gestionada. Para usarla, tu app de Developer Hub debe estar configurada en la versión Preview API.
Ejemplos
Aquí tienes algunas formas de usar esta función:
Flujos de aprobación automatizados: Dirige aprobaciones de reembolsos o descuentos a una herramienta interna que aplica reglas de negocio y responde automáticamente
Paneles personalizados para compañeros: Muestra solicitudes HITL en tus propias herramientas de soporte o portal interno junto con otras tareas
Escalación a equipos externos: Reenvía preguntas a equipos que no usan Intercom — como ingeniería, legal o finanzas — y captura su respuesta
Registro de auditoría y cumplimiento: Registra cada decisión HITL en un sistema de cumplimiento antes de responder, creando un rastro automático de papel
Antes de comenzar
Para configurar Respond by API, necesitarás:
Un Fin Procedure con al menos un paso Human-in-the-Loop
Una app de Developer Hub — crea una en Configuración > Developer Hub si aún no tienes una
Un endpoint HTTPS que pueda recibir solicitudes webhook
Tu app de Developer Hub debe tener los alcances OAuth read_conversations y write_conversations
Paso 1: Habilita Preguntar vía webhook en tu procedimiento
Abre el procedimiento que quieres configurar en el editor de Procedimientos.
Selecciona tu paso Human-in-the-Loop.
Abre el panel de Configuración del paso haciendo clic en el ícono de engranaje.
Selecciona la pestaña Más canales.
Expande la sección Preguntar vía webhook.
Activa Habilitar para este procedimiento.
Haz clic en Verificar configuración de webhook para confirmar que tu app de Developer Hub está suscrita correctamente.
Guarda tu procedimiento.
Después de hacer clic en Verificar configuración de webhook, verás uno de estos mensajes:
"Webhook conectado." — tu webhook está configurado correctamente
"No se encontró webhook." — necesitas configurar tu webhook en Developer Hub (ver Paso 2)
Si la verificación falla, haz clic en Developer Hub para abrir la configuración de tu app en una nueva pestaña.
Nota: El canal Preguntar vía webhook funciona junto con los canales Inbox y Slack. Cuando se alcanza un paso HITL, todos los canales habilitados son notificados al mismo tiempo. El canal que responda primero gana — las respuestas posteriores son rechazadas.
Paso 2: Configura tu webhook en Developer Hub
Ve a Configuración > Developer Hub, o navega directamente a la configuración de tu app.
Selecciona tu app, o crea una nueva.
Ve a Versión API y cambia a Preview.
Ve a Webhooks en la configuración de tu app.
Ingresa la URL de tu endpoint webhook (debe ser HTTPS).
Agrega el tema procedure.hitl_notification.created a tus temas suscritos.
Asegúrate de que tu app tenga los alcances OAuth requeridos: read_conversations (necesario para recibir notificaciones webhook) y write_conversations (necesario para enviar respuestas callback vía API).
Guarda la configuración de tu webhook.
Importante: El tema webhook HITL solo está disponible en la versión Preview API mientras esta función está en disponibilidad gestionada. Debes cambiar a esta versión antes de que el tema aparezca en la lista de temas webhook.
Paso 3: Maneja la carga útil del webhook
Cuando un procedimiento llega a un paso Human-in-the-Loop con Preguntar vía webhook habilitado, Intercom envía una solicitud POST a tu endpoint webhook. La carga útil incluye:
El ID de la conversación
La pregunta que Fin está haciendo
Los atributos que tu sistema debe completar
Una URL de callback para enviar tu respuesta
Mensajes recientes de la conversación para contexto
Para la especificación completa de la carga útil y campos, consulta la referencia API de procedimientos.
Paso 4: Envía una respuesta callback
Una vez que tu sistema haya procesado la solicitud HITL, envía una solicitud POST a la callback_url proporcionada en la carga útil del webhook. Incluye el step_id y los valores para cada atributo listado en attributes_to_collect. Autentica con un token Bearer que tenga el alcance OAuth write_conversations.
Después de una respuesta exitosa, Fin reanuda el procedimiento usando los valores de atributos que proporcionaste. El compañero asociado con tu token OAuth queda registrado como quien respondió.
Para el formato completo de la solicitud callback, detalles de autenticación, tipos de datos soportados y códigos de error, consulta la referencia API de procedimientos.
Mejores prácticas
Ten en cuenta lo siguiente al construir tu integración:
Verifica las firmas webhook: Intercom firma las cargas útiles webhook con HMAC. Siempre verifica la firma para confirmar que la solicitud es auténtica. Consulta la referencia API de procedimientos para más detalles.
Responde antes del tiempo de espera: Las solicitudes HITL tienen un tiempo de espera configurable establecido en el editor de Procedimientos. Si no se recibe respuesta antes de expires_at, el procedimiento ejecuta su comportamiento de tiempo de espera configurado (mensaje de escalación, reasignación, etc.).
No envíes respuestas duplicadas: El callback no es idempotente. Si envías una respuesta más de una vez para el mismo paso, las solicitudes posteriores devuelven 409 Conflict. Si recibes un 409, tu respuesta original ya fue procesada.
Para atributos de lista, envía el id de la opción: No envíes la etiqueta visible de la opción — envía su id del arreglo de opciones.
Registra quién responde: El compañero asociado con tu token OAuth queda registrado como el que responde. Considera usar una cuenta de servicio dedicada si quieres una identidad consistente.
Maneja las carreras multicanal con gracia: Si el canal API está habilitado junto con Inbox o Slack, la primera respuesta gana. Tu sistema puede recibir un 409 si un compañero responde primero por otro canal.