Per il tuo sviluppatore
Questo capitolo non è per il titolare: è da girare a chi vi segue il gestionale o il sito. Serve a collegare l'assistente ai vostri sistemi, e richiede qualcuno che sappia scrivere codice.
Se non avete un gestionale da collegare, potete saltarlo del tutto: tutto il resto della piattaforma funziona benissimo senza.
Le tre cose che si possono fare
Leggere e scrivere dall'esterno. C'è un'interfaccia REST: il gestionale può elencare le conversazioni, leggere i messaggi, rispondere, creare contatti. Si autentica con una chiave che generi in questa pagina.
Essere avvisati in tempo reale. Invece di chiedere ogni minuto se è successo qualcosa, si registra un indirizzo del proprio sistema e riceve una notifica agli eventi che interessano: conversazione creata, messaggio ricevuto, conversazione passata a un operatore, contatto creato.
Far agire l'assistente sui vostri dati. Nella sezione Azioni si definiscono chiamate al gestionale che l'assistente può usare durante una conversazione: lo stato di un ordine, la disponibilità di uno slot. È la funzione che trasforma l'assistente da "sa rispondere" a "sa fare".
Le chiavi
Quando ne generi una, il valore compare una volta sola. Copialo subito in un posto sicuro: non è recuperabile, si può solo revocare e crearne una nuova.
Esiste l'opzione sola lettura: la chiave può leggere ma non modificare né inviare nulla. Se l'integrazione deve solo mostrare dati da qualche parte, usala — è la differenza tra un bug che sbaglia una schermata e un bug che scrive ai clienti.
Le notifiche in uscita: tre cose da sapere
La firma va verificata. Ogni notifica arriva con una firma calcolata sul corpo della richiesta e sul segreto mostrato accanto all'indirizzo registrato. Va verificata sul corpo grezzo, prima di interpretarlo come JSON: se lo si rilegge dopo averlo trasformato, la firma non torna mai. È l'errore più comune di questa integrazione.
Rispondete in fretta. Se il vostro sistema non risponde entro pochi secondi la consegna è considerata fallita. Riproviamo un paio di volte con attesa crescente, poi lasciamo perdere. Meglio accettare subito e lavorare dopo, che elaborare tutto prima di rispondere.
Può arrivare due volte. Su una rete non è possibile garantire che una notifica arrivi esattamente una volta. Ogni evento ha un identificativo: tenete traccia di quelli già visti e ignorate i doppioni, o vi ritroverete due ordini uguali.
Le azioni, e l'unica regola che conta
Un'azione è una chiamata al vostro sistema che l'assistente può fare da solo. Si definisce con un indirizzo, i parametri e il formato della richiesta.
La regola: il vostro endpoint deve tollerare di non ricevere un secondo tentativo. Le chiamate hanno un tempo massimo; se scade su un'operazione che scrive qualcosa, non riproviamo — apposta, per non creare doppioni. Il che significa che l'operazione va progettata per essere sicura anche se il risultato non torna indietro.
Se il vostro sistema è lento a rispondere, meglio che accetti la richiesta e la lavori dopo, invece di tenere aperta la connessione.
Da dove partire
Nella pagina c'è il collegamento alla documentazione completa, con gli esempi già compilati con i valori del vostro account. È il punto da cui far partire chi scrive il codice.