Onboarding Cliente

Questa procedura descrive i passaggi necessari per creare una nuova organizzazione, aggiungere utenti, configurare scope e canali, e completare il deploy dell’infrastruttura associata. Nell'esempio indicato, verrà predisposto un canale che usa un Telegram Bot per la comunicazione e l'interazione.

1. Creazione dell’Organizzazione

L’organizzazione può essere creata in due modi:

  • Da interfaccia: attraverso il pannello di amministrazione.

  • Da API: eseguendo una chiamata POST all’endpoint:

POST /api/v1/organization

Body richiesto:

{
  "name": "Nome organizzazione"
}

2. (Opzionale) Creazione di un Utente Associato all’Organizzazione

Per aggiungere un utente a una specifica organizzazione, inviare una chiamata POST a:

POST /api/v1/user

Body esempio:

{
  "name": "Prova",
  "surname": "Test",
  "email": "[email protected]",
  "organizations": [2]
}

Dove 2 è l’ID dell’organizzazione creata nel passo precedente.

3. Creazione dello Scope

Uno scope rappresenta un contesto operativo o funzionale legato all’organizzazione.

Body esempio:

Il campo organizationId deve corrispondere all’ID dell’organizzazione.

4. Creazione del Channel

Un channel definisce il canale di comunicazione (es. Telegram, WhatsApp, ecc.).

Body esempio:

typeId identifica il tipo di canale. scopes contiene gli ID degli scope creati in precedenza.

5. Creazione del Bot Telegram

Per i canali di tipo Telegram è necessario creare un bot su Telegram e ottenere il relativo token di accesso.

  1. Creare il bot tramite BotFather:

    • Aprire Telegram e cercare l’utente @BotFather.

    • Avviare la conversazione e inviare il comando:

    • Seguire le istruzioni di BotFather:

      • Inserire il nome visualizzato del bot (es. Demo Calybron Bot).

      • Inserire il nome utente univoco del bot, che deve terminare con bot (es. demo_calybron_bot).

    • Al termine BotFather fornirà un token API nel formato:

  2. Impostare le informazioni del bot (opzionale ma consigliato):

    • Con BotFather è possibile usare i comandi:

      • /setdescription per aggiungere una descrizione.

      • /setabouttext per il testo breve “About”.

      • /setuserpic per impostare un’immagine profilo.

      • /setcommands per definire i comandi disponibili.

  3. Salvare il token:

    • Il token generato da BotFather deve essere copiato e conservato in modo sicuro.

    • Verrà inserito nel file di configurazione al momento del Deploy del Channel (Step 6) come valore di bot.token.

Nota: Senza questo passaggio il canale Telegram non sarà in grado di ricevere o inviare messaggi.

6. Deploy del Channel

Per rendere operativo il nuovo canale, basterà andarlo a configurare all'interno della cartella dove è stata clonata la repository Calybron Channel Telegram Base. Su staging questa cartella si trova in /var/calybron-st/calybron-channel-telegram-base.

  1. Aggiungere un nuovo file di configurazione config/{organization}.json.

  2. All’interno del file, modificare i seguenti parametri:

    • bot.token

    • bot.startMessages

    • cip.token

    • cip.channel_uuid

  3. Verificare gli endpoint: Per l’ambiente di staging, la base URL è st-api.calybron.cloud

  4. Configurare PM2: Creare un file startup.{organization}.config.js nella root della cartella. Al suo interno inserire le seguenti configurazioni (modificare i riferimenti all'organization secondo quanto compilato allo step precedente).

  5. Avviare il processo:

7. Creazione del DIM

Il DIM (Dynamic Intent Module) definisce la logica conversazionale. Può essere creato dalla pagina di dettaglio dello scope generato in precedenza: è presente una sezione apposita (inizialmente vuota) con la possibilità di registrare un nuovo DIM. Dovremo specificarne il nome, e dovremo salvarci il token generato.

8. Deployare e configurare il modulo DIM

Passaggi:

  1. Forkare il Calybron DIM Base.

  2. Modificare il file presentation.json.

    • Al suo interno, andremo a specificare almeno un intent con is_tool: false. Andranno mantenuti, per il momenti, i campi dell'esempio già presente, sovrascrivendo solo:

      • organization

      • intentSlug

      • scope

      • context

      • description

    • Prevedere sempre almeno in intento is_tool: false che funzioni da identity per Calybron. In questo, inserire il contesto su che "ruolo" deve interpretare.

    • Se possibile, predisporre già un intento is_tool: true che funzioni da primo tool utilizzabile. Ogni intento di questo tipo dovrà essere successivamente allacciato nella intentRegistry ad un file .js che genererà la risposta (è possibile usare in fase iniziale example.js, che ripeterà eventuale payload ricevuto).

Nota: In questo caso è opportuno valutare se il tool ha bisogno di entity (come nell'esempio fornito). Non sono obbligatori per tutti i tool, ma sono utili per alcuni flussi in cui Calybron deve raccogliere prima dei parametri da usare nell'eseguire operazioni.

  1. Aggiungere un nuovo file di configurazione config/{organization}.json.

  2. All’interno del file, modificare i seguenti parametri:

    • iip.token

    • intentRegistry: in questa sezione dovremo elencare tutti gli slug degli intenti is_tool: true che abbiamo definito dentro presentation.json. Per ciascuno, sarà collegato un file .js caricato nella cartella src/intents/. Prendere a modello l'example per verificare come creare un nuovo file.

  3. Configurare PM2: Creare un file startup.{organization}.config.js nella root della cartella. Al suo interno inserire le seguenti configurazioni (modificare i riferimenti all'organization secondo quanto compilato allo step precedente).

  4. Avviare il processo:

Esempio di Configurazione PM2 Telegram Base

Esempio di Configurazione PM2 DIM Base

PreviousMisure di Sicurezza Tecniche

Last updated