AI Actions

AI Actions

Las AI Actions amplían las capacidades de tu Agente de IA más allá de responder preguntas a partir de la Base de Conocimiento. Te permiten definir comportamientos activados: cosas que la IA debe hacer cuando detecta situaciones específicas en una conversación.

Qué hacen las AI Actions:

• HTTP Request Actions — Llaman a APIs externas cuando se activan. Por ejemplo, comprobar el estado de un pedido en tu backend, crear un ticket de soporte o consultar información de una cuenta, todo durante la conversación.
• Acciones MCP: Se conectan a servidores Model Context Protocol para integraciones de herramientas avanzadas (p. ej., búsquedas de productos en Shopify, consultas a bases de datos personalizadas).

Casos de uso típicos:

• Consultar información en tiempo real (estado de pedidos, detalles de cuenta, inventario) desde tus sistemas backend durante las conversaciones
• Crear tickets, actualizar registros de CRM o disparar flujos de trabajo en sistemas externos según el contexto de la conversación
• Ofrecer recomendaciones personalizadas consultando tu catálogo de productos

Cada action tiene un name, una description (en las HTTP Request Actions, la descripción indica a la IA cuándo activarla) y una configuración específica del tipo. Las actions pueden activarse/desactivarse individualmente mediante la API. Las actions se crean y configuran por completo en el Dashboard de Quickchat; la API ofrece operaciones de listar, actualizar (activar/desactivar) y eliminar, además de endpoints dedicados para crear y configurar Acciones MCP.

List All AI Actions

Scope: read_all

GET https://app.quickchat.ai/v1/api/ai_actions

Shell

curl https://app.quickchat.ai/v1/api/ai_actions \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/ai_actions",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

[
  {
    "id": 1,
    "name": "Check Order Status",
    "description": "Look up order status when customer asks about their order.",
    "is_active": true,
    "type": "http_request",
    "icon": null,
    "icon_color": null,
    "is_valid": true
  }
]

Field	Description
id integer	Identificador de la AI Action
name string	Nombre visible
description string	Cuándo se activa la action
is_active boolean	Si está activada
type string	"http_request", "remote_mcp", "shopify_remote_mcp" o "knowledge_base"
icon string or null	Identificador del icono
icon_color string or null	Color del icono
is_valid boolean	Si está correctamente configurada

Update AI Action

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/ai_actions/{action_id}

Request Body

Parameter	Description
is_active boolean	Activar/desactivar la action
icon string	Identificador del icono (máx. 200 caracteres)
icon_color string	Color del icono (máx. 50 caracteres)

Shell

curl -X PATCH https://app.quickchat.ai/v1/api/ai_actions/1 \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"is_active": false}'

Python

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/ai_actions/1",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={"is_active": False},
)
data = response.json()

Response 200 OK — Devuelve el snapshot actualizado de la AI Action.

Delete AI Action

Scope: write_all

DELETE https://app.quickchat.ai/v1/api/ai_actions/{action_id}

Shell

curl -X DELETE https://app.quickchat.ai/v1/api/ai_actions/1 \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/ai_actions/1",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)

Response 200 OK (cuerpo vacío)

Create MCP Action

Scope: write_all

POST https://app.quickchat.ai/v1/api/ai_actions/remote_mcp

Conecta un servidor MCP remoto a tu Agente de IA como una Acción MCP. Requiere un token de API con el scope write_all (los tokens de API requieren el plan Business o superior).

Request Body

Parameter	Description
remote_mcp_url string, required	La URL del servidor MCP. Debe usar https://; se rechazan las URL que resuelven a direcciones de red privadas o internas
headers array, required	Cabeceras de conexión enviadas al servidor, p. ej. un token Authorization estático. Cada entrada es {"id", "name", "value"}: elige cualquier cadena única como id. Envía [] si el servidor no necesita ninguna
allowed_tools array, required	Interruptores por herramienta, cada uno {"name", "is_active"}. Envía [] para dejar la disponibilidad de herramientas en manos de default_tool_is_active
name string	Nombre mostrado en la lista de Acciones (máx. 100 caracteres). Por defecto, una etiqueta derivada del host del servidor
description string	Descripción mostrada en la lista de Acciones (máx. 2500 caracteres)
icon string	Identificador del icono (máx. 200 caracteres)
icon_color string	Color del icono (máx. 50 caracteres)

name y description son etiquetas para operadores: identifican la acción en el dashboard, y la IA nunca las lee. La IA trabaja con las descripciones de herramientas que publica el propio servidor MCP.

Shell

