Introduction à l'API

L'API Swiftask permet aux développeurs d'interagir de manière programmatique avec les agents IA de Swiftask. Vous pouvez envoyer des messages, gérer des conversations, joindre des fichiers et recevoir des réponses générées par l'IA par le biais de simples points d'extrémité HTTP.

Présentation

L'API Swiftask vous permet de :

• Envoyer des messages à des agents IA et recevoir des réponses

• Gérer l'historique des conversations entre les sessions

• Joindre et traiter des fichiers (documents, images, etc.)

• Configurer les modes d'analyse des documents (SIMPLE ou AVANCÉ) pour le traitement des fichiers

• Suivre l'utilisation et la consommation de crédits par demande

• Gérer les conversations et les commentaires des widgets

L'API est conçue pour les développeurs qui souhaitent intégrer les agents Swiftask AI dans leurs propres applications, automatiser des flux de travail ou créer des solutions personnalisées basées sur Swiftask.

Conditions préalables

Pour utiliser l'API Swiftask, vous devez disposer :

• D'un compte Swiftask (inscrivez-vous sur swiftask.ai)

• D'un accès à un espace de travail

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

• Le jeton client et le slug (identifiant unique) de votre agent

Guide étape par étape

1. Obtenez vos identifiants API

Chaque agent IA dans Swiftask dispose de ses propres identifiants API dont vous aurez besoin pour l'authentification.

Trouvez votre jeton API et votre slug :

1. Ouvrez votre agent dans Swiftask

2. Accédez aux paramètres de l'agent

3. Cliquez sur Développeur dans la barre latérale gauche

4. Vous verrez deux valeurs importantes :

• Client token de l'agent : votre jeton d'authentification API (par exemple, 91ae5e07-1e98-466e-af41-e88b550692b8)

• Slug unique de l'agent : l'identifiant unique de votre agent (par exemple, blank-templatexlxjz)

Important : conservez votre jeton en lieu sûr. Toute personne ayant accès à votre jeton peut effectuer des requêtes API au nom de votre agent et utiliser vos crédits.

2. Comprendre l'authentification

Toutes les requêtes API doivent inclure une authentification. Il existe deux méthodes d'authentification en fonction de votre cas d'utilisation :

Méthode d'authentification 1 : jeton porteur (pour serveur à serveur)

Incluez le jeton dans les en-têtes de votre requête :

Authorization: Bearer YOUR_CLIENT_TOKEN
Content-Type: application/json

Méthode d'authentification 2 : jeton client dans la requête (pour les requêtes de widget)

Incluez le jeton en tant que paramètre de requête :

?clientToken=YOUR_CLIENT_TOKEN 

3. URL de base de l'API

Toutes les requêtes API doivent être envoyées à :

https://graphql.swiftask.ai/api

4. Effectuez votre première requête API

Voici un exemple simple d'envoi d'un message à votre agent IA :

Exemple cURL :

curl -X POST 'https://graphql.swiftask.ai/api/ai/blank-templatexlxjz' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_CLIENT_TOKEN' \
  -d '{
    "input": "Hello, how can I help you today?",
    "sessionId": 12345,
    "messageHistory": [],
    "files": [],
    "documentAnalysisMode": "SIMPLE"
  }'

Remplacez :

• blank-templatexlxjz par le slug de votre agent

• YOUR_CLIENT_TOKEN par votre jeton client

API disponibles

1. API Chat

Envoyez des messages à votre agent IA et recevez des réponses.

Point de terminaison : POST /api/ai/{slug}

Authentification : jeton porteur dans l'en-tête d'autorisation

Corps de la requête :

Réponse :

{
  "text": "Agent response here",
  "botId": 123,
  "botSlug": "agent-slug",
  "sessionId": 1001,
  "totalBotUsage": 45,
  "files": [],
  "isBotError": false,
  "tokenUsage": {
    "inputTokens": 150,
    "outputTokens": 300,
    "totalTokens": 450
  }
}

Principales fonctionnalités :

• Envoyez des SMS à votre agent

• Joindre des fichiers à analyser (documents, images, etc.)

• Conservez le contexte de la conversation grâce à l'historique des messages

• Configurez les modes d'analyse des documents (SIMPLE ou AVANCÉ)

• Suivez les sessions sur plusieurs demandes

• Surveillez l'utilisation des jetons et la consommation de crédits

2. API de chat pour widget

Envoyez des messages à partir d'un widget public ou d'une interface intégrée.

Point de terminaison : POST /api/widget/ai

Authentification : clientToken dans le paramètre de requête

Corps de la requête :

Exemple :

curl -X POST 'https://graphql.swiftask.ai/api/widget/ai?clientToken=YOUR_CLIENT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "input": "Tell me about your products",
    "sessionId": "user-session-123"
  }'

3. API de configuration des widgets

Récupérer l'apparence et la configuration du widget.

