# Ripresa delle Sessioni

La funzionalità di ripresa delle sessioni permette agli utenti di continuare conversazioni precedenti senza perdere il contesto, migliorando significativamente l'esperienza utente.

### Come funziona

Quando viene fornito un `sessionID`, AIsuru verifica automaticamente la validità della sessione:

* **Sessione valida**: recupera lo storico della conversazione e ripopola la chat, mostrando l'ultimo messaggio dell'Agente
* **Sessione non valida**: crea una nuova sessione e mostra il messaggio di benvenuto

⏰ **Importante**: Le sessioni scadono dopo **1 ora** di inattività.

### Ottenere il sessionID

#### Dall'interfaccia di AIsuru

Il modo più semplice per trovare l'ID di una sessione:

1. Accedi alla sezione \<img src="../.gitbook/assets/conversazioni.svg" alt="" data-size="line"> **Conversazioni** del tuo Agente
2. Clicca su \<img src="../.gitbook/assets/URL.svg" alt="" data-size="line"> **Apri** per la conversazione desiderata
3. Nella sezione **"Informazioni sessione"**, troverai l'**ID sessione**

#### Tramite JavaScript

Per ottenere programmaticamente l'ID di una sessione attiva:

```javascript
javascript// Sessione correnteconst sessionID = getMemoriState().sessionID;// Per widget con integrationID specificoconst sessionID = getMemoriState("mio-integration-id").sessionID;
```

### Implementazione

#### Web Component

```html
html<memori-client  memoriName="MioMemori"  ownerUserName="utente"  tenantID="aisuru.com"  sessionID="uuid-della-sessione-da-riprendere"></memori-client>
```

#### Componente React

```tsx
tsx<Memori  memoriName="MioMemori"  ownerUserName="utente"  tenantID="aisuru.com"  sessionID="uuid-della-sessione-da-riprendere"/>
```

### Casi d'uso comuni

#### Salvare e riprendere sessioni

```javascript
javascript// Salva sessionIDdocument.addEventListener('MemoriNewDialogState', (e) => {  const sessionID = e.detail.sessionID;  localStorage.setItem('memori-session', sessionID);});// Riprendi sessione salvataconst savedSessionID = localStorage.getItem('memori-session');// Usa savedSessionID nell'attributo sessionID del componente
```

#### Integrazione con autenticazione utente

```javascript
javascript// Associa sessione all'utente loggatoconst userSessionKey = `memori-session-${userId}`;localStorage.setItem(userSessionKey, sessionID);// Riprendi sessione per utente specificoconst userSessionID = localStorage.getItem(userSessionKey);
```

### Integrazione avanzata via API

#### 1. Recupero dei Chat Log (Storico)

Esistono due modalità per recuperare i messaggi passati, a seconda che si conosca già la sessione specifica o si voglia mostrare un elenco cronologico all'utente.

**A. Recupero sessione specifica**

Da utilizzare se si dispone già di un ID sessione e si vogliono caricare i messaggi associati.

**Endpoint:** `GET /memori/v2/SessionChatLogs/{sessionID}/{chatLogSessionID}`

**Nota:** passando lo stesso ID in entrambi i parametri, l'API restituirà i log di quella specifica sessione.

**B. Elenco cronologico paginato**

Da utilizzare per mostrare all'utente la cronologia delle sue conversazioni passate.

* **Endpoint:** `POST /memori/v2/UserChatLogsByTokenPaged`
* **Parametri Payload (`ChatLogFilters`):**

| Parametro                | Tipo    | Descrizione                                                    |
| ------------------------ | ------- | -------------------------------------------------------------- |
| `loginToken`             | String  | Token di autenticazione dell'utente.                           |
| `memoriID`               | String  | ID univoco del Memori (Engine).                                |
| `from`                   | Number  | Indice di partenza per la paginazione.                         |
| `howMany`                | Number  | Numero di item da recuperare.                                  |
| `dateFrom` / `dateTo`    | String  | Intervallo temporale (formato `yyyyMMddHHmmssfff`).            |
| `minimumMessagesPerChat` | Number  | (Opzionale) Numero minimo di messaggi da includere nella chat. |
| `showChatsWithNoHistory` | Boolean | (Opzionale) Include sessioni aperte ma senza messaggi.         |

#### 2. Analisi della risposta (JSON)

Indipendentemente dall'endpoint usato, la struttura dei log segue questo schema:

```json
{
  "chatLogs": [
    {
      "chatLogID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sessionID": "session-uuid-1111-2222",
      "lines": [
        {
          "text": "Ciao, come posso aiutarti?",
          "inbound": false,
          "emitter": "assistant"
        },
        {
          "text": "Vorrei info sul prodotto X",
          "inbound": true,
          "emitter": "user"
        }
      ]
    }
  ]
}
```

> **Integrazione UI:** usa `inbound: true` per i messaggi dell'utente e `inbound: false` per quelli dell'assistente.

#### 3. Apertura di una nuova sessione (ripresa)

Dopo aver identificato la conversazione da proseguire, è necessario aprire una nuova sessione operativa iniettando il contesto passato.

**Endpoint:** `POST /memori/v2/Session`

#### Opzioni di continuazione

Nel body della richiesta, è possibile scegliere **uno** dei due parametri di ancoraggio:

1. `continueFromChatLogID`: utilizza l'ID del blocco di log ottenuto al punto 1.
2. `continueFromSessionID`: utilizza l'ID della sessione precedente.

> La sessione dura 5 minuti.

**Esempio Body JSON:**

```json
{
  "memoriID": "IL-TUO-ID-AGENTE",
  "continueFromChatLogID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "initialContextVars": {
    "LANG": "it"
  },
  "additionalInfo": {
    "language": "it",
    "timeZoneOffset": "-120"
  }
}
```

**Risultato:** il backend restituirà un **nuovo** `sessionID`. Da questo momento in poi, tutti i messaggi successivi dovranno usare questo nuovo ID.

***

### Note tecniche

* **Targeting ID:** il `chatLogID` identifica l'intero snapshot della conversazione. **Non** passare mai l'ID di un singolo messaggio (`line`) nel campo di continuazione.
* **Variabili di contesto:** usa `initialContextVars` per passare dati come la lingua o il percorso URL attuale; questi aiutano il motore a fornire risposte contestualizzate fin dal primo messaggio della ripresa.
* **Client SDK:** per una tipizzazione forte dei parametri `ChatLogFilters`, si consiglia l'uso del pacchetto ufficiale `@memori.ai/memori-api-client`.

### Vantaggi

* **Continuità dell'esperienza**: gli utenti possono riprendere conversazioni interrotte;
* **Mantenimento del contesto**: l'Agente ricorda le informazioni della conversazione precedente;
* **Gestione automatica**: AIsuru gestisce automaticamente sessioni scadute o non valide;
* **Flessibilità**: compatibile con tutti i layout e le configurazioni.


---

# 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/ripresa-delle-sessioni.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.