nAIxus Documentation

Continuer une conversation sur plusieurs requêtes du canal API avec session_id.

Utilisez ce guide lorsque vous devez maintenir le contexte entre plusieurs requêtes sur le même canal - par exemple, un chat de support multi-tour ou un workflow avec état.

Résultat attendu : les requêtes suivantes continuent le même fil de conversation, préservant le contexte du flow des tours précédents.

Fonctionnement des conversations

L'omission de session_id démarre une nouvelle conversation. Le serveur assigne un UUID et le retourne dans session_id (réponse JSON ou événement SSE data-run).
La fourniture de session_id reprend une conversation existante, qui porte l'état construit par le flow lors des tours précédents.
Une conversation appartient à un canal et un tenant spécifiques. Vous ne pouvez pas reprendre une conversation du canal A sur le canal B.

Étape 1 - Démarrer une conversation

Envoyez la première requête sans session_id :

curl -X POST "https://api.example.com/public/v1/api/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"user_message":"J'"'"'ai besoin d'"'"'aide avec la commande #12345"}}'

Réponse :

{
  "run_id": "9c1d…",
  "session_id": "b1f2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "output": {
    "result": { "text": "Je peux vous aider. Quel est le problème avec la commande #12345 ?" },
    "error": null,
    "messages": [
      {
        "id": "pub_7f6d8e9a",
        "role": "assistant",
        "content": "Je peux vous aider. Quel est le problème avec la commande #12345 ?"
      }
    ],
    "metadata": {
      "channel_id": "6f1e2d3c-…",
      "flow_id": "1a2b3c4d-…",
      "flow_name": "Support commandes",
      "flow_version": { "version_number": 3, "version_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9" },
      "environment": "prod",
      "livechat_mode": null,
      "execution_order": ["trigger_from_channel", "agent"],
      "started_at": "2026-08-04T10:00:00.000Z",
      "completed_at": "2026-08-04T10:00:01.000Z"
    }
  }
}

output.result est la sortie du flow lui-même et sa forme dépend du flow - ne la traitez pas comme « la réponse de l'assistant ». Utilisez les zéro, une ou plusieurs entrées de output.messages pour les publications assistant stables. Chaque entrée a la forme {id: string, role: "assistant", content: string} ; conservez id et ne dédupliquez pas selon le contenu.

Stockez le session_id.

Étape 2 - Envoyer un message de suivi

Incluez session_id dans la requête suivante :

curl -X POST "https://api.example.com/public/v1/api/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"user_message":"Je ne l'"'"'ai jamais reçue"},"session_id":"b1f2c3d4-e5f6-7890-abcd-ef1234567890"}'

Le flow reçoit l'historique complet de la conversation et répond en conséquence.

Si l'exécution précédente s'est arrêtée sur un nœud Question (status: "pending" et livechat_mode: null), ce message sert de réponse : l'exécution en pause reprend avec le même run_id. Voir Répondre à un nœud Question.

Choisir une réponse JSON ou SSE

Utilisez POST /execute sans le paramètre de requête stream lorsque cet appel doit attendre ses publications JSON.
Utilisez POST /execute?stream=true lorsque cet appel doit observer les publications et la reprise de l'automatisation après le livechat sur une seule connexion SSE.
Lisez les tours précédents avec GET /public/v1/api/conversations/{session_id}/messages. Cette route GET ne permet pas d'envoyer un nouveau message.

Exemple TypeScript

type AssistantPublication = {
  id: string;
  role: 'assistant';
  content: string;
};

class ApiConversation {
  private sessionId: string | null = null;

  constructor(private readonly apiKey: string) {}

  async send(message: string): Promise<AssistantPublication[]> {
    const body = JSON.stringify({
      payload: { user_message: message },
      ...(this.sessionId ? { session_id: this.sessionId } : {}),
    });

    const response = await fetch('https://api.example.com/public/v1/api/execute', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body,
    });

    const data = await response.json();
    if (!response.ok) throw new Error(data.error?.code);

    this.sessionId = data.session_id;
    return data.output?.messages ?? [];
  }
}

GET .../messages retourne l'automatisation, le livechat et l'automatisation reprise dans l'ordre chronologique. Les entrées automation peuvent inclure un publication_id nullable, égal à output.messages[].id lorsque l'entrée d'historique représente une publication. Le turn_index final est attribué après la fusion des sources. Une conversation inconnue retourne 404.

Reprise inter-canal

Une conversation d'un autre canal du même tenant est refusée avec 403 conversation_forbidden. Un identifiant inconnu, ou appartenant à un autre tenant, retourne 404 conversation_not_found, sans révéler s'il existe ailleurs.

Référence

Pour les contraintes du champ session_id et les codes d'erreur, voir la référence d'API et Lire les conversations.

Reprendre une conversation existante