# Client API

### Overview

An npm module that wraps the backend and engine APIs. It handles API calls and exposes the available methods with typed parameters and responses. Can be used on both the web and node/server side.

### API Architecture <a href="#architettura_api_464" id="architettura_api_464"></a>

The Memori API consists of two main components:

1. **Engine API** ([Swagger](https://engine.memori.ai/swagger/index.html))
   1. Manages sessions and dialogues;
   2. Handles NLP features;
   3. Processes conversational functionality.
2. **Backend API (**[Swagger](https://backend.memori.ai/memoriai/swagger/index.html)**)**
   1. Manages users and assets;
   2. Handles notifications;
   3. Controls system administration.

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

```javascript
import memoriApiClient from "@memori.ai/memori-api-client";
// Initialize with default endpoints
const memori = memoriApiClient(
"https://backend.memori.ai", // API URL
"https://engine.memori.ai" // Engine URL
);
```

### Core Features <a href="#funzionalit_core_491" id="funzionalit_core_491"></a>

#### **Session Management**

{% code overflow="wrap" %}

```javascript
// Initialize a basic session
const {
  sessionID,
  currentState
} = await memori.initSession({
  memoriID: "your-memori-id",
  birthdate: "1900-01-01T00:00:00.000Z",
});
// Initialize a session with context
const sessionWithContext = await memori.initSession({
  memoriID: "your-memori-id",
  birthdate: "1900-01-01T00:00:00.000Z",
  context: {
    location: "Milan",
    userType: "premium",
    customVariable: "value",
  },
});
```

{% endcode %}

#### **Dialog Events**

```javascript
// Send a text message
const {
  currentState: dialogState
} = await memori.postTextEnteredEvent({
  sessionId: sessionID,
  text: "Hello Memori!",
});
// Change date context
await memori.postDateChangedEvent({
  sessionId: sessionID,
  date: "2024-12-13",
});
// Change location context
await memori.postPlaceChangedEvent({
  sessionId: sessionID,
  place: "Rome",
});
```

### Advanced Features <a href="#funzionalit_avanzate_536" id="funzionalit_avanzate_536"></a>

#### Global State Management <a href="#gestione_dello_stato_globale_538" id="gestione_dello_stato_globale_538"></a>

```javascript
// Get current state
const state = getMemoriState();
const sessionID = getMemoriState().sessionID;
// For multiple widgets
const specificState = getMemoriState("widget-integration-id");
// Read state manually from the DOM
const dialogState = JSON.parse(document.querySelector("div[data-memori-engine-state]") ? .dataset ? .memoriEngineState ? ?"{}");
```

### Event Listeners <a href="#eventi_listener_555" id="eventi_listener_555"></a>

#### **MemoriNewDialogState**

You can listen to every message using the `MemoriNewDialogState` event and evaluate its content to trigger a reaction

```javascript
// Listen for state changes
document.addEventListener("MemoriNewDialogState", (e) = >{
  const {
    emission,
    context,
    sessionID
  } = e.detail;
  // Log analytics
  logConversation({
    sessionId: sessionID,
    message: emission,
    timestamp: new Date(),
    context: context,
  });
  // Handle specific responses
  if (emission.includes("help")) {
    showHelpPanel();
  }
});
// Handle end of speech
document.addEventListener("MemoriEndSpeak", () = >{
  clearCustomElements();
  checkConversationFlow();
});
```

#### Message Sending <a href="#gestione_invio_messaggi_587" id="gestione_invio_messaggi_587"></a>

```javascript
// Basic message
typeMessage("Hello!");
// Advanced message with options
typeMessage("Show product catalog", true, // wait for previous message
false, // show in chat
"Loading catalog..." // loading text
);
// Don't show the message in chat
typeMessageHidden("analyze_sentiment", true);
```

### Complete API Integration Example <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 memoriConversation() {
  // Initialize client
  const memori = memoriApiClient("https://backend.memori.ai", "https://engine.memori.ai");

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

    // Send initial message
    const {
      currentState: firstResponse
    } = await memori.postTextEnteredEvent({
      sessionId: sessionID,
      text: "Hello! Tell me about yourself.",
    });
    console.log("Memori says:", firstResponse.emission);

    // Update context
    await memori.postPlaceChangedEvent({
      sessionId: sessionID,
      place: "Rome",
    });

    // Send next message
    const {
      currentState: secondResponse
    } = await memori.postTextEnteredEvent({
      sessionId: sessionID,
      text: "What can you tell me about this location?",
    });
    console.log("Memori says:", secondResponse.emission);

    // Run NLP analysis
    const language = await memori.guessLanguage(sessionID, secondResponse.emission);
    console.log("Response language:", language);

    // Close session
    await memori.closeSession(sessionID);
  } catch(error) {
    console.error("Error:", 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/en/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.