> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need.

# Integrar un workflow con TeLeo

Sigue estos pasos para conectar un workflow de texto con la consola sin publicar
cambios de forma improvisada. El destino de ATC texto continúa fuera de alcance
hasta que exista un workflow aprobado.

## Antes de empezar

* Define si la entrada será la frontera HappyRobot o la API Super App. Para una
  misma sesión utiliza una sola.
* Confirma organización, tenant, entorno, target y owner del workflow.
* Solicita una credencial M2M server-side; no la pongas en el cliente.
* Define `session_id`, correlación, canal, resumen y destino del webhook.
* Acordad retención, PII, adjuntos, notas privadas y criterio de cierre.
* Prepara un ticket sintético y un receptor de webhook idempotente.

## 1. Prepara el contexto

Incluye solo lo que el agente necesita para no repetir preguntas:

| Dato | Regla |
|---|---|
| Sesión y correlación | Estables y consistentes en creación, mensajes y webhook. |
| Canal y entorno | Explícitos para evitar cruzar voz, texto o perfiles. |
| Motivo y resumen | Breves, saneados y en el idioma acordado. |
| Estado de autenticación | Estado lógico; nunca el token original. |
| Cliente y caso | Solo campos autorizados y existentes. |
| Histórico | Solo el tramo necesario para continuar. |
| Secretos y cookies | Nunca se envían al ticket. |

## 2. Crea el ticket

Llama a `POST /api/hr/tickets` si el origen es HappyRobot o a
`POST /api/v1/tickets` si el integrador usa la API Super App. Consulta el
[contrato de API](/use-cases/super-app/teleo/reference/api) para el envelope.

El identificador del ticket debe ser el de la sesión estable. Guarda la
respuesta y comprueba si se creó o ya existía. No emitas la señal de inicio
hasta que la creación sea aceptada.

## 3. Señaliza el escalado

Publica `escalation_started` con la sesión y el mismo entorno del run cuando el
contrato del workflow lo requiera. La señal no transporta transcript ni
credenciales.

Si la creación falla, aplica el fallback aprobado y registra un error controlado;
no anuncies que un agente está disponible.

## 4. Devuelve respuestas humanas

Configura el webhook saliente de la sesión y prueba este orden:

1. el agente responde en TeLeo;
2. TeLeo guarda la respuesta pública;
3. el webhook recibe la respuesta y la correlación;
4. el workflow la entrega al cliente;
5. una nota privada queda fuera de la entrega.

Un fallo de webhook no debe borrar la respuesta ni generar un segundo ticket.

## 5. Añade mensajes posteriores

Usa `POST /api/hr/tickets/{session_id}/messages` o la actualización pública
correspondiente con el mismo identificador. No crees un ticket nuevo por cada
mensaje. Si el agente no está disponible, deja que TeLeo aplique la regla de
cola; no asignes desde el workflow sin contrato.

## 6. Cierra o de-escala

Distingue:

* **Cierre:** final permanente iniciado por el agente según la configuración del
  ciclo.
* **De-escalado:** final del tramo humano y retorno al bot con
  `escalation_ended`.
* **Pendientes:** aparcamiento; no es cierre.
* **X de la UI:** cerrar la ventana; no es ninguna de las anteriores.

El workflow debe tratar cada señal como estado de ciclo, no como confirmación de
un resultado empresarial.

## 7. Reintenta y audita

* Usa la sesión estable para hacer idempotente la creación.
* Consulta antes de reenviar un mensaje sin confirmación.
* Registra método, ruta lógica, estado, correlación, entorno y latencia.
* Redacta headers de autenticación y cuerpos con PII.
* Separa fallos de TeLeo, HappyRobot, webhook y backend de negocio.
* Conserva una condición de rollback que deje disponible el fallback anterior.

## Checklist de aceptación

* \[ ] El ticket se crea sin agente conectado.
* \[ ] Repetir creación no duplica la atención.
* \[ ] El agente ve resumen e histórico mínimos.
* \[ ] Mensaje de cliente y respuesta de agente recorren el mismo ticket.
* \[ ] Nota privada no se entrega al cliente.
* \[ ] Webhook falla de forma observable sin perder mensajes.
* \[ ] Pendientes, cola, cierre y de-escalado producen estados distintos.
* \[ ] Se conserva correlación y entorno.
* \[ ] No se exponen secretos, tokens ni PII innecesaria.
* \[ ] UAT y aprobación de owners preceden a cualquier ampliación de tráfico.