> For the complete documentation index, see [llms.txt](https://docs.aisuru.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisuru.com/frontend/client-api.md).

# 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 <a href="#architettura_api_464" id="architettura_api_464"></a>

L’API Memori consiste in due componenti principali:

1. **API Engine** ([Swagger](https://engine.memori.ai/swagger/index.html))
   1. Gestisce sessioni e dialoghi;
   2. Gestisce funzionalità NLP;
   3. Elabora funzionalità conversazionali.
2. **API Backend (**[Swagger](https://backend.memori.ai/memoriai/swagger/index.html)**)**
   1. Gestisce utenti e asset;
   2. Gestisce notifiche;
   3. Controlla amministrazione sistema.

### Inizializzazione Client <a href="#inizializzazione_client_479" id="inizializzazione_client_479"></a>

```javascript
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 <a href="#funzionalit_core_491" id="funzionalit_core_491"></a>

#### **Gestione Sessione**

{% code overflow="wrap" %}

```javascript
// 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",
  },
});
```

{% endcode %}

#### **Eventi di Dialogo**

```javascript
// 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 <a href="#funzionalit_avanzate_536" id="funzionalit_avanzate_536"></a>

#### Gestione dello Stato Globale <a href="#gestione_dello_stato_globale_538" id="gestione_dello_stato_globale_538"></a>

```javascript
// 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 <a href="#eventi_listener_555" id="eventi_listener_555"></a>

#### **MemoriNewDialogState**

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

```javascript
// 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 <a href="#gestione_invio_messaggi_587" id="gestione_invio_messaggi_587"></a>

```javascript
// 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 <a href="#esempio_completo_di_integrazione_api_605" id="esempio_completo_di_integrazione_api_605"></a>

```javascript
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);
  }
}
```