Gestion des sessions de chat

Les sessions de chat représentent des conversations individuelles avec votre agent d'intelligence artificielle. Découvrez comment créer, récupérer, mettre à jour et supprimer des sessions afin d'organiser plusieurs conversations pour vos utilisateurs.

Présentation

Chaque session de chat conserve son propre historique de messages et sa propre configuration. Considérez une session comme un fil de conversation distinct : vous pouvez avoir plusieurs sessions par utilisateur, chacune avec son propre contexte et ses propres messages. Les sessions sont stockées de manière permanente, ce qui permet aux utilisateurs de revenir à tout moment aux conversations précédentes.

Ce guide explique comment répertorier les sessions, en créer de nouvelles, récupérer les détails d'une session avec l'historique des messages, mettre à jour les propriétés d'une session et supprimer les sessions qui ne sont plus nécessaires.

Prérequis

Avant de travailler avec les sessions, assurez-vous que vous disposez des éléments suivants :

1. Vous êtes authentifié auprès de l'API — Suivez les instructions Guide d'authentification et d'installation pour obtenir votre accessToken et votre workspaceId

2. Configuré votre client GraphQL — Votre client Apollo doit inclure les en-têtes d'authentification requis

3. Un ID todo — reçu dans la réponse d'authentification sous la forme todoId (il s'agit du conteneur pour toutes les sessions)

Pour commencer

Voici la configuration minimale pour créer et répertorier des sessions :

Étape 1 : Lister les sessions existantes

Récupérez une liste paginée de toutes les sessions de chat d'un utilisateur.

import { gql } from '@apollo/client';

const GET_SESSIONS = gql`
  query GetTodoChatSessions($todoId: Float!, $limit: Int, $offset: Int) {
    getTodoChatSessions(todoId: $todoId, limit: $limit, offset: $offset) {
      sessions {
        id
        title
        createdAt
        updatedAt
        defaultBotId
      }
      totalCount
    }
  }
`;

const listSessions = async (client, todoId, limit = 20, offset = 0) => {
  const { data } = await client.query({
    query: GET_SESSIONS,
    variables: { todoId, limit, offset },
  });

  return data.getTodoChatSessions;
};

// Usage
const result = await listSessions(client, 12345);
console.log(`Found ${result.totalCount} sessions`);
result.sessions.forEach(session => {
  console.log(`- ${session.title} (ID: ${session.id})`);
});

Étape 2 : Créer une nouvelle session

Créez une nouvelle session de chat pour une conversation.

const CREATE_SESSION = gql`
  mutation CreateTodoChatSession($data: TodoChatSessionInput!) {
    createTodoChatSession(data: $data) {
      id
      title
      createdAt
      defaultBotId
      todoId
    }
  }
`;

const createSession = async (client, todoId, title = 'New Chat') => {
  const { data } = await client.mutate({
    mutation: CREATE_SESSION,
    variables: {
      data: {
        todoId,
        title,
      },
    },
  });

  return data.createTodoChatSession;
};

// Usage
const newSession = await createSession(client, 12345, 'Customer Support');
console.log('Created session:', newSession.id);

Étape 3 : Obtenir les détails de la session avec les messages

Récupérez une session spécifique, y compris tous ses messages.

const GET_SESSION = gql`
  query GetOneTodoChatSession($sessionId: Float!) {
    getOneTodoChatSession(sessionId: $sessionId) {
      id
      title
      createdAt
      updatedAt
      defaultBotId
      todoId
      messages {
        id
        message
        createdAt
        sentBy {
          id
          firstName
        }
        isBotReply
      }
    }
  }
`;

const getSessionDetails = async (client, sessionId) => {
  const { data } = await client.query({
    query: GET_SESSION,
    variables: { sessionId },
  });

  return data.getOneTodoChatSession;
};

// Usage
const session = await getSessionDetails(client, 67890);
console.log(`Session: ${session.title}`);
console.log(`Messages: ${session.messages.length}`);
session.messages.forEach(msg => {
  const sender = msg.isBotReply ? 'Bot' : msg.sentBy.firstName;
  console.log(`${sender}: ${msg.message}`);
});

Requête de sessions

Obtenir la liste des sessions

Récupérer une liste paginée des sessions de chat pour un utilisateur.

Requête GraphQL :

