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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aisuru.com/frontend/client-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.