Azioni AI

Gestisci le azioni AI del tuo agente tramite API.

Verifiche facoltative degli esempi

Visualizza un’anteprima delle corrispondenze JSONPath. Verifica percorsi radice, campi, indici di array e caratteri jolly rispetto al JSON fornito. Non esegue un’azione e non salva la memoria della conversazione.
Verifica una connessione MCP di esempio. Inizializza ed elenca gli strumenti soltanto sull’endpoint della documentazione Cloudflare o di Microsoft Learn. Non esegue accessi né strumenti.

In un browser compatibile, questi controlli sono disponibili anche come strumenti del sito. I link aprono i moduli standard.

Azioni AI

Le azioni AI estendono le capacità dell’agente oltre le risposte basate sulla base di conoscenza. Permettono di definire comportamenti attivati da condizioni: operazioni che l’AI deve eseguire quando rileva situazioni specifiche in una conversazione.

Cosa fanno le azioni AI:

Azioni di richiesta HTTP: chiamano API esterne quando vengono attivate. Per esempio, verificano lo stato di un ordine nel backend, creano un ticket di assistenza o cercano informazioni sull’account, tutto durante la conversazione.
Azioni MCP: si collegano a server Model Context Protocol per integrazioni avanzate con strumenti, per esempio ricerche di prodotti Shopify o query personalizzate a database.

Casi d’uso tipici:

Recuperare informazioni in tempo reale, come stato degli ordini, dettagli dell’account e disponibilità, dai sistemi backend durante le conversazioni
Creare ticket, aggiornare record CRM o attivare flussi in sistemi esterni in base al contesto della conversazione
Fornire consigli personalizzati interrogando il catalogo prodotti

Ogni azione ha un name, una description (per le azioni di richiesta HTTP la descrizione indica all’AI quando attivarla) e una configurazione specifica del tipo. Le azioni possono essere attivate o disattivate singolarmente tramite API. Vengono create e configurate completamente nella dashboard Quickchat: l’API offre operazioni di elenco, aggiornamento (attivazione/disattivazione) ed eliminazione, oltre a endpoint dedicati per creare e configurare le Azioni MCP.

Elencare tutte le azioni AI

Ambito: read_all

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

Shell
Python

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

import requests

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

Risposta 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
  }
]

Campo	Descrizione
`id` intero	Identificatore dell’azione AI
`name` stringa	Nome visualizzato
`description` stringa	Quando si attiva l’azione
`is_active` booleano	Indica se è attiva
`type` stringa	`"http_request"`, `"remote_mcp"`, `"shopify_remote_mcp"` o `"knowledge_base"`
`icon` stringa o null	Identificatore dell’icona
`icon_color` stringa o null	Colore dell’icona
`is_valid` booleano	Indica se è configurata correttamente

Aggiornare un’azione AI

Ambito: write_all

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

Corpo della richiesta

Parametro	Descrizione
`is_active` booleano	Attiva/disattiva l’azione
`icon` stringa	Identificatore dell’icona (massimo 200 caratteri)
`icon_color` stringa	Colore dell’icona (massimo 50 caratteri)

Shell
Python

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}'

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()

Risposta 200 OK: restituisce lo snapshot aggiornato dell’azione AI.

Eliminare un’azione AI

Ambito: write_all

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

Shell
Python

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

import requests

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

Risposta 200 OK (corpo vuoto)

Creare un’azione MCP

Ambito: write_all

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

Collega un server MCP remoto all’agente AI come Azione MCP. Richiede un token API con ambito write_all (i token API richiedono il piano Business o superiore).

Corpo della richiesta

Parametro	Descrizione
`remote_mcp_url` stringa, obbligatorio	URL del server MCP. Deve usare `https://`; vengono rifiutati gli URL che risolvono in indirizzi di rete privati o interni
`headers` array, obbligatorio	Header di connessione inviati al server, per esempio un token statico `Authorization`. Ogni voce è `{"id", "name", "value"}`: scegli una stringa univoca qualsiasi come `id`. Invia `[]` se il server non ne richiede
`allowed_tools` array, obbligatorio	Interruttori per singolo strumento, ciascuno `{"name", "is_active"}`. Invia `[]` per lasciare la disponibilità degli strumenti a `default_tool_is_active`
`name` stringa	Nome mostrato nell’elenco delle azioni (massimo 100 caratteri). Il valore predefinito è un’etichetta derivata dall’host del server
`description` stringa	Descrizione mostrata nell’elenco delle azioni (massimo 2500 caratteri)
`icon` stringa	Identificatore dell’icona (massimo 200 caratteri)
`icon_color` stringa	Colore dell’icona (massimo 50 caratteri)

