API de gestión del bot

Introducción

La API de gestión del bot te permite, desde tu propia plataforma o backend:

• Consultar el estado y la configuración de tu bot: nombre, estado, temperatura, emociones, idiomas, WhatsApp, instrucciones e intenciones con sus acciones.
• Ajustar un conjunto mínimo de opciones: nombre, temperatura, estado (apagar/encender/pendiente), idiomas y conversaciones de WhatsApp.

Esta API vive en el frontend de EasyChatBot (CodeIgniter) y usa su propia clave (ecb_mgmt_…), totalmente independiente de las claves del chat (ecb_sk_dev_… / ecb_sk_live_…). No consume tokens de chat.

Base URL:

Cada petición se autentica con la clave de gestión del bot. La clave funciona con el bot en INACTIVE, PENDING o RUNNING.

Cómo obtener la clave

1. Inicia sesión en el dashboard de EasyChatBot.
2. Ve a Mis Chatbots → bot correspondiente → Instalar.
3. En la sección «API de gestión del bot (clientes)» pulsa Generar clave.
4. La clave se muestra una sola vez (formato ecb_mgmt_…). Cópiala y guárdala en tu gestor de secretos.
5. Si la pierdes, puedes regenerarla desde el mismo modal; la regeneración revoca la clave anterior.

Autenticación y headers

Si la clave es inválida o está ausente obtendrás un 401 con {"success": false, "message": "…"}.

GET /api/v1/bot

Devuelve un snapshot de solo lectura con la configuración actual del bot.

Respuesta — éxito

{
  "success": true,
  "data": {
    "bot": {
      "id": 123,
      "name": "Mi bot de soporte",
      "status": "PENDING",
      "temperature": 0.7,
      "emotions": [
        { "code": "friendly", "label": "Amigable" }
      ],
      "languages": {
        "enabled": true,
        "all_languages": false,
        "languages": ["es", "en"],
        "catalog": [
          { "code": "es", "name": "Español" },
          { "code": "en", "name": "Inglés" }
        ]
      },
      "whatsapp": {
        "whatsapp_enabled": true
      }
    },
    "instructions": [
      { "text": "Responde siempre en tono cordial.", "channels": ["all"] }
    ],
    "intents": [
      {
        "id": 456,
        "title": "Consultar horarios",
        "detection_description": "Detecta preguntas sobre horarios",
        "enabled": true,
        "approved": false,
        "priority": 0,
        "action_type": "query_rewriting",
        "action_name": "query_rewriting",
        "config": null,
        "welcome_message": "¡Claro! Te ayudo con los horarios.",
        "completion_message": null,
        "allowed_channels": ["all"],
        "form_data": null
      }
    ]
  }
}

Los campos emotions, instructions e intents son de solo lectura: no se modifican con esta API.

PATCH /api/v1/bot

Actualización parcial: envía solo los campos que quieres cambiar. Se ignoran los que no se envían.

Sub-campos de languages

Respuesta — éxito tras actualizar

{
  "success": true,
  "message": "Bot actualizado correctamente",
  "data": {
    "bot": {
      "id": 123,
      "name": "Mi bot de soporte",
      "status": "RUNNING",
      "temperature": 0.5,
      "emotions": [
        { "code": "friendly", "label": "Amigable" }
      ],
      "languages": {
        "enabled": true,
        "all_languages": false,
        "languages": ["es", "en"],
        "catalog": []
      },
      "whatsapp": {
        "whatsapp_enabled": true
      }
    },
    "instructions": [],
    "intents": []
  }
}

Tras un status a INACTIVE, las intenciones MCP se desactivan automáticamente (mismo comportamiento que el dashboard).

Errores

Todos los errores usan el formato {"success": false, "message": "…"}.

Ejemplo de error de validación

{
  "success": false,
  "message": "El campo temperature debe ser un número entre 0 y 2."
}

Ejemplo de error de autenticación

{
  "success": false,
  "message": "Clave de gestión inválida o ausente."
}

Ejemplos con curl

Sustituye ecb_mgmt_xxxxxxxx por tu clave real.

1. Consultar el bot (lectura)

curl -H "Authorization: Bearer ecb_mgmt_xxxxxxxx" \
     https://www.easychatbot.app/api/v1/bot

2. Actualizar nombre, temperatura y estado

curl -X PATCH -H "Authorization: Bearer ecb_mgmt_xxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{"name":"Mi bot de soporte","temperature":0.5,"status":"RUNNING"}' \
     https://www.easychatbot.app/api/v1/bot

3. Activar detección de idiomas (solo español e inglés)

curl -X PATCH -H "Authorization: Bearer ecb_mgmt_xxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{"languages":{"enabled":true,"all_languages":false,"languages":["es","en"]}}' \
     https://www.easychatbot.app/api/v1/bot

4. Apagar las conversaciones por WhatsApp

curl -X PATCH -H "Authorization: Bearer ecb_mgmt_xxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{"whatsapp_enabled":false}' \
     https://www.easychatbot.app/api/v1/bot

Guía de instalación paso a paso

1. Genera la clave de gestión.
   Dashboard → Mis Chatbots → bot → Instalar → sección «API de gestión del bot (clientes)» → Generar clave. Guarda la clave ecb_mgmt_… en tu gestor de secretos (solo se muestra una vez).
2. Prueba con curl.
   Ejecuta el GET del paso 1 de la sección anterior. Deberías recibir {"success": true, "data": {…}} con el snapshot del bot.
3. Integra en tu backend.
   Almacena la clave en una variable de entorno (EASYCHATBOT_MGMT_API_KEY, por ejemplo). Al cargar tu plataforma, consulta el GET para mostrar el estado y la configuración de tu bot. Cuando el usuario guarde cambios, envía un PATCH con solo los campos modificados.
4. Gestiona la clave.
   Si sospechas que se filtró, regenérala en el dashboard: la clave anterior queda revocada inmediatamente.

Traza de cambios

Cada escritura con esta API queda registrada en la página de Uso del bot (tipo Configuración) con el origen API de gestión, indicando qué campo cambió y de qué valor a cuál. Esto te permite auditar quién (o qué sistema) modificó la configuración del bot.

Los cambios hechos desde el dashboard también se registran, identificando el usuario de la sesión.