> 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/ripresa-delle-sessioni.md).
# 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 \
**Conversazioni** del tuo Agente
2. Clicca su \
**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
```
#### Componente React
```tsx
tsx
```
### 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.