name e description sono etichette per gli operatori: identificano l’azione nella dashboard e l’AI non le legge mai. L’AI usa le descrizioni degli strumenti pubblicate dal server MCP stesso.

Shell
Python

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"
  }'

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()

Risposta 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": []
}

Campo	Descrizione
`remote_mcp_url` stringa	URL del server MCP collegato
`default_tool_is_active` booleano	Indica se possono essere usati gli strumenti non elencati in `allowed_tools`
`allowed_tools` array	Interruttori per singolo strumento, `{"name", "is_active"}`
`headers` array	Header di connessione salvati
`remote_mcp_auth_token` stringa o null	Campo precedente per il token statico. Non può essere impostato tramite questa API: passa invece le credenziali tramite `headers`
`oauth` oggetto o null	Stato di autorizzazione dei server collegati tramite accesso OAuth (`null` negli altri casi)
`recommended_tools` array	Nomi degli strumenti consigliati da Quickchat per i server con un profilo curato (sola lettura)
`validation_issues` array	Nomi dei controlli di configurazione non superati; vuoto quando `is_valid` è `true`

Gli altri campi corrispondono a Elencare tutte le azioni AI.

L’azione viene creata con is_active: false. Per i server senza un profilo Quickchat curato, parte anche con default_tool_is_active: true, quindi ogni strumento scoperto al momento della risposta è consentito finché non lo limiti. Per attivare l’azione, usa l’endpoint Aggiornare un’azione AI sopra: PATCH /v1/api/ai_actions/{action_id} con {"is_active": true}.

Recuperare la configurazione di un’azione MCP

Ambito: read_all

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

Shell
Python

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

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()

Risposta 200 OK: restituisce la configurazione specifica MCP, nella stessa struttura della risposta di creazione sopra.

Aggiornare la configurazione di un’azione MCP

Ambito: write_all

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

Tutti i campi sono facoltativi; cambiano solo quelli che invii.

Corpo della richiesta

Parametro	Descrizione
`remote_mcp_url` stringa	Nuovo URL del server, convalidato come alla creazione. Cambiare l’URL di un server collegato tramite OAuth cancella l’autorizzazione salvata e disattiva l’azione
`headers` array	Sostituisce gli header di connessione
`allowed_tools` array	Sostituisce gli interruttori per singolo strumento, ciascuno `{"name", "is_active"}`
`default_tool_is_active` booleano	Indica se possono essere usati gli strumenti non elencati in `allowed_tools`
`name` stringa	Nome visualizzato (massimo 100 caratteri)
`description` stringa	Descrizione mostrata nell’elenco delle azioni (massimo 2500 caratteri)

Shell
Python

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
  }'

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()

Risposta 200 OK: restituisce l’azione MCP aggiornata, nella stessa struttura della risposta di creazione.

Il test della connessione e la scoperta degli strumenti, cioè la verifica Connetti nella dashboard, non sono disponibili nell’API pubblica. La dashboard esegue automaticamente la verifica quando colleghi o ricolleghi un server; i server protetti da OAuth devono completare l’autorizzazione nella dashboard. Il campo oauth delle risposte sopra ne indica lo stato.

Azioni AI

Verifiche facoltative degli esempi

Azioni AI

Elencare tutte le azioni AI

Aggiornare un’azione AI

Eliminare un’azione AI

Creare un’azione MCP

Recuperare la configurazione di un’azione MCP

Aggiornare la configurazione di un’azione MCP

Per iniziare

Agente AI

Actions

Conversazioni

Channels

Il tuo sito web

Helpdesk e CRM

App di messaggistica

Account e fatturazione

Per iniziare

Configurazione

Knowledge Base

Conversazioni