AI Actions

AI Actions

As AI Actions estendem as capacidades do seu Agente de IA para além de responder perguntas a partir da Base de Conhecimento. Elas permitem definir comportamentos acionados — coisas que a IA deve fazer quando detecta situações específicas em uma conversa.

O que as AI Actions fazem:

• HTTP Request Actions — Chamam APIs externas quando acionadas. Por exemplo, verificar o status de um pedido no seu backend, criar um ticket de suporte ou consultar informações de conta — tudo durante a conversa.
• Ações MCP: Conectam-se a servidores Model Context Protocol para integrações avançadas de ferramentas (ex.: consultas de produtos da Shopify, queries personalizadas a bancos de dados).

Casos de uso típicos:

• Consultar informações em tempo real (status de pedido, detalhes de conta, estoque) nos seus sistemas de backend durante as conversas
• Criar tickets, atualizar registros de CRM ou disparar workflows em sistemas externos com base no contexto da conversa
• Fornecer recomendações personalizadas consultando seu catálogo de produtos

Cada action tem um name, uma description (nas HTTP Request Actions, a descrição informa à IA quando acioná-la) e uma configuração específica do tipo. As actions podem ser ativadas/desativadas individualmente via API. As actions são criadas e totalmente configuradas no Dashboard do Quickchat — a API oferece operações de listagem, atualização (ativar/desativar) e exclusão, além de endpoints dedicados para criar e configurar Ações 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 da AI Action
name string	Nome de exibição
description string	Quando a action é acionada
is_active boolean	Se está ativada
type string	"http_request", "remote_mcp", "shopify_remote_mcp" ou "knowledge_base"
icon string or null	Identificador do ícone
icon_color string or null	Cor do ícone
is_valid boolean	Se está configurada corretamente

Update AI Action

Scope: write_all

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

Request Body

Parameter	Description
is_active boolean	Ativar/desativar a action
icon string	Identificador do ícone (máx. 200 caracteres)
icon_color string	Cor do ícone (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 — Retorna o snapshot atualizado da 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 (corpo vazio)

Create MCP Action

Scope: write_all

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

Conecta um servidor MCP remoto ao seu Agente de IA como uma Ação MCP. Requer um token de API com o scope write_all (tokens de API exigem o plano Business ou superior).

Request Body

Parameter	Description
remote_mcp_url string, required	A URL do servidor MCP. Deve usar https://; URLs que resolvem para endereços de rede privados ou internos são rejeitadas
headers array, required	Cabeçalhos de conexão enviados ao servidor, ex.: um token Authorization estático. Cada entrada é {"id", "name", "value"} — escolha qualquer string única como id. Envie [] se o servidor não precisar de nenhum
allowed_tools array, required	Interruptores por ferramenta, cada um {"name", "is_active"}. Envie [] para deixar a disponibilidade das ferramentas a cargo de default_tool_is_active
name string	Nome exibido na lista de Ações (máx. 100 caracteres). O padrão é um rótulo derivado do host do servidor
description string	Descrição exibida na lista de Ações (máx. 2500 caracteres)
icon string	Identificador do ícone (máx. 200 caracteres)
icon_color string	Cor do ícone (máx. 50 caracteres)

name e description são rótulos para operadores: identificam a ação no dashboard, e a IA nunca os lê. A IA trabalha com as descrições de ferramentas publicadas pelo próprio 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	A URL do servidor MCP conectado
default_tool_is_active boolean	Se as ferramentas ausentes de allowed_tools podem ser usadas
allowed_tools array	Interruptores por ferramenta, {"name", "is_active"}
headers array	Cabeçalhos de conexão armazenados
remote_mcp_auth_token string or null	Campo legado para um token estático. Não pode ser definido por esta API — passe as credenciais via headers
oauth object or null	Status de autorização dos servidores conectados com login OAuth (null caso contrário)
recommended_tools array	Nomes de ferramentas que a Quickchat recomenda para servidores com um perfil ajustado pela Quickchat (somente leitura)
validation_issues array	Nomes das verificações de configuração que falharam; vazio quando is_valid é true

Os demais campos correspondem a List All AI Actions.

A action é criada com is_active: false. Para servidores sem um perfil ajustado pela Quickchat, ela também começa com default_tool_is_active: true, então toda ferramenta descoberta no momento da resposta fica permitida até você restringi-la. Para ligar a action, use o endpoint Update AI Action acima: PATCH /v1/api/ai_actions/{action_id} com {"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 — Retorna a configuração específica de MCP, no mesmo formato da resposta de criação acima.

Update MCP Action Configuration

Scope: write_all

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

Todos os campos são opcionais; apenas os campos enviados mudam.

Request Body

Parameter	Description
remote_mcp_url string	Nova URL do servidor (validada como na criação). Mudar a URL de um servidor conectado com OAuth apaga a autorização armazenada e desliga a action
headers array	Substitui os cabeçalhos de conexão
allowed_tools array	Substitui os interruptores por ferramenta, cada um {"name", "is_active"}
default_tool_is_active boolean	Se as ferramentas ausentes de allowed_tools podem ser usadas
name string	Nome exibido (máx. 100 caracteres)
description string	Descrição exibida na lista de Ações (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 — Retorna a Ação MCP atualizada, no mesmo formato da resposta de criação.

Nota

O teste de conexão e a descoberta de ferramentas — a verificação Connect do dashboard — não estão disponíveis na API pública. O dashboard executa a verificação automaticamente quando você conecta ou reconecta um servidor, e servidores protegidos por OAuth precisam concluir a autorização no dashboard; o campo oauth das respostas acima informa esse status.

---