Référence API

Référence complète pour tous les types GraphQL, les requêtes, les mutations et les abonnements dans l'API Swiftask Public Bot. Utilisez-la comme guide de consultation lors de la construction de votre intégration.

Présentation

Ce document de référence répertorie tous les types GraphQL, types d'entrée, requêtes, mutations et abonnements disponibles dans l'API Swiftask. Chaque entrée comprend le schéma GraphQL, les descriptions des champs et des exemples d'utilisation courants. Utilisez ce guide en complément des exemples pratiques présentés dans d'autres guides.

L'API est organisée en trois catégories principales : les types de données (ce que l'API renvoie), les types d'entrée (ce que vous envoyez à l'API) et les opérations (requêtes, mutations et abonnements).

Types GraphQL

TodoChatMessage

Représente un seul message dans une session de chat.

Type GraphQL :

type TodoChatMessage {
  id: Int!
  message: String
  createdAt: DateTime!
  updatedAt: DateTime!
  sessionId: Int!
  sentBy: User!
  isBotReply: Boolean
  files: [File]
  parentMessageId: Int
}

Descriptions des champs :

Exemple d'utilisation :

const message = {
  id: 12345,
  message: 'What is your pricing?',
  createdAt: '2024-01-29T19:50:13.631Z',
  updatedAt: '2024-01-29T19:50:13.631Z',
  sessionId: 67890,
  sentBy: {
    id: 1,
    firstName: 'John',
    lastName: 'Doe',
  },
  isBotReply: false,
  files: null,
  parentMessageId: null,
};

TodoChatSession

Représente une session de chat contenant plusieurs messages.

Type GraphQL :

type TodoChatSession {
  id: Int!
  title: String
  createdAt: DateTime!
  updatedAt: DateTime!
  todoId: Int!
  defaultBotId: Int
  messages: [TodoChatMessage]
  uiLayout: String
}

Descriptions des champs :

Exemple d'utilisation :

const session = {
  id: 67890,
  title: 'Customer Support',
  createdAt: '2024-01-29T19:50:13.631Z',
  updatedAt: '2024-01-29T20:15:45.123Z',
  todoId: 12345,
  defaultBotId: 789,
  messages: [
    { id: 1, message: 'Hello', isBotReply: false },
    { id: 2, message: 'Hi there!', isBotReply: true },
  ],
  uiLayout: 'DEFAULT',
};

ChatStreamMessage

Représente un fragment d'un message en streaming.

Type GraphQL :

type ChatStreamMessage {
  messageChunk: String!
  userId: Int!
  id: Int!
  botId: Int!
  botResponseMessageId: Int!
  isStoppable: Boolean!
}

Descriptions des champs :

Exemple d'utilisation :

// Each subscription event looks like this:
const streamChunk = {
  messageChunk: 'Hello, ',
  userId: 1,
  id: 54321,
  botId: 789,
  botResponseMessageId: 12345,
  isStoppable: true,
};

// Next chunk:
const nextChunk = {
  messageChunk: 'how can I help?',
  userId: 1,
  id: 54322,
  botId: 789,
  botResponseMessageId: 12345,
  isStoppable: true,
};

AgentToolCall

Représente un événement d'appel d'outil d'agent.

Type GraphQL :

type AgentToolCall {
  tool: String!
  toolImage: String
  botId: Int!
  id: Int!
  status: String!
}

Descriptions des champs :

Noms d'outils courants :

• web_search — Recherche sur le Web

• calculator — Calculs mathématiques

• knowledge_base — Recherche dans une base de connaissances

• api_call — Appels API externes

• database_query — Requêtes de base de données

• file_search — Recherche de fichiers

Exemple d'utilisation :

const toolCall = {
  tool: 'web_search',
  toolImage: 'https://...',
  botId: 789,
  id: 99999,
  status: 'START',
};

