Creare una nuova Action

La creazione di una nuova Action richiede la configurazione di diversi elementi: l'endpoint da chiamare, i parametri necessari, il metodo HTTP e la gestione della risposta. Il processo è guidato e non richiede competenze di programmazione avanzate.

Accesso alla creazione Actions

1. Dal pannello principale, clicca su "Actions" nel menu
2. Se non hai ancora Actions, vedrai il pulsante "Crea la tua prima Action"
3. Se hai già altre Actions, clicca su "Crea Nuova Action"
4. Si aprirà il modulo di configurazione guidata

Informazioni base richieste

Nome dell'Action

• Scopo: Identificare chiaramente l'azione per te e per l'assistente
• Esempi efficaci:
  • "Crea ticket supporto"
  • "Invia email benvenuto"
  • "Controlla disponibilità prodotto"
  • "Prenota appuntamento"
• Consigli: Usa nomi descriptivi che indicano chiaramente cosa fa l'Action

Descrizione dell'Action

• Importanza: L'AI utilizza questa descrizione per capire quando usare l'Action
• Cosa includere:
  • Quando deve essere utilizzata
  • Che tipo di problemi risolve
  • Quali informazioni sono necessarie
• Esempio: "Utilizza questa Action quando l'utente vuole segnalare un problema tecnico o richiedere assistenza. Richiede: email utente, descrizione problema, categoria del problema."

Configurazione URL e metodo

URL dell'endpoint

• Formato: URL completo dell'API da chiamare
• Esempi:
  • https://api.mioservizio.com/tickets
  • https://miosito.com/api/appointments
  • https://webhook.example.com/contact
• Requisiti: L'URL deve essere accessibile pubblicamente e supportare HTTPS

Metodo HTTP

• GET: Per recuperare informazioni (es. controllo disponibilità)
• POST: Per creare nuove risorse (es. nuovo ticket, nuovo contatto)
• PUT: Per aggiornare risorse esistenti
• DELETE: Per eliminare risorse (uso meno common)

Gestione dell'autenticazione

Tipi di autenticazione supportati

• API Key nell'header: Più sicuro, chiave nell'header HTTP
• API Key nel URL: Meno sicuro ma più semplice
• Bearer Token: Token JWT o simili nell'header Authorization
• Basic Auth: Username e password codificati

Configurazione sicura

• Non hardcodare credenziali: Usa i campi dedicati per API key
• Usa HTTPS sempre: Non inviare mai credenziali su HTTP
• Rotazione chiavi: Cambia periodicamente le API key
• Permessi minimi: Concedi solo i permessi strettamente necessari

Processo di creazione step-by-step

Step 1: Informazioni base

1. Inserisci nome Action descrittivo
2. Scrivi descrizione dettagliata per l'AI
3. Seleziona la tipologia (se disponibili template)

Step 2: Configurazione endpoint

1. Inserisci URL completo dell'API
2. Seleziona metodo HTTP appropriato
3. Configura headers necessari (Content-Type, etc.)

Step 3: Autenticazione

1. Scegli il tipo di autenticazione
2. Inserisci credenziali nei campi sicuri
3. Testa la connessione se possibile

Step 4: Parametri

1. Definisci i parametri che l'Action deve raccogliere
2. Specifica quali sono obbligatori e quali opzionali
3. Imposta valori di default dove appropriato

Step 5: Test e validazione

1. Utilizza la funzione di test integrata
2. Verifica che la risposta sia quella attesa
3. Controlla la gestione degli errori

Esempi pratici di configurazione

Action per invio email

Action per creazione ticket

Errori comuni da evitare

• URL non accessibili: Verifica che l'endpoint sia raggiungibile pubblicamente
• Autenticazione errata: Testa sempre le credenziali prima di salvare
• Parametri mancanti: Assicurati di definire tutti i parametri necessari
• Descrizioni vaghe: L'AI ha bisogno di istruzioni precise per usare correttamente l'Action
• Mancanza di gestione errori: Prevedi cosa fare se l'API esterna non risponde

Best practices

• Inizia semplice: Crea prima Actions per casi d'uso semplici
• Testa abbondantemente: Verifica tutti i possibili scenari
• Documenta tutto: Mantieni note su come funziona ogni Action
• Monitora l'utilizzo: Controlla regolarmente che le Actions funzionino correttamente
• Backup delle configurazioni: Salva le impostazioni importanti