Documentazione

API Personalizzata

Chiama API esterne dal tuo agente per recuperare dati o attivare integrazioni.

Le azioni API personalizzate permettono al tuo agente di interagire con servizi esterni. Recupera dati in tempo reale, invia moduli o attiva flussi di lavoro in altri strumenti.

Creazione di un'Azione API Personalizzata

  1. Vai alla scheda Azioni del tuo agente
  2. Clicca su Crea azione → API Personalizzata
  3. Configura la chiamata API:
    • URL dell'Endpoint - L'endpoint API da chiamare
    • Metodo HTTP - GET, POST, PUT, PATCH o DELETE
    • Header - Autenticazione e content-type
    • Corpo della Richiesta - Dati da inviare (per POST/PUT/PATCH)
  4. Salva e testa

Opzioni di Configurazione

URL dell'Endpoint

L'URL completo dell'endpoint API:

https://api.yourservice.com/v1/data

Usa solo endpoint HTTPS. Gli endpoint HTTP sono bloccati per motivi di sicurezza.

Metodo HTTP

MetodoCaso d'Uso
GETRecupera dati da un servizio esterno
POSTInvia dati, crea record
PUTSostituisce record esistenti
PATCHAggiorna parzialmente record esistenti
DELETERimuove record

Aggiungi gli header di autenticazione e content-type:

Authorization: Bearer {{SECRET:service_api_key}}
Content-Type: application/json

Crea il segreto con nome separatamente. Agentkit risolve {{SECRET:name}} solo sul server. Le letture delle azioni e i log non includono mai il valore memorizzato.

Origine dei dati di input

Per un campo di testo con un solo indirizzo email, scegli l'email verificata con richiesta se non disponibile. Agentkit usa il contatto web verificato o il mittente del messaggio in arrivo. Ai visitatori anonimi chiede l'indirizzo. Il modello non può sostituire un indirizzo verificato.

Corpo della Richiesta

Per le richieste POST/PUT, definisci il corpo JSON con i dati che vuoi inviare.

Quando Viene Chiamata l'API

L'AI decide quando chiamare l'API in base al contesto della conversazione e alla descrizione dell'azione. Puoi guidare questo comportamento fornendo una descrizione chiara di quando l'azione deve essere attivata.

Gestione delle Risposte

Risposta di Successo

Quando l'API risponde con successo (stato 2xx):

  • Mostra un messaggio di successo al visitatore
  • Includi i dati della risposta nella chat
  • Attiva azioni di follow-up

Gestione degli Errori

Quando l'API fallisce:

  • Mostra un messaggio di errore chiaro
  • Registra l'errore nei log per il debug
  • Ripeti la richiesta facoltativamente

Casi d'Uso di Esempio

Verifica Stato Ordine

Configura un endpoint GET per recuperare i dati dell'ordine quando i visitatori chiedono informazioni sullo stato del loro ordine.

Invia al CRM

Configura un endpoint POST per inviare i dati dei lead al tuo sistema CRM.

Ottieni Dati in Tempo Reale

Configura un endpoint GET per recuperare dati in tempo reale (come disponibilità o inventario) dai tuoi sistemi.

Considerazioni sulla Sicurezza

Chiavi API

  • Memorizza le chiavi API come segreti con nome e usa riferimenti {{SECRET:name}}.
  • Usa chiavi specifiche per ambiente durante i test
  • Ruota le chiavi periodicamente

Rate Limiting

  • Le API esterne potrebbero avere limiti di frequenza
  • Configura di conseguenza il rate limiting del tuo agente
  • Monitora l'utilizzo dell'API nei log

Privacy dei Dati

  • Invia solo i dati necessari
  • Assicurati che i servizi esterni siano conformi al GDPR, se necessario
  • Non registrare nei log dati di risposta sensibili

Timeout e Tentativi

ImpostazionePredefinitoNote
Timeout20 secondiLa richiesta fallisce se non c'è risposta
Tentativi0Configura i tentativi dei webhook per maggiore affidabilità

Test della Tua Azione API

  1. Configura l'azione con un endpoint di test
  2. Vai al Playground
  3. Attiva l'azione con l'input appropriato
  4. Controlla la risposta in chat
  5. Rivedi i log per il debug

Prossimi Passi