Point de terminaison : GET /api/widget/config

Authentification : clientToken dans le paramètre de requête

Exemple :

curl 'https://graphql.swiftask.ai/api/widget/config?clientToken=YOUR_CLIENT_TOKEN'

Réponse : paramètres d'apparence du widget (couleurs, avatar, etc.)

4. API de commentaires sur les widgets

Envoyez des commentaires sur les réponses des agents.

Point de terminaison : POST /api/widget/feedback

Authentification : clientToken dans le paramètre de requête

Corps de la requête :

Exemple :

curl -X POST 'https://graphql.swiftask.ai/api/widget/feedback?clientToken=YOUR_CLIENT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "feedback": "POSITIVE",
    "comment": "Very helpful response!",
    "sessionId": 12345
  }'

5. API « J'aime/Je n'aime pas »

Envoyez des commentaires « J'aime » ou « Je n'aime pas » sur des messages individuels.

Point de terminaison : POST /api/widget/like-dislike

Corps de la requête :

Exemple :

curl -X POST 'https://graphql.swiftask.ai/api/widget/like-dislike' \
  -H 'Content-Type: application/json' \
  -d '{
    "messageId": 5678,
    "feedback": "POSITIVE"
  }'

6. API Get Conversation

Récupérer une conversation par ID de session.

Point de terminaison : GET /api/widget/conversation

Paramètres de requête :

Exemple :

curl 'https://graphql.swiftask.ai/api/widget/conversation?sessionId=user-session-123'

7. API de suppression de conversation

Supprimer une conversation par ID de session.

Point de terminaison : POST /api/widget/conversation/delete

Paramètres de requête :

Exemple :

curl -X POST 'https://graphql.swiftask.ai/api/widget/conversation/delete?sessionId=user-session-123' 

8. API URL signée S3

Obtenir une URL signée pour télécharger des fichiers vers S3.

Point de terminaison : GET /widget/get-signed-url

Paramètres de requête :

Exemple :

curl 'https://graphql.swiftask.ai/widget/get-signed-url?fileName=document.pdf' 

Réponse :

{
  "signedUrl": "https://s3.amazonaws.com/...",
  "fileUrl": "https://..."
}

Authentification et sécurité

Sécurisez votre jeton API

Votre jeton API vous donne un accès complet à votre agent IA. Suivez ces bonnes pratiques en matière de sécurité :

À faire :

• Stockez les jetons dans des variables d'environnement

• Utilisez des coffres-forts sécurisés ou des systèmes de gestion des secrets

• Faites tourner régulièrement les jetons

• Mettre en œuvre des contrôles d'accès basés sur les jetons

À ne pas faire :

• Exposer les jetons dans le code côté client

• Commiter les jetons dans le contrôle de version (Git)

• Partager les jetons publiquement

• Intégrer les jetons en dur dans votre application

Exemple de variable d'environnement

# .env file
SWIFTASK_API_KEY=91ae5e07-1e98-466e-af41-e88b550692b8
SWIFTASK_AGENT_SLUG=blank-templatexlxjz

import os

api_key = os.getenv('SWIFTASK_API_KEY')
agent_slug = os.getenv('SWIFTASK_AGENT_SLUG')

Format de requête et de réponse

Structure de la requête

Toutes les requêtes API utilisent le format JSON et doivent inclure les en-têtes suivants :

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY  (for /api/ai/*)

Gestion des erreurs

Format de réponse d'erreur :

{
  "error": "Error message describing what went wrong"
}

Codes d'état HTTP courants :

Dépannage

Erreur « Non autorisé » (401)

Cause : jeton API invalide ou manquant

Solution :

• Vérifiez que votre jeton est correct

• Assurez-vous que l'en-tête Authorization est correctement formaté : Bearer YOUR_TOKEN

• Vérifiez que votre jeton n'a pas été révoqué

Erreur « Bad Request » (400)

Cause : corps de requête non valide ou champs obligatoires manquants

Solution :

• Vérifiez que tous les champs obligatoires sont remplis

• Vérifiez que les types de champs correspondent (par exemple, input doit être une chaîne de caractères)

• Validez votre formatage JSON

Erreurs de validation

L'ID de session doit être une chaîne de caractères : assurez-vous que sessionId est une chaîne de caractères et non un nombre

La saisie doit être une chaîne de caractères : assurez-vous que input est une chaîne de caractères, et non un objet ou un tableau

Assistance et ressources

Besoin d'aide ?

• Communauté de développeurs : rejoignez notre Discord pour obtenir de l'aide sur l'API

• Assistance par e-mail : contactez support@swiftask.ai

• Documentation : consultez les guides sur docs.swiftask.ai

• Ouvrir un ticket : Aide → Ouvrir un ticket dans le tableau de bord

Prêt à intégrer ? Commencez par l'API Chat (POST /api/ai/{slug}) pour envoyer votre premier message.