botino/docs/env.md

Variables de entorno (Botino)

Variables usadas (runtime)

Core

• PORT: puerto del servidor (default 3000).
• TENANT_KEY: key por defecto para resolver tenant (default piaf).
• DATABASE_URL: conexión Postgres.
• PG_POOL_MAX: tamaño del pool (default 10).
• PG_IDLE_TIMEOUT_MS: idle timeout (default 30000).
• PG_CONN_TIMEOUT_MS: connection timeout (default 5000).
• APP_ENCRYPTION_KEY: clave para desencriptar credenciales Woo en Postgres (tenant_ecommerce_config).

OpenAI

• OPENAI_API_KEY (o OPENAI_APIKEY): API key.
• OPENAI_MODEL: modelo (default gpt-4o-mini).

Turn Engine

• TURN_ENGINE: motor de turnos. Valores:
  • v1 (default): pipeline actual (heurísticas + guardrails + LLM plan final).
  • v2: “LLM-first NLU, deterministic core” (nuevo motor detrás de feature flag).

WooCommerce (solo fallback si falta config por tenant)

• WOO_CONSUMER_KEY: consumer key (se usa solo si en tenant_ecommerce_config falta consumer_key).
• WOO_CONSUMER_SECRET: consumer secret (idem).

Evolution API (WhatsApp)

Variables para el envío de mensajes a WhatsApp via Evolution API.

• EVOLUTION_API_URL: URL base de Evolution API (ej: https://api.evolution.com).
• EVOLUTION_API_KEY: API key para autenticación (header apikey).
• EVOLUTION_INSTANCE_NAME: nombre de la instancia de WhatsApp (ej: piaf).
• EVOLUTION_SEND_ENABLED: habilita/deshabilita el envío real a WhatsApp.
  • 0 (default): Solo guarda mensajes en BD, NO envía a WhatsApp. Ideal para desarrollo/pruebas.
  • 1: Envía mensajes realmente a WhatsApp. Para producción.

Flujo:

1. Bot recibe mensaje de Evolution via webhook (/webhook/evolution)
2. Procesa el mensaje y genera respuesta
3. Guarda respuesta en BD (direction: "out")
4. Si EVOLUTION_SEND_ENABLED=1, envía respuesta a Evolution API → WhatsApp

Endpoint usado: POST {EVOLUTION_API_URL}/message/sendText/{instance}

Debug por temas (nuevo)

Todos aceptan 1/true/yes/on para activar.

• DEBUG_PERF: perf/timings (pipeline + webhook evolution).
• DEBUG_WOO_HTTP: requests/responses a Woo (status/timing/len).
• DEBUG_WOO_PRODUCTS: cache/búsquedas de productos Woo.
• DEBUG_LLM: requests/responses a OpenAI.
• DEBUG_EVOLUTION: logs del hook evolution (además de perf).
• DEBUG_DB: reservado para instrumentar queries DB (no está verboso aún).
• DEBUG_RESOLVE: debug de resolución/ambiguity (pipeline).

Notas importantes

• En producción multi-tenant, Woo se toma de Postgres (tenant_ecommerce_config). Si restaurás WordPress y cambian keys/base_url, tenés que actualizar esa tabla para el tenant correspondiente; no alcanza con regenerar keys en WP si Botino sigue leyendo las viejas desde Postgres.