Blocco API - Chiama API esterne dal flusso del tuo chatbot

Panoramica

Il Blocco API permette al tuo chatbot di chiamare qualsiasi API REST esterna durante la conversazione, catturare la risposta e instradare il flusso in base al successo o al fallimento. Usalo per cercare ordini nel tuo database, verificare OTP, recuperare lo stato delle spedizioni, controllare i saldi degli account o integrare qualsiasi sistema che esponga un endpoint HTTP.

Quando il bot raggiunge un blocco API, invia la richiesta HTTP configurata, attende la risposta, estrae i campi dal body JSON o XML in variabili, poi segue il ramo di successo (HTTP 2xx/3xx) o il ramo di fallimento (HTTP 4xx/5xx). I blocchi successivi nel flusso possono usare le variabili estratte in messaggi, condizioni o chiamate API successive.

Dove trovarlo

1. Apri il tuo chatbot in Studio
2. Trascina il blocco API dalla barra laterale sinistra sulla canvas
3. Collegalo da un blocco precedente qualsiasi
4. Fai doppio clic sul blocco per configurarlo

Il blocco API ha due connessioni di output: Successo (in alto/predefinita) per le risposte 2xx e 3xx, e Fallimento (secondaria) per le risposte 4xx e 5xx.

Configurazione

Passaggio 1: Imposta l'URL e il metodo della richiesta

Campo	Descrizione
URL	L'endpoint completo, per esempio https://api.example.com/orders/{order_id}
Metodo	Verbo HTTP: GET, POST, PUT, PATCH o DELETE

Puoi inserire qualsiasi variabile catturata in precedenza nel flusso usando la sintassi {variable_name} (parentesi graffe singole). Le variabili vengono risolte in fase di esecuzione prima dell'invio della richiesta.

Passaggio 2: Aggiungi parametri di query (facoltativo)

Per le richieste GET, usa i Parametri di query per aggiungere coppie chiave-valore all'URL. Ogni riga prevede una Chiave e un Valore. La sostituzione delle variabili funziona in entrambi i campi.

Key: customer_email       Value: {email}
Key: include_archived     Value: false

Passaggio 3: Configura gli header

Aggiungi header HTTP personalizzati nella sezione Header. Ogni riga prevede una Chiave e un Valore.

Key: Content-Type         Value: application/json
Key: Accept               Value: application/json
Key: X-Custom-Header      Value: {tenant_id}

Content-Type viene rilevato automaticamente quando scegli un formato del body, ma puoi sovrascriverlo.

Passaggio 4: Aggiungi l'autenticazione

Il blocco API supporta tre modalità di autenticazione. Scegline una adatta all'API di destinazione.

Tipo di autenticazione	Campi	Come viene inviata
Basic Auth	Username, Password	Inviata come Authorization: Basic <base64>
Bearer Token	Bearer Token	Inviato come Authorization: Bearer <token>
Custom Header	Nome header, Valore header	Inviato come <Name>: <Value> (per chiavi API, schemi personalizzati)

Nota: Per le API che usano x-api-key o simili, scegli Custom Header e imposta Name su x-api-key e Value sulla tua chiave. Puoi anche memorizzare la chiave in una variabile e referenziarla come {api_key}.

Passaggio 5: Costruisci il body della richiesta

Per le richieste POST, PUT e PATCH, configura il body nella sezione Body. Scegli il formato:

Formato	Usa quando
JSON	La maggior parte delle API REST moderne
XML	Endpoint SOAP o XML legacy
Nessuno	Nessun body necessario (tipico per GET e DELETE)

Scrivi il JSON o l'XML grezzo nell'editor del body. Le variabili possono essere inserite inline:

{
  "order_id": "{order_id}",
  "customer": {
    "name": "{name}",
    "email": "{email}"
  },
  "total": {amount}
}

Passaggio 6: Mappa la risposta in variabili

In Salva risposta in variabili, definisci come estrarre i campi dalla risposta JSON in variabili di flusso.

Percorso JSON	Nome variabile
result.user.name	user_name
data.orders[0].status	order_status
items[*].id	item_ids

Sintassi dei percorsi supportata:

• Notazione con punto per oggetti annidati: result.user.email
• Indice di array: items[0].name
• Estrazione con wildcard dall'array: items[*].id restituisce tutti gli ID come array
• Campo radice: status o message

I valori estratti sono disponibili in tutti i blocchi successivi come {variable_name}.

Passaggio 7: Invia e salva

Clicca su Invia nel modale del blocco, poi salva il flusso usando Salva modifiche nella barra superiore.

Come viene gestita la risposta

Percorso di successo (HTTP 2xx / 3xx)

1. Le variabili da Salva risposta in variabili vengono popolate
2. Il flusso segue la connessione di output Successo

Percorso di fallimento (HTTP 4xx / 5xx)

1. Le variabili di risposta possono o meno popolarsi a seconda del body dell'errore
2. Il flusso segue la connessione di output Fallimento
3. Usa questo ramo per inviare un messaggio di errore amichevole o riprovare

Timeout

