🔌 Client API

Panoramica

Modulo npm che fa da wrapper alle API di backend e engine. Permette di effettuare le chiamate e fornisce i metodi disponibili, con parametri e risposte tipizzati. Utilizzabile sia lato web che lato node/server.

Architettura API

L’API Memori consiste in due componenti principali:

1. API Engine (Swagger)

   1. Gestisce sessioni e dialoghi;

   2. Gestisce funzionalità NLP;

   3. Elabora funzionalità conversazionali.

2. API Backend (Swagger)

   1. Gestisce utenti e asset;

   2. Gestisce notifiche;

   3. Controlla amministrazione sistema.

Inizializzazione Client

import memoriApiClient from "@memori.ai/memori-api-client";
// Inizializza con endpoint predefiniti
const memori = memoriApiClient(
"https://backend.memori.ai", // URL API
"https://engine.memori.ai" // URL Engine
);

Funzionalità Core

Gestione Sessione

// Inizializza sessione base
const {
  sessionID,
  currentState
} = await memori.initSession({
  memoriID: "tuo-memori-id",
  birthdate: "1900-01-01T00:00:00.000Z",
});
// Inizializza sessione con contesto
const sessionWithContext = await memori.initSession({
  memoriID: "tuo-memori-id",
  birthdate: "1900-01-01T00:00:00.000Z",
  context: {
    location: "Milano",
    userType: "premium",
    customVariable: "valore",
  },
});

Eventi di Dialogo

// Invia messaggio di testo
const {
  currentState: dialogState
} = await memori.postTextEnteredEvent({
  sessionId: sessionID,
  text: "Ciao Memori!",
});
// Cambia contesto data
await memori.postDateChangedEvent({
  sessionId: sessionID,
  date: "2024-12-13",
});
// Cambia contesto luogo
await memori.postPlaceChangedEvent({
  sessionId: sessionID,
  place: "Roma",
});

Funzionalità Avanzate

Gestione dello Stato Globale

// Ottieni stato corrente
const state = getMemoriState();
const sessionID = getMemoriState().sessionID;
// Per widget multipli
const specificState = getMemoriState("widget-integration-id");
// Lettura manuale dello stato dal DOM
const dialogState = JSON.parse(document.querySelector("div[data-memori-engine-state]") ? .dataset ? .memoriEngineState ? ?"{}");

Eventi Listener

MemoriNewDialogState

Puoi ascoltare ogni messaggio usando l’evento MemoriNewDialogState e valutare il contenuto per attivare una reazione

// Ascolta i cambiamenti di stato
document.addEventListener("MemoriNewDialogState", (e) = >{
  const {
    emission,
    context,
    sessionID
  } = e.detail;
  // Registra analytics
  logConversazione({
    sessionId: sessionID,
    message: emission,
    timestamp: new Date(),
    context: context,
  });
  // Gestisce risposte specifiche
  if (emission.includes("aiuto")) {
    mostraPannelloAiuto();
  }
});
// Gestisce fine parlato
document.addEventListener("MemoriEndSpeak", () = >{
  pulisciElementiPersonalizzati();
  verificaFlussoConversazione();
});

Gestione Invio Messaggi

// Messaggio base
typeMessage("Ciao!");
// Messaggio avanzato con opzioni
typeMessage("Mostra catalogo prodotti", true, // attendi messaggio precedente
false, // mostra in chat
"Caricamento catalogo..." // testo di caricamento
);
// Non mostrare il messaggio nella chat
typeMessageHidden("analizza_sentimento", true);

Esempio Completo di Integrazione API

import memoriApiClient from "@memori.ai/memori-api-client";

async function conversazioneMemori() {
  // Inizializza client
  const memori = memoriApiClient("https://backend.memori.ai", "https://engine.memori.ai");

  try {
    // Avvia sessione
    const {
      sessionID,
      currentState
    } = await memori.initSession({
      memoriID: "tuo-memori-id",
      birthdate: "1900-01-01T00:00:00.000Z",
      context: {
        location: "Milano",
        userType: "premium",
      },
    });

    // Invia messaggio iniziale
    const {
      currentState: primaRisposta
    } = await memori.postTextEnteredEvent({
      sessionId: sessionID,
      text: "Ciao! Parlami di te.",
    });
    console.log("Memori dice:", primaRisposta.emission);

    // Aggiorna contesto
    await memori.postPlaceChangedEvent({
      sessionId: sessionID,
      place: "Roma",
    });

    // Invia messaggio successivo
    const {
      currentState: secondaRisposta
    } = await memori.postTextEnteredEvent({
      sessionId: sessionID,
      text: "Cosa puoi dirmi di questa località?",
    });
    console.log("Memori dice:", secondaRisposta.emission);

    // Esegui analisi NLP
    const lingua = await memori.guessLanguage(sessionID, secondaRisposta.emission);
    console.log("Lingua della risposta:", lingua);

    // Chiudi sessione
    await memori.closeSession(sessionID);
  } catch(error) {
    console.error("Errore:", error.resultMessage);
  }
}