query GetTodoChatSessions($todoId: Float!, $limit: Int, $offset: Int) {
  getTodoChatSessions(todoId: $todoId, limit: $limit, offset: $offset) {
    sessions {
      id
      title
      createdAt
      updatedAt
      defaultBotId
    }
    totalCount
  }
}

Paramètres :

• todoId (obligatoire) — L'ID du conteneur provenant de votre réponse d'authentification

• limit (facultatif) — Nombre de sessions par page (par défaut : 20)

• offset (facultatif) — Décalage de pagination pour la récupération des pages (par défaut : 0)

Retourne : Objet contenant un tableau d'sessionss et d'totalCount

Exemple avec pagination :

const listSessionsWithPagination = async (client, todoId) => {
  const pageSize = 10;
  let offset = 0;
  let allSessions = [];
  let totalCount = 0;

  // Fetch first page
  const { data } = await client.query({
    query: GET_SESSIONS,
    variables: { todoId, limit: pageSize, offset },
  });

  totalCount = data.getTodoChatSessions.totalCount;
  allSessions = data.getTodoChatSessions.sessions;

  // Fetch remaining pages if needed
  while (allSessions.length < totalCount) {
    offset += pageSize;
    const { data: nextPage } = await client.query({
      query: GET_SESSIONS,
      variables: { todoId, limit: pageSize, offset },
    });
    allSessions = [...allSessions, ...nextPage.getTodoChatSessions.sessions];
  }

  return allSessions;
};

Obtenir les détails d'une seule session

Récupérer les détails complets d'une session spécifique, y compris tous les messages.

Requête GraphQL :

query GetOneTodoChatSession($sessionId: Float!) {
  getOneTodoChatSession(sessionId: $sessionId) {
    id
    title
    createdAt
    updatedAt
    defaultBotId
    todoId
    messages {
      id
      message
      createdAt
      sentBy {
        id
        firstName
      }
      isBotReply
    }
  }
}

Paramètres :

• sessionId (obligatoire) — L'ID de la session à récupérer

Résultats : Objet de session complet avec l'historique des messages

Obtenir ou créer une session de démarrage

Récupérer ou créer la session de démarrage par défaut pour un utilisateur. Cela est utile si vous souhaitez une expérience de « démarrage rapide » sans créer explicitement une session.

Requête GraphQL :

query GetOrCreateUserStartTodoChatSession($botSlug: String) {
  getOrCreateUserStartTodoChatSession(botSlug: $botSlug) {
    id
    title
    defaultBotId
    todoId
  }
}

Paramètres :

• botSlug (facultatif) — Le slug de votre agent