// Later:
const toolEnd = {
  tool: 'web_search',
  toolImage: 'https://...',
  botId: 789,
  id: 100000,
  status: 'END',
};

SyncBotResponse

Réponse à une requête synchrone d'un bot.

Type GraphQL :

type SyncBotResponse {
  text: String!
  botId: Int
  botSlug: String
  isBotError: Boolean
  sessionId: Int
  files: JSON
  sourceMetadatas: JSON
  sources: JSON
  responseJson: JSON
  jobId: String
}

Descriptions des champs :

Exemple d'utilisation :

const response = {
  text: 'The capital of France is Paris.',
  botId: 789,
  botSlug: 'knowledge-bot',
  isBotError: false,
  sessionId: 67890,
  sources: [
    { title: 'Wikipedia', url: 'https://...' },
    { title: 'Britannica', url: 'https://...' },
  ],
  sourceMetadatas: { count: 2 },
  files: null,
  responseJson: { answer: 'Paris', confidence: 0.99 },
  jobId: 'job_123456',
};

Utilisateur

Représente un utilisateur dans le système.

Type GraphQL :

type User {
  id: Int!
  firstName: String
  lastName: String
  email: String
}

Descriptions des champs :

Types de saisie

NewMessageInput

Entrée pour l'envoi d'un nouveau message.

Type d'entrée GraphQL :

input NewMessageInput {
  message: String
  todoChatId: Int
  fileIds: [Int]
  mentionedUserId: Int
  mentionedUserIds: [Int]
  mentionedBotId: Int
  parentMessageId: Int
  botPromptId: Int
  sessionId: Int
  command: String
  extraConfig: JSON
  isForAiReply: Boolean
}

Descriptions des champs :

Exemple d'utilisation :

const messageInput = {
  message: 'What is the weather?',
  sessionId: 67890,
  isForAiReply: true,
};

const messageWithFiles = {
  message: 'Analyze these documents',
  sessionId: 67890,
  fileIds: [101, 102, 103],
  isForAiReply: true,
};

const threadedReply = {
  message: 'Can you elaborate?',
  sessionId: 67890,
  parentMessageId: 12345,
  isForAiReply: true,
};

TodoChatSessionInput

Entrée pour créer ou mettre à jour une session.

Type d'entrée GraphQL :

input TodoChatSessionInput {
  title: String
  todoChatId: Int
  todoId: Int
  createFromChatAsDataSourceId: Int
  defaultBotId: Int
  fromBotPromptId: Int
  toogleChatGptVersion: Boolean
  autoReplyLMM: Boolean
  chatCollectionId: Int
  uiLayout: String
}

Descriptions des champs :

Exemple d'utilisation :

const basicSession = {
  title: 'Support Chat',
  todoId: 12345,
};

const sessionWithBot = {
  title: 'Sales Inquiry',
  todoId: 12345,
  defaultBotId: 789,
};

const compactSession = {
  title: 'Quick Chat',
  todoId: 12345,
  uiLayout: 'COMPACT',
};

BotCustomConfigInput

Entrée pour la configuration personnalisée du bot.

Type d'entrée GraphQL :

input BotCustomConfigInput {
  botId: Int!
  sessionId: Int
  model: String
  temperature: Float
}

Descriptions des champs :

Exemple d'utilisation :

const botConfig = {
  botId: 123,
  sessionId: 67890,
  model: 'gpt-4',
  temperature: 0.7,
};

Requêtes

getTodoChatSessions

Obtenir une liste paginée des sessions de chat.

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 :

Renvoie : Objet avec un tableau d'sessionss et totalCount

Exemple :

const result = await client.query({
  query: gql`
    query GetTodoChatSessions($todoId: Float!, $limit: Int, $offset: Int) {
      getTodoChatSessions(todoId: $todoId, limit: $limit, offset: $offset) {
        sessions {
          id
          title
          createdAt
        }
        totalCount
      }
    }
  `,
  variables: { todoId: 12345, limit: 20, offset: 0 },
});

