Démarrer avec le SDK JavaScript Swiftask

Écrit par Stanislas

Dernière mise à jour Il y a 16 jours

Intégrez les agents IA dans vos applications en utilisant l'API Swiftask Public Bot. Vous contrôlez l'interface utilisateur ; Swiftask gère l'agent IA, la base de connaissances et le traitement des messages.

Aperçu

L'API Swiftask Public Bot vous permet d'intégrer directement le chat alimenté par l'IA dans vos applications. Vous contrôlez l'interface utilisateur ; Swiftask gère l'agent IA, la base de connaissances et le traitement des messages.

Ce que vous pouvez construire :

  • Interfaces de chat personnalisées alimentées par vos agents Swiftask

  • Conversations multi-sessions (support, ventes, support technique, etc.)

  • Réponses en streaming en temps réel, caractère par caractère

  • Surveiller ce que fait votre agent (appels d'outils, analyse de données)

  • Applications web, applications mobiles ou widgets intégrés

Prérequis

Avant de commencer, vous avez besoin de :

  • Un compte Swiftask (inscrivez-vous sur swiftask.ai)

  • Un agent IA créé dans votre espace de travail

  • Votre jeton client d'agent (depuis la section Développeur)

  • Node.js 14+ ou un navigateur moderne

  • Apollo Client installé (npm install @apollo/client graphql)

  • Connaissances de base en JavaScript (async/await, promesses)

Installation et configuration

Étape 1 : Obtenir votre jeton client

  1. Cliquez sur Agents dans la barre latérale gauche

  2. Trouvez votre agent et cliquez sur le bouton éditer (icône stylo)

  3. Dans le menu de gauche, cliquez sur Développeur

  4. Vous verrez le panneau Développeur avec :

    • Client token de l'agent — Copiez ceci

    • Slug unique de l'agent

    • Options d'intégration ci-dessous

Gardez votre jeton client sécurisé ; il identifie votre agent à l'API.

Étape 2 : Installer les dépendances

npm install @apollo/client graphql

L'API Swiftask utilise Apollo Client (un client GraphQL) pour les requêtes, les mutations et les abonnements en temps réel.

Étape 3 : S'authentifier en 30 secondes

// Générer un identifiant unique pour cet utilisateur/cette session
const clientUuid = crypto.randomUUID();
localStorage.setItem('swiftask_client_uuid', clientUuid);

// Authenticate using your client token from Developer panel
const clientToken = '88576b1c-f933-4679-99b8-3f95e27ef46e';// Remplacez par votre jeton
const response = await fetch(
  `https://graphql.swiftask.ai/public/widget-bot/${clientToken}`,
  {
    method: 'GET',
    headers: { 'x-client-uuid': clientUuid },
  }
);

const { data } = await response.json();
const { accessToken, workspaceId, starterSessionId } = data;

//Vous avez maintenant tout ce qu'il vous faut pour discuter.
console.log('✅ Authentifié ! Prêt à envoyer des messages.');

Étape 4 : Envoyer votre premier message

import { ApolloClient, InMemoryCache, createHttpLink, gql } from '@apollo/client';
import { setContext } from '@apollo/client/link/context';

// Configuration Apollo Client
const httpLink = createHttpLink({
  uri: 'https://graphql.swiftask.ai/graphql',
});

const authLink = setContext((_, { headers }) => ({
  headers: {
    ...headers,
    authorization: `Bearer ${accessToken}`,
    'x-workspace-id': workspaceId,
    'x-client': 'widget',
  },
}));

const client = new ApolloClient({
  link: authLink.concat(httpLink),
  cache: new InMemoryCache(),
});

const SEND_MESSAGE = gql`
  mutation SendNewMessage($newMessageData: NewMessageInput!) {
    sendNewMessage(newMessageData: $newMessageData) {
      id
      message
      createdAt
    }
  }
`;

// Enoyer un message
const result = await client.mutate({
  mutation: SEND_MESSAGE,
  variables: {
    newMessageData: {
      message: 'Bonjour, agent !',
      sessionId: starterSessionId,
      isForAiReply: true,
    },
  },
});

console.log('L\'agent répondra :', result.data.sendNewMessage);

C'est tout ! Vous vous êtes authentifié et avez envoyé un message.

Concepts clés

REST vs. GraphQL

  • REST : GET /public/widget-bot/:clientToken — Authentification

  • GraphQL : https://graphql.swiftask.ai/graphql — Messages, sessions, mises à jour

  • WebSocket : wss://graphql.swiftask.ai/graphql — Streaming en temps réel

Sessions et messages

Imaginez des dossiers :

Utilisateur (authentifié)
  └── Session 1 (fil de conversation)
       ├── Message 1 (utilisateur)
       ├── Message 2 (réponse de l'agent)
       └── Message 3 (utilisateur)
  └── Session 2 (une autre conversation)

Vous obtenez automatiquement un identifiant de session de démarrage (starterSessionId). Vous pouvez également créer de nouvelles sessions pour différentes conversations (assistance, ventes, etc.).

Diffusion en temps réel

Au lieu d'attendre la réponse complète, vous pouvez la diffuser caractère par caractère grâce aux abonnements WebSocket. Idéal pour les interfaces de chat.

Intégrations de frameworks

React

Utilisez un hook personnalisé pour gérer l'authentification et les sessions :

import { useState, useEffect } from 'react';

export function useSwiftaskChat(clientToken) {
  const [messages, setMessages] = useState([]);
  const [streamingMessage, setStreamingMessage] = useState('');
  const [session, setSession] = useState(null);

  useEffect(() => {
    // Initialiser le client, créer une session, configurer les abonnements
  }, [clientToken]);

  const sendMessage = async (text) => {
    // Envoyer un message et écouter la réponse
  };

  return { messages, streamingMessage, sendMessage };
}

Modèles courants

Plusieurs sessions

const supportSession = await chat.createSession('Support');
const salesSession = await chat.createSession('Ventes');

await sendMessage(supportSession.id, 'Ma commande est cassée');
await sendMessage(salesSession.id, 'Parlez-moi de votre tarif');

Diffuser les réponses en temps réel

chat.subscribeToStream(
  sessionId,
  (fullMessage) => {
    console.log('Diffusion :', fullMessage);
  },
  () => {
    console.log('Réponse terminée');
  }
);

Gérer les erreurs avec élégance

try {
  await chat.authenticate();
} catch (error) {
  if (error.message.includes('Invalid client token')) {
    console.error('Check your token in Agents → Edit → Developer');
  } else if (error.message.includes('Agent not found')) {
    console.error('Agent does not exist or is not public');
  }
}

Dépannage

Erreur "Invalid client token"

  • Vérifiez que votre jeton est copié correctement depuis Agents → Éditer → Développeur

  • Assurez-vous de copier la chaîne complète

  • N'ajoutez pas d'espaces supplémentaires

"Agent not found"

  • Vérifiez que votre agent existe et est visible dans le menu Agents

  • L'agent doit être dans le même espace de travail

La connexion WebSocket échoue

  • Utilisez wss:// (WebSocket sécurisé), pas ws://

  • Incluez authorization et workspaceId dans les paramètres

  • Vérifiez que votre réseau autorise les connexions WebSocket

Bonnes pratiques

  • Stocker l'UUID client de manière persistante — Enregistrez-le dans localStorage

  • Gérer l'expiration des jetons — Les jetons durent environ 1 heure

  • Utiliser des blocs try-catch — Toujours envelopper les appels API

  • Diffuser les réponses — Meilleure UX qu'attendre les réponses complètes

  • Organiser les sessions — Utilisez des noms clairs ("Support", "Ventes")

  • Valider l'entrée — Vérifier le texte du message avant d'envoyer

Points de terminaison API

  • REST (auth) : https://graphql.swiftask.ai/public/widget-bot/:clientToken

  • GraphQL : https://graphql.swiftask.ai/graphql

  • WebSocket : wss://graphql.swiftask.ai/graphql

Prêt à construire ? Commencez par l'authentification, puis explorez les guides plus approfondis. Vous aurez une intégration de chat fonctionnelle en quelques minutes. 🚀