Renvoie : La session de démarrage (créée si elle n'existe pas)

Exemple :

const GET_STARTER_SESSION = gql`
  query GetOrCreateUserStartTodoChatSession($botSlug: String) {
    getOrCreateUserStartTodoChatSession(botSlug: $botSlug) {
      id
      title
      defaultBotId
    }
  }
`;

const getStarterSession = async (client, botSlug) => {
  const { data } = await client.query({
    query: GET_STARTER_SESSION,
    variables: { botSlug },
  });

  return data.getOrCreateUserStartTodoChatSession;
};

// Usage - useful for quick start without creating a new session
const starterSession = await getStarterSession(client, 'my-agent-slug');
console.log('Using starter session:', starterSession.id);

Rechercher des sessions

Recherchez dans les sessions de chat par titre ou contenu.

Requête GraphQL :

query GetSearchTodoChatSessions($todoId: Float!, $searchQuery: String) {
  getSearchTodoChatSessions(todoId: $todoId, searchQuery: $searchQuery) {
    id
    title
    createdAt
  }
}

Paramètres :

• todoId (obligatoire) — L'ID du conteneur

• searchQuery (facultatif) — Terme de recherche pour filtrer les sessions

Résultats : tableau des sessions correspondantes

Exemple :

const SEARCH_SESSIONS = gql`
  query GetSearchTodoChatSessions($todoId: Float!, $searchQuery: String) {
    getSearchTodoChatSessions(todoId: $todoId, searchQuery: $searchQuery) {
      id
      title
      createdAt
    }
  }
`;

const searchSessions = async (client, todoId, query) => {
  const { data } = await client.query({
    query: SEARCH_SESSIONS,
    variables: { todoId, searchQuery: query },
  });

  return data.getSearchTodoChatSessions;
};

// Usage
const results = await searchSessions(client, 12345, 'billing');
console.log(`Found ${results.length} sessions matching "billing"`);
Creating and updating sessions

Créer une nouvelle session

Créer une nouvelle session de chat avec une configuration bot facultative.

Mutation GraphQL :

mutation CreateTodoChatSession($data: TodoChatSessionInput!) {
  createTodoChatSession(data: $data) {
    id
    title
    createdAt
    defaultBotId
    todoId
  }
}

Paramètres d'entrée :

Exemple :

const CREATE_SESSION = gql`
  mutation CreateTodoChatSession($data: TodoChatSessionInput!) {
    createTodoChatSession(data: $data) {
      id
      title
      createdAt
      defaultBotId
    }
  }
`;

// Basic session
const basicSession = await client.mutate({
  mutation: CREATE_SESSION,
  variables: {
    data: {
      todoId: 12345,
      title: 'Product Questions',
    },
  },
});

// Session with specific bot
const botSession = await client.mutate({
  mutation: CREATE_SESSION,
  variables: {
    data: {
      todoId: 12345,
      title: 'Support Chat',
      defaultBotId: 789,
    },
  },
});

// Session with custom layout
const compactSession = await client.mutate({
  mutation: CREATE_SESSION,
  variables: {
    data: {
      todoId: 12345,
      title: 'Quick Chat',
      uiLayout: 'COMPACT',
    },
  },
});

Mettre à jour une session

Mettre à jour les propriétés d'une session existante (comme le titre ou la configuration).

Mutation GraphQL :

mutation UpdateTodoChatSession($data: TodoChatSessionInput!, $id: Float!) {
  updateTodoChatSession(data: $data, id: $id) {
    id
    title
    updatedAt
  }
}

Paramètres :

• id (obligatoire) — ID de session à mettre à jour

• data (obligatoire) — Objet avec les champs à mettre à jour (identiques à ceux utilisés lors de la création)

Exemple :

const UPDATE_SESSION = gql`
  mutation UpdateTodoChatSession($data: TodoChatSessionInput!, $id: Float!) {
    updateTodoChatSession(data: $data, id: $id) {
      id
      title
      updatedAt
    }
  }
`;

const updateSession = async (client, sessionId, updates) => {
  const { data } = await client.mutate({
    mutation: UPDATE_SESSION,
    variables: {
      id: sessionId,
      data: updates,
    },
  });

  return data.updateTodoChatSession;
};

// Usage
const updated = await updateSession(client, 67890, {
  title: 'Updated Session Title',
});
console.log('Session updated:', updated.title);

Mettre à jour la configuration personnalisée du bot

Configurer les paramètres LLM personnalisés pour une session spécifique (comme le modèle et la température).

Mutation GraphQL :

mutation UpdateCustomBotConfig($data: BotCustomConfigInput!) {
  updateTodoChatSessionCustomBotConfig(data: $data) {
    id
  }
}

Paramètres d'entrée :

Exemple :

const UPDATE_BOT_CONFIG = gql`
  mutation UpdateCustomBotConfig($data: BotCustomConfigInput!) {
    updateTodoChatSessionCustomBotConfig(data: $data) {
      id
    }
  }
`;

// Set model and temperature for a session
const configResult = await client.mutate({
  mutation: UPDATE_BOT_CONFIG,
  variables: {
    data: {
      botId: 123,
      sessionId: 67890,
      model: 'gpt-4',
      temperature: 0.7,
    },
  },
});

console.log('Bot config updated for session:', configResult.data.updateTodoChatSessionCustomBotConfig.id);

Suppression de sessions

Supprimer une seule session

Supprimez une session de chat et tous ses messages.

Mutation GraphQL :

mutation DeleteTodoChatSession($id: Float!) {
  deleteTodoChatSession(id: $id) {
    id
  }
}

Paramètres :

• id (obligatoire) — ID de la session à supprimer

Exemple :

const DELETE_SESSION = gql`
  mutation DeleteTodoChatSession($id: Float!) {
    deleteTodoChatSession(id: $id) {
      id
    }
  }
`;

const deleteSession = async (client, sessionId) => {
  const { data } = await client.mutate({
    mutation: DELETE_SESSION,
    variables: { id: sessionId },
  });

  return data.deleteTodoChatSession;
};

// Usage
const deleted = await deleteSession(client, 67890);
console.log('Session deleted:', deleted.id);

Supprimer plusieurs sessions

Supprimez plusieurs sessions en une seule opération pour plus d'efficacité.

Mutation GraphQL :

mutation DeleteManyTodoChatSession($ids: [Int!]!) {
  deleteManyTodoChatSession(ids: $ids)
}

Paramètres :

• ids (obligatoire) — Tableau des identifiants de session à supprimer

Exemple :

const DELETE_MANY_SESSIONS = gql`
  mutation DeleteManyTodoChatSession($ids: [Int!]!) {
    deleteManyTodoChatSession(ids: $ids)
  }
`;

const deleteManySessions = async (client, sessionIds) => {
  const { data } = await client.mutate({
    mutation: DELETE_MANY_SESSIONS,
    variables: { ids: sessionIds },
  });

  return data.deleteManyTodoChatSession;
};

// Usage
const result = await deleteManySessions(client, [101, 102, 103]);
console.log(`Deleted ${result} sessions`);

Classe complète de gestionnaire de session

Voici une classe réutilisable qui encapsule toutes les opérations de session :

class SessionManager {
  constructor(client, todoId) {
    this.client = client;
    this.todoId = todoId;
  }

  async listSessions(limit = 20, offset = 0) {
    const query = gql`
      query GetTodoChatSessions($todoId: Float!, $limit: Int, $offset: Int) {
        getTodoChatSessions(todoId: $todoId, limit: $limit, offset: $offset) {
          sessions {
            id
            title
            createdAt
            defaultBotId
          }
          totalCount
        }
      }
    `;

    const { data } = await this.client.query({
      query,
      variables: { todoId: this.todoId, limit, offset },
    });

    return data.getTodoChatSessions;
  }

  async createSession(title = 'New Chat', options = {}) {
    const mutation = gql`
      mutation CreateTodoChatSession($data: TodoChatSessionInput!) {
        createTodoChatSession(data: $data) {
          id
          title
          createdAt
          defaultBotId
        }
      }
    `;

    const { data } = await this.client.mutate({
      mutation,
      variables: {
        data: {
          todoId: this.todoId,
          title,
          ...options,
        },
      },
    });

    return data.createTodoChatSession;
  }

  async getSessionDetails(sessionId) {
    const query = gql`
      query GetOneTodoChatSession($sessionId: Float!) {
        getOneTodoChatSession(sessionId: $sessionId) {
          id
          title
          createdAt
          updatedAt
          defaultBotId
          messages {
            id
            message
            createdAt
            isBotReply
            sentBy {
              firstName
            }
          }
        }
      }
    `;

    const { data } = await this.client.query({
      query,
      variables: { sessionId },
    });

    return data.getOneTodoChatSession;
  }

  async updateSession(sessionId, updates) {
    const mutation = gql`
      mutation UpdateTodoChatSession($data: TodoChatSessionInput!, $id: Float!) {
        updateTodoChatSession(data: $data, id: $id) {
          id
          title
          updatedAt
        }
      }
    `;

    const { data } = await this.client.mutate({
      mutation,
      variables: {
        id: sessionId,
        data: updates,
      },
    });

    return data.updateTodoChatSession;
  }

  async deleteSession(sessionId) {
    const mutation = gql`
      mutation DeleteTodoChatSession($id: Float!) {
        deleteTodoChatSession(id: $id) {
          id
        }
      }
    `;

    await this.client.mutate({
      mutation,
      variables: { id: sessionId },
    });
  }

  async deleteManySessions(sessionIds) {
    const mutation = gql`
      mutation DeleteManyTodoChatSession($ids: [Int!]!) {
        deleteManyTodoChatSession(ids: $ids)
      }
    `;

    const { data } = await this.client.mutate({
      mutation,
      variables: { ids: sessionIds },
    });

    return data.deleteManyTodoChatSession;
  }

  async searchSessions(query) {
    const gqlQuery = gql`
      query GetSearchTodoChatSessions($todoId: Float!, $searchQuery: String) {
        getSearchTodoChatSessions(todoId: $todoId, searchQuery: $searchQuery) {
          id
          title
          createdAt
        }
      }
    `;

    const { data } = await this.client.query({
      query: gqlQuery,
      variables: { todoId: this.todoId, searchQuery: query },
    });

    return data.getSearchTodoChatSessions;
  }

  async getStarterSession(botSlug) {
    const query = gql`
      query GetOrCreateUserStartTodoChatSession($botSlug: String) {
        getOrCreateUserStartTodoChatSession(botSlug: $botSlug) {
          id
          title
          defaultBotId
        }
      }
    `;

    const { data } = await this.client.query({
      query,
      variables: { botSlug },
    });

    return data.getOrCreateUserStartTodoChatSession;
  }

  async updateBotConfig(botId, sessionId, config) {
    const mutation = gql`
      mutation UpdateCustomBotConfig($data: BotCustomConfigInput!) {
        updateTodoChatSessionCustomBotConfig(data: $data) {
          id
        }
      }
    `;

    const { data } = await this.client.mutate({
      mutation,
      variables: {
        data: {
          botId,
          sessionId,
          ...config,
        },
      },
    });

    return data.updateTodoChatSessionCustomBotConfig;
  }
}

// Usage example
const sessionManager = new SessionManager(client, 12345);

// Create a new session
const session = await sessionManager.createSession('Customer Support');
console.log('Created session:', session.id);

// Get session details
const details = await sessionManager.getSessionDetails(session.id);
console.log('Messages in session:', details.messages.length);

// Update session
await sessionManager.updateSession(session.id, { title: 'Premium Support' });

// Search sessions
const results = await sessionManager.searchSessions('support');
console.log('Found sessions:', results.length);

// Delete session
await sessionManager.deleteSession(session.id);

Cas d'utilisation pratiques

Système d'assistance multithread

Organisez les conversations du service client en sessions distinctes par thème :

const sessionManager = new SessionManager(client, todoId);

// Create sessions for different support categories
const billingSession = await sessionManager.createSession('Billing Inquiry');
const technicalSession = await sessionManager.createSession('Technical Support');
const salesSession = await sessionManager.createSession('Sales Question');

// Each session maintains its own conversation history
// User can switch between sessions without losing context

Récupération de session

Récupérez les conversations précédentes lorsqu'un utilisateur revient :

// List all sessions for the user
const { sessions } = await sessionManager.listSessions();

// Display session list in UI
sessions.forEach(session => {
  console.log(`${session.title} - Last updated: ${session.updatedAt}`);
});

// User selects a session to continue
const selectedSession = sessions[0];
const details = await sessionManager.getSessionDetails(selectedSession.id);

// Display message history
details.messages.forEach(msg => {
  console.log(`${msg.isBotReply ? 'Bot' : 'User'}: ${msg.message}`);
});

Nettoyage de session

Supprimez périodiquement les sessions anciennes ou terminées :

// Get all sessions
const { sessions } = await sessionManager.listSessions(100, 0);

// Filter old sessions (older than 30 days)
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
const oldSessions = sessions.filter(s => new Date(s.createdAt) < thirtyDaysAgo);

// Delete old sessions in batch
if (oldSessions.length > 0) {
  const sessionIds = oldSessions.map(s => s.id);
  await sessionManager.deleteManySessions(sessionIds);
  console.log(`Deleted ${oldSessions.length} old sessions`);
}

Démarrage rapide avec une session de démarrage

Pour les cas d'utilisation simples, utilisez la session de démarrage créée automatiquement :

// Get or create the default starter session
const starterSession = await sessionManager.getStarterSession('my-agent-slug');

// Start chatting immediately without creating a new session
console.log('Ready to chat in session:', starterSession.id);

Meilleures pratiques

1. Utilisez la session de démarrage pour les cas simples — Si vous n'avez besoin que d'une seule conversation par utilisateur, utilisez getOrCreateUserStartTodoChatSession pour éviter la création manuelle de sessions.

2. Organisez les sessions par objectif — Créez des sessions distinctes pour différents sujets ou intentions des utilisateurs afin de maintenir les conversations ciblées.

3. Implémentez la pagination — Lorsque vous répertoriez les sessions, utilisez limit et offset pour gérer efficacement un grand nombre de sessions.

4. Nettoyez les anciennes sessions — Supprimez régulièrement les sessions archivées ou terminées afin que la liste des sessions de l'utilisateur reste gérable.

5. Stockez les identifiants de session — Conservez les identifiants de session importants dans l'état de votre interface utilisateur ou dans le stockage local pour y accéder rapidement.

6. Traitez les erreurs de session introuvable — Vérifiez toujours si une session existe avant d'essayer d'en récupérer les détails.

7. Supprimer par lots lorsque cela est possible — Utilisez deleteManyTodoChatSession au lieu de supprimer les sessions une par une pour améliorer les performances.

8. Définissez des titres significatifs — Utilisez des titres de session descriptifs afin que les utilisateurs puissent identifier facilement les conversations.