Le richieste vanno in timeout dopo 30 secondi. Se la tua API è lenta, considera di suddividere il lavoro in due passaggi o di usare un pattern asincrono guidato da webhook.

Test nell'API Playground

Ogni chiamata del blocco API viene registrata ed è disponibile nell'API Playground all'interno di Studio. Per ogni esecuzione di test puoi vedere:

• L'URL completamente risolto, il metodo e gli header
• Il body della richiesta che è stato inviato
• Il codice di stato HTTP ricevuto
• Il body completo della risposta
• Le variabili che sono state estratte

Usa il playground per fare il debug di variabili template, autenticazione e mappature dei percorsi JSON prima di mettere in produzione il flusso.

Best practice

• Memorizza i segreti in variabili, non nella configurazione del blocco. Acquisisci le chiavi API da impostazioni specifiche dell'ambiente e passale tramite variabili così che lo stesso flusso funzioni in staging e produzione
• Configura sempre il ramo di Fallimento. Non dare mai per scontato che la chiamata API abbia successo. Invia un messaggio di fallback come "Non siamo riusciti a recuperare il tuo ordine in questo momento. Riprova più tardi."
• Mantieni piccoli i body delle richieste. Non inviare intere cronologie di chat o payload di grandi dimensioni a meno che l'API non ne abbia bisogno
• Valida i campi della risposta prima di usarli. Se order_status potrebbe mancare, aggiungi un blocco Condizione dopo la chiamata API per controllare {order_status} prima di usarlo in un messaggio
• Usa nomi di variabili descrittivi. user_email è meglio di val1 perché è più facile da debuggare nel Playground e nel log della conversazione
• Imposta esplicitamente Content-Type quando invii JSON, così che le API rigorose accettino la richiesta

Casi d'uso comuni

Ricerca ordine

Il cliente fornisce un ID ordine, il bot recupera lo stato dal tuo backend e-commerce.

• Metodo: GET
• URL: https://api.myshop.com/orders/{order_id}
• Autenticazione: Bearer Token
• Mappa risposta: data.status su order_status, data.tracking_url su tracking_url

Verifica OTP

Il bot raccoglie un codice di 6 cifre, chiama il tuo endpoint di verifica e si dirama in base al risultato.

• Metodo: POST
• URL: https://api.myapp.com/verify-otp/
• Body: {"phone": "{phone}", "code": "{otp_code}"}
• Mappa risposta: verified su otp_verified
• Usa poi un blocco Condizione: se {otp_verified} == true continua, altrimenti richiedi di nuovo

Sincronizzazione contatto CRM

Invia i dettagli di contatto raccolti al tuo CRM quando l'utente completa la qualificazione.

• Metodo: POST
• URL: https://api.crm.com/v1/contacts/
• Autenticazione: Custom Header (x-api-key: {crm_key})
• Body: {"name": "{name}", "email": "{email}", "source": "chatbot"}

Risoluzione dei problemi

La richiesta fallisce con 401 Unauthorized

1. Controlla che il tipo di autenticazione corrisponda a ciò che l'API si aspetta
2. Per i Bearer token, non includere la parola Bearer nel campo del token. Il blocco la aggiunge automaticamente
3. Per l'autenticazione Custom Header, verifica che il nome dell'header corrisponda esattamente alla documentazione dell'API (sensibile alle maiuscole per alcune API)
4. Ispeziona la richiesta nell'API Playground per confermare che l'header venga inviato

Le variabili non si popolano dalla risposta

1. Apri l'API Playground e ispeziona il body effettivo della risposta
2. Conferma che il percorso JSON corrisponda alla struttura della risposta. I percorsi sono sensibili alle maiuscole
3. Per gli array, usa items[0].field per un singolo valore o items[*].field per tutti i valori
4. Se la risposta è XML, assicurati di aver impostato correttamente il formato del body. I percorsi JSON funzionano anche sull'XML analizzato

Il flusso segue il ramo di fallimento anche quando l'API funziona

1. Controlla il codice di stato HTTP nell'API Playground. Alcune API restituiscono 201 (Created) su POST, che è comunque un successo
2. Se l'API restituisce 200 ma con un errore nel body, usa un blocco Condizione dopo il ramo di successo per ispezionare il campo della risposta

La richiesta va in timeout

1. Il timeout è fissato a 30 secondi. Se la tua API impiega regolarmente più tempo, l'API potrebbe non essere adatta alla chat in tempo reale
2. Considera di spostare il lavoro lento in un job in background e fare polling per il risultato, oppure usa un webhook per essere notificato quando è pronto

Le variabili template appaiono come {variable} grezzo nella richiesta

1. Conferma che la variabile sia stata impostata da un blocco precedente nel flusso
2. Controlla l'ortografia del nome della variabile (sensibile alle maiuscole)
3. Usa il log della conversazione per ispezionare quali variabili sono effettivamente popolate in quel punto

Prossimi passi

• Blocco Webhook - Ricevi chiamate HTTP in entrata per attivare o riprendere un flusso
• Blocco Fine conversazione - Termina le conversazioni con un pulsante di riavvio
• Panoramica di Studio - Esplora tutti i tipi di blocco e le funzionalità del flow builder