> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelinqa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cycle de vie d'une session

> Créer, faire progresser, reprendre et terminer une conversation NBQ V1.

Une session V1 est un état durable côté serveur. Elle est créée une fois, puis avancée avec des mutations protégées contre les doubles envois et les écritures concurrentes.

<Steps>
  <Step title="Créer la session">
    `POST /v1/sessions` crée un `session_id` et renvoie `versions.state_version: 0`. La session est attachée à la configuration publiée active.
  </Step>

  <Step title="Demander une première question">
    `POST /v1/sessions/{session_id}/next` avec `state_version: 0` renvoie une décision et des candidats ordonnés.
  </Step>

  <Step title="Envoyer le tour suivant">
    Renvoyez la nouvelle `state_version` et, si vous les avez, `decision_id`, `question_id`, le texte réellement posé et la réponse du visiteur.
  </Step>

  <Step title="Appliquer des informations externes">
    `/events` ajoute un résumé, des messages manqués ou une donnée connue du CRM sans sélectionner immédiatement une question.
  </Step>

  <Step title="Lire ou reprendre">
    `GET /v1/sessions/{session_id}` restitue l'état public. Vous pouvez reprendre après une interruption avec la dernière `state_version`.
  </Step>

  <Step title="Déclarer le résultat">
    `/feedback` enregistre un succès, un échec ou une autre issue métier. Il remplace la notion limitée de « conversion » de la bêta 0.9.
  </Step>
</Steps>

## Deux identifiants à conserver

| Valeur                   | Rôle                                                                                                       |
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `session_id`             | Identifie toute la conversation.                                                                           |
| `versions.state_version` | Empêche deux mises à jour concurrentes d'écraser le même état. Utilisez toujours la dernière valeur reçue. |

`decision_id` et `question_id` améliorent la corrélation du tour, mais restent optionnels : NBQ peut retrouver la décision en attente à partir des messages observés.

## Arrêts souples

`max_turns` est une limite souple. Lorsque cette limite est atteinte, NBQ peut encore retourner la meilleure question disponible avec un avertissement. Votre application décide alors de continuer ou d'arrêter. `action: stop` signifie qu'aucune question identifiable n'est disponible.

<Warning>
  Ne réutilisez jamais une ancienne `state_version`. En cas de conflit, relisez la session avant de recalculer votre mutation.
</Warning>