curl -X POST https://app.quickchat.ai/v1/api/ai_actions/remote_mcp \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "remote_mcp_url": "https://mcp.example.com/mcp",
    "headers": [
      {"id": "h-1", "name": "Authorization", "value": "Bearer <SERVER_TOKEN>"}
    ],
    "allowed_tools": [],
    "name": "Example MCP"
  }'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/ai_actions/remote_mcp",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "remote_mcp_url": "https://mcp.example.com/mcp",
        "headers": [
            {"id": "h-1", "name": "Authorization", "value": "Bearer <SERVER_TOKEN>"}
        ],
        "allowed_tools": [],
        "name": "Example MCP",
    },
)
data = response.json()

Response 201 Created

{
  "id": 2,
  "name": "Example MCP",
  "description": "Connected MCP server",
  "is_active": false,
  "type": "remote_mcp",
  "icon": "FaMixcloud",
  "icon_color": "#EF4444",
  "is_valid": true,
  "validation_issues": [],
  "remote_mcp_url": "https://mcp.example.com/mcp",
  "remote_mcp_auth_token": "",
  "default_tool_is_active": true,
  "allowed_tools": [],
  "headers": [
    {"id": 10, "name": "Authorization", "value": "Bearer <SERVER_TOKEN>"}
  ],
  "oauth": null,
  "recommended_tools": []
}

Field	Description
remote_mcp_url string	La URL del servidor MCP conectado
default_tool_is_active boolean	Si pueden usarse las herramientas que no aparecen en allowed_tools
allowed_tools array	Interruptores por herramienta, {"name", "is_active"}
headers array	Cabeceras de conexión almacenadas
remote_mcp_auth_token string or null	Campo heredado para un token estático. No puede establecerse mediante esta API; pasa las credenciales a través de headers
oauth object or null	Estado de autorización de los servidores conectados con inicio de sesión OAuth (null en caso contrario)
recommended_tools array	Nombres de herramientas que Quickchat recomienda para servidores con un perfil ajustado por Quickchat (solo lectura)
validation_issues array	Nombres de las comprobaciones de configuración fallidas; vacío cuando is_valid es true

El resto de campos coincide con List All AI Actions.

La action se crea con is_active: false. En los servidores sin un perfil ajustado por Quickchat también empieza con default_tool_is_active: true, de modo que toda herramienta descubierta al responder está permitida hasta que la restrinjas. Para encender la action, usa el endpoint Update AI Action de más arriba: PATCH /v1/api/ai_actions/{action_id} con {"is_active": true}.

Get MCP Action Configuration

Scope: read_all

GET https://app.quickchat.ai/v1/api/ai_actions/{action_id}/remote_mcp

Shell

curl https://app.quickchat.ai/v1/api/ai_actions/2/remote_mcp \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/ai_actions/2/remote_mcp",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK — Devuelve la configuración específica de MCP, con la misma forma que la respuesta de creación anterior.

Update MCP Action Configuration

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/ai_actions/{action_id}/remote_mcp

Todos los campos son opcionales; solo cambian los campos que envías.

Request Body

Parameter	Description
remote_mcp_url string	Nueva URL del servidor (validada como al crear). Cambiar la URL de un servidor conectado con OAuth borra la autorización almacenada y apaga la action
headers array	Sustituye las cabeceras de conexión
allowed_tools array	Sustituye los interruptores por herramienta, cada uno {"name", "is_active"}
default_tool_is_active boolean	Si pueden usarse las herramientas que no aparecen en allowed_tools
name string	Nombre mostrado (máx. 100 caracteres)
description string	Descripción mostrada en la lista de Acciones (máx. 2500 caracteres)

Shell

curl -X PATCH https://app.quickchat.ai/v1/api/ai_actions/2/remote_mcp \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "allowed_tools": [
      {"name": "search_docs", "is_active": true},
      {"name": "delete_page", "is_active": false}
    ],
    "default_tool_is_active": false
  }'

Python

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/ai_actions/2/remote_mcp",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "allowed_tools": [
            {"name": "search_docs", "is_active": True},
            {"name": "delete_page", "is_active": False},
        ],
        "default_tool_is_active": False,
    },
)
data = response.json()

Response 200 OK — Devuelve la Acción MCP actualizada, con la misma forma que la respuesta de creación.

Nota

La prueba de conexión y el descubrimiento de herramientas (la comprobación Connect del dashboard) no están disponibles en la API pública. El dashboard ejecuta la comprobación automáticamente cuando conectas o reconectas un servidor, y los servidores protegidos con OAuth deben completar su autorización en el dashboard; el campo oauth de las respuestas anteriores informa de ese estado.

---