Azioni: risposte dal tuo sistema

Un'azione permette al tuo bot di cercare qualcosa nel tuo sistema nel mezzo di una chat — dov'è un ordine, quando sarà consegnato, se una prenotazione è confermata. Il cliente chiede, il bot raccoglie ciò che gli serve, chiama la tua API e risponde da ciò che riceve, nella lingua del cliente.

Funziona ovunque funzioni il tuo bot: il widget per sito web, il link del bot e il codice QR, e le app Android, iOS, React Native, Flutter e Ionic. Non viene installato né aggiornato nulla — la chiamata parte dai nostri server, quindi le credenziali della tua API non raggiungono mai un browser o un telefono.

Prima di iniziare: chiunque può chattare con il tuo bot

Il tuo bot è una chat pubblica. Se basta il numero d'ordine per vedere un ordine, chiunque può digitare numeri finché uno non funziona.

Il bot aiuta in tre modi, ma nessuno sostituisce quel controllo: invia solo i valori che il cliente ha davvero digitato, limita quante ricerche possono fare una chat o un indirizzo, e puoi scegliere quali campi della risposta può vedere.

Configurane una

Apri Azioni nella dashboard e scegli Nuova azione. Proprietari e amministratori possono vedere questa schermata.

• Nome — per te, ad esempio "Stato dell'ordine".
• Quando deve usarla il bot? — una frase, come la diresti a un nuovo collega: "Il cliente chiede dov'è il suo ordine o quando arriverà."
• Indirizzo della tua API — GET o POST, e un indirizzo https://. Scrivi {{order_id}} dove va un valore.
• Cosa il bot chiede al cliente — fino a sei valori. Ognuno ha un'etichetta con parole tue ("Numero ordine"), il nome usato dalla tua API (order_id) e un tipo: testo libero, un numero, un indirizzo email o un numero di telefono.
• Header — la tua chiave API o il tuo token. Conservati cifrati e mai più mostrati.
• Condividi con il bot solo questi campi — facoltativo. Elenca le parti della risposta che il bot può usare, come status, eta, items[].name. Tutto il resto viene scartato prima che l'AI lo veda.

Premi Test, digita dei valori di esempio e vedrai la richiesta inviata ed esattamente cosa riceverebbe il bot. Poi provala davvero nella schermata Test: "Dov'è il mio ordine 48213? La mia email è asha@example.com".

Cosa riceve la tua API

Con GET, i valori che hai inserito nell'indirizzo vengono compilati e gli altri aggiunti alla query string:

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

Con POST, i valori sono il body JSON:

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

Ogni richiesta porta con sé anche i tuoi header e questi:

Cosa restituire

Rispondi entro 8 secondi con JSON, o con una breve riga di testo semplice.

• 200 con i dati — il bot risponde da quelli. Tienili compatti e usa nomi di campo chiari: {"status":"shipped","eta":"2 October"} funziona meglio dei codici interni.
• 404 quando non c'è corrispondenza — il bot lo dice al cliente e gli chiede di controllare ciò che ha digitato.
• Qualsiasi altra cosa, o nessuna risposta in tempo — il bot si scusa, offre i tuoi contatti e la chat viene segnalata a te. Il motivo è mostrato nella schermata Azioni.

I redirect non vengono seguiti e una risposta oltre 256 KB non viene letta.

Verifica la firma

Le richieste sono firmate secondo lo standard Standard Webhooks, così puoi usare una libreria esistente. Il tuo segreto di firma è nella schermata Azioni.

A mano: unisci l'id, il timestamp e il body esatto con dei punti, firma il risultato con HMAC-SHA256 usando il segreto (la parte dopo whsec_, decodificata da base64) e confronta.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

Per una richiesta GET il body è vuoto, quindi il testo firmato termina con un punto. Usa POST se vuoi che anche i valori siano coperti dalla firma.

Come la usa il bot

• Chiede tutto ciò che manca, una breve domanda alla volta, e ricorda ciò che il cliente ha detto prima nella chat.
• Non indovina mai un valore. Se il cliente non l'ha digitato, il bot lo chiede.
• Una ricerca per messaggio. Le tue risposte salvate hanno comunque la precedenza, quindi una domanda a cui hai risposto a mano non chiama mai la tua API.
• Le risposte di una ricerca non vengono mai riutilizzate per un altro cliente.
• Una ricerca conta come una risposta, come qualsiasi altra risposta scritta dall'AI.

In Chat, una risposta arrivata da una ricerca lo indica sotto: quale azione è stata eseguita e come è andata. I valori digitati dal cliente restano nella trascrizione e in nessun altro posto.

Limiti

Le azioni leggono informazioni. Non puntarne una a un indirizzo che modifica qualcosa — annullare un ordine o emettere un rimborso richiede un passaggio di conferma che il bot non ha ancora.