console.log(`Total sessions: ${result.data.getTodoChatSessions.totalCount}`);

getOneTodoChatSession

Obtenir les détails 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 :

Renvoie : Objet TodoChatSession complet avec les messages

getOrCreateUserStartTodoChatSession

Obtenir ou créer la session de démarrage par défaut pour un utilisateur.

Requête GraphQL :

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

Paramètres :

Renvoie : objet TodoChatSession (créé s'il n'existe pas)

getSearchTodoChatSessions

Recherche les sessions de chat par chaîne de requête.

Requête GraphQL :

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

Paramètres :

Renvoie : tableau d'objets TodoChatSession correspondants

getSpeechFromText

Obtenir l'URL audio pour la conversion texte-parole.

Requête GraphQL :

query GetSpeechFromText($messageId: Float!) {
  getSpeechFromText(messageId: $messageId)
}

Paramètres :

Renvoie : chaîne URL audio

Mutations

sendNewMessage

Envoie un nouveau message et déclenche une réponse en streaming.

Mutation GraphQL :

mutation SendNewMessage($newMessageData: NewMessageInput!) {
  sendNewMessage(newMessageData: $newMessageData) {
    id
    message
    createdAt
    sessionId
    sentBy {
      id
      firstName
      lastName
    }
    isBotReply
  }
}

Paramètres :

Renvoie : objet TodoChatMessage

Exemple :

const { data } = await client.mutate({
  mutation: gql`
    mutation SendNewMessage($newMessageData: NewMessageInput!) {
      sendNewMessage(newMessageData: $newMessageData) {
        id
        message
      }
    }
  `,
  variables: {
    newMessageData: {
      message: 'Hello!',
      sessionId: 67890,
      isForAiReply: true,
    },
  },
});

syncBotRequest

Envoie un message et obtient une réponse complète (non streaming).

Mutation GraphQL :

mutation SyncBotRequest($newMessageData: NewMessageInput!) {
  syncBotRequest(newMessageData: $newMessageData) {
    text
    botId
    botSlug
    isBotError
    sessionId
    files
    sourceMetadatas
    sources
    responseJson
    jobId
  }
}

Paramètres :

Renvoie : objet SyncBotResponse

regenerateResponse

Régénère la réponse du bot pour un message.

Mutation GraphQL :

mutation RegenerateResponse($messageId: Float!) {
  regenerateResponse(messageId: $messageId) {
    id
    message
    createdAt
  }
}

Paramètres :

Renvoie : objet TodoChatMessage (nouvelle réponse)

stopAIResponse

Arrête la génération de réponse IA en cours.

Mutation GraphQL :

mutation StopAIResponse($sessionId: Float!, $botId: Float!) {
  stopAIResponse(sessionId: $sessionId, botId: $botId)
}

Paramètres :

Renvoie : booléen (vrai si l'arrêt a réussi)

retryBotMessage

Réessayer d'envoyer un message qui a échoué.

Mutation GraphQL :

mutation RetryBotMessage($sessionId: Float!) {
  retryBotMessage(sessionId: $sessionId)
}

Paramètres :

Renvoie : booléen (vrai si la nouvelle tentative a réussi)

createTodoChatSession

Crée une nouvelle session de chat.

Mutation GraphQL :

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

Paramètres :

Renvoie : objet TodoChatSession

updateTodoChatSession

Mettre à jour une session existante.

Mutation GraphQL :

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

Paramètres :

Renvoie : objet TodoChatSession

deleteTodoChatSession

Supprimer une seule session.

Mutation GraphQL :

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

Paramètres :

Renvoie : objet TodoChatSession

deleteManyTodoChatSession

Supprime plusieurs sessions en une seule opération.

Mutation GraphQL :

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

Paramètres :

Renvoie : nombre de sessions supprimées

updateTodoChatSessionCustomBotConfig

Mettre à jour la configuration du bot pour une session.

Mutation GraphQL :

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

Paramètres :

Renvoie : Objet TodoChatSession

Abonnements

onMessageStream

S'abonner au flux de messages en temps réel.

Abonnement GraphQL :

subscription OnMessageStream($sessionId: Float!) {
  onMessageStream(sessionId: $sessionId) {
    messageChunk
    userId
    id
    botId
    botResponseMessageId
    isStoppable
  }
}

Paramètres :

Émet : objets ChatStreamMessage

newMessage

S'abonner aux nouveaux messages complets.

Abonnement GraphQL :

subscription NewMessage($sessionId: Float!) {
  newMessage(sessionId: $sessionId) {
    id
    message
    createdAt
    sentBy {
      firstName
    }
    isBotReply
  }
} 

Paramètres :

Émet : objets TodoChatMessage

newIntermediateMessage

S'abonner aux messages intermédiaires (étapes de réflexion).

Abonnement GraphQL :

subscription NewIntermediateMessage($sessionId: Float!) {
  newIntermediateMessage(sessionId: $sessionId) {
    id
    message
    createdAt
    isBotReply
  }
}

Paramètres :

Émet : objets TodoChatMessage

onAgentToolCall

S'abonner aux événements d'appel de l'outil agent.

Abonnement GraphQL :

subscription OnAgentToolCall($sessionId: Float!) {
  onAgentToolCall(sessionId: $sessionId) {
    tool
    toolImage
    botId
    id
    status
  }
}

Paramètres :

Émet : objets AgentToolCall

userTyping

S'abonner aux événements de saisie de l'utilisateur.

Abonnement GraphQL :

subscription UserTyping($sessionId: Float!) {
  userTyping(sessionId: $sessionId) {
    id
    firstName
    lastName
  }
}

Paramètres :

Émet : objets utilisateur

botAnalyzingDatasources

S'abonner aux événements de la source de données d'analyse du bot.

Abonnement GraphQL :

subscription BotAnalyzingDatasources($sessionId: Float!) {
  botAnalyzingDatasources(sessionId: $sessionId) {
    id
    firstName
  }
}

Paramètres :

Émet : objets utilisateur

Points de terminaison API

Points de terminaison REST

URL de base : https://graphql.swiftask.ai

Points de terminaison GraphQL

URL de base : https://graphql.swiftask.ai (HTTP) ou wss://graphql.swiftask.ai (WebSocket)

En-têtes requis

Toutes les requêtes GraphQL doivent inclure les en-têtes suivants :

Les connexions WebSocket utilisent l'connectionParamse au lieu des en-têtes :

connectionParams: {
  authorization: `Bearer ${accessToken}`,
  workspaceId: workspaceId,
}

Modèles courants

Pagination

Lorsque vous répertoriez les sessions, utilisez limit et offset pour la pagination :

// Get first 20 sessions
const page1 = await client.query({
  variables: { todoId, limit: 20, offset: 0 },
});

// Get next 20 sessions
const page2 = await client.query({
  variables: { todoId, limit: 20, offset: 20 },
});

// Get total count
const totalCount = page1.data.getTodoChatSessions.totalCount;
const totalPages = Math.ceil(totalCount / 20);Error handling

Toutes les opérations peuvent échouer. Traitez les erreurs de manière cohérente :

try {
  const { data } = await client.mutate({ mutation });
  return data;
} catch (error) {
  if (error.graphQLErrors?.length > 0) {
    console.error('GraphQL Error:', error.graphQLErrors[0].message);
  } else if (error.networkError) {
    console.error('Network Error:', error.networkError);
  } else {
    console.error('Unknown Error:', error);
  }
  throw error;
}

Gestion des valeurs nulles

Certains champs sont facultatifs. Vérifiez toujours s'ils sont nuls :

const message = data.sendNewMessage;
if (message.files) {
  // Process files
}

if (message.parentMessageId) {
  // This is a threaded reply
}