Vous avez créé une tâche de provisioning et récupéré un ID de tâche pjb_ ainsi qu'un ID de moteur eng_ en quelques millisecondes. Le moteur est déjà utilisable, mais il continue de se compléter : un agent IA parcourt vos sources et y consigne des voix de marque, des entrées de glossaire et des instructions. Pendant ce temps, vous voulez montrer ce qui se passe — une ligne du type « Analyse de votre guide de style… configuration du moteur… terminé », comme dans un assistant d'installation, plutôt qu'un simple spinner muet.
Le WebSocket vous donne exactement ce flux. Connectez-vous à la tâche et le serveur envoie un instantané de l'état actuel, puis un événement provisioning.progress chaque fois que le workflow passe à une nouvelle étape. Et comme le serveur envoie l'état courant dès la connexion puis ferme immédiatement une tâche terminée, vous pouvez vous connecter à tout moment, même après la fin — il n'y a aucune fenêtre à ne pas rater.
GET /jobs/provisioning/:jobId/wsLe jobId correspond à la valeur pjb_ renvoyée par l'appel de création. Vous découvrez le provisioning asynchrone ? Commencez par la Vue d'ensemble pour bien comprendre le modèle.
Sur cette page
- Types de messages
- Instantané à la connexion
- Événements de progression
- Se connecter après la fin de la tâche
- L'intégrer à votre interface
- Gardez votre clé API côté serveur
Types de messages#
Deux types de messages transitent sur le socket. Le premier n'arrive qu'une seule fois, à la connexion ; le second arrive ensuite à répétition, à mesure que la tâche avance.
| Type | Quand | Champs clés |
|---|---|---|
provisioning.snapshot | À la connexion initiale | jobId, status, errorMessage |
provisioning.progress | Au début ou à la fin de chaque étape du workflow | jobId, step, detail |
Il s'agit d'un flux d'activité, pas d'un flux de résultats : il vous indique où en est la tâche et si elle a échoué, mais pas quels enregistrements l'IA a créés. Le récapitulatif de tout ce qui a été provisionné — les ID de voix de marque, de glossaire et d'instructions — arrive séparément, dans le webhook de fin ou en relisant la tâche une fois terminée. Réservez le socket à la barre de progression ; utilisez le webhook pour la charge utile.
Instantané à la connexion#
Dès la connexion, le serveur lit l'état actuel de la tâche dans la base de données et l'envoie. Aucun événement de progression préalable n'est nécessaire — l'instantané se suffit à lui-même.
{
"type": "provisioning.snapshot",
"jobId": "pjb_A1b2C3d4E5f6G7h8",
"status": "in_progress",
"errorMessage": null
}| Champ | Description |
|---|---|
status | in_progress, completed ou failed. |
errorMessage | La description de l'échec lorsque status vaut failed, sinon null. |
L'instantané est le seul message que vous êtes certain de recevoir. Si la tâche est encore en cours, vous recevrez ensuite des événements de progression ; si elle est déjà terminée, vous recevrez l'instantané, et rien de plus (voir ci-dessous).
Événements de progression#
Pendant l'exécution du workflow, le serveur diffuse un événement provisioning.progress chaque fois qu'il entre dans une nouvelle étape. Chaque événement indique le step et contient un detail lisible par un humain.
{
"type": "provisioning.progress",
"jobId": "pjb_A1b2C3d4E5f6G7h8",
"step": "crawling",
"detail": "Crawling source URLs..."
}step | Quand | Exemple de detail |
|---|---|---|
crawling | Les URL sources sont en cours de récupération | "Crawling source URLs..." ou "Retrying crawl (attempt 2)..." |
configuring | L'agent IA analyse le contenu et rédige la configuration du moteur | "AI agent analyzing content and configuring engine..." ou "Retrying configuration (attempt 2)..." |
completed | La tâche s'est terminée avec succès | "Provisioning complete" |
failed | La tâche a échoué | Un message d'erreur décrivant l'échec |
Une nouvelle tentative n'est pas un échec
Les étapes crawling et configuring peuvent se produire plusieurs fois — une erreur transitoire de récupération ou d'analyse déclenche une nouvelle tentative, qui apparaît comme un événement de progression avec un detail du type "Retrying crawl (attempt 2)...". Cela signifie que la tâche se rétablit, pas qu'elle a échoué. Ne considérez comme terminale que l'étape failed ; son detail contient la vraie raison.
Gérez les étapes que vous ne reconnaissez pas
De nouvelles valeurs de step peuvent être ajoutées au fil du temps. Gérez les étapes que vous connaissez, considérez completed et failed comme les deux qui ferment le socket, et traitez tout le reste comme purement informatif — un client compatible avec les évolutions futures continue de fonctionner sans mise à jour.
Se connecter après la fin de la tâche#
La vraie question, avec tout socket de progression, est ce qui se passe si vous vous connectez tard — une fois l'exploration terminée, après qu'un déploiement a reconnecté l'onglet, ou après l'échec de la tâche. Ici, la réponse tient directement au fonctionnement de l'instantané.
Si la tâche a déjà atteint completed ou failed, le serveur envoie l'instantané avec ce status final (et errorMessage, en cas d'échec), puis ferme immédiatement la connexion. Il n'y a aucun événement de progression à rejouer, puisque l'état final est déjà dans l'instantané. Une tâche encore en cours garde la connexion ouverte et diffuse sa progression ; une tâche terminée vous donne le résultat, puis coupe la ligne.
Dans tous les cas, le premier message vous indique où en sont les choses. Connectez-vous à tout moment, même après la fin — vous ne pouvez ni arriver trop tôt, ni trop tard.
L'intégrer à votre interface#
Ouvrez le socket avec l'ID de tâche pjb_, lisez l'instantané pour définir votre état initial, puis mettez à jour à chaque événement de progression et fermez lorsque la tâche atteint completed ou failed :
import WebSocket from "ws";
const jobId = "pjb_A1b2C3d4E5f6G7h8";
const ws = new WebSocket(
`wss://api.lingo.dev/jobs/provisioning/${jobId}/ws`,
{ headers: { "X-API-Key": process.env.LINGO_API_KEY } }
);
ws.on("message", (raw) => {
const event = JSON.parse(raw);
switch (event.type) {
case "provisioning.snapshot":
console.log(`status: ${event.status}`);
break;
case "provisioning.progress":
console.log(`${event.step}: ${event.detail}`);
if (event.step === "completed" || event.step === "failed") {
ws.close();
}
break;
}
});Exécutez-le sur une tâche dont l'exploration se déroule sans accroc et qui affiche la configuration en train de s'écrire, étape par étape :
status: in_progress
crawling: Crawling source URLs...
configuring: AI agent analyzing content and configuring engine...
completed: Provisioning completeC'est toute la séquence à l'écran : la tâche s'ouvre sur in_progress, vous la voyez d'abord explorer puis configurer, et completed vous indique que le moteur est entièrement provisionné. La même boucle reste valable en cas de connexion tardive — une tâche terminée envoie un seul instantané avec son status final, puis le socket se ferme ; le code qui gère l'exécution en direct gère donc aussi le rejeu, sans cas particulier.
Gardez votre clé API côté serveur#
Le socket s'authentifie avec votre clé API — la même clé à portée organisationnelle que celle utilisée par les endpoints REST. Cette clé donne accès à chaque moteur de votre organisation ; le navigateur est donc le pire endroit pour ouvrir la connexion : n'importe qui affichant le code source pourrait la voir.
Connectez-vous depuis votre backend, pas depuis le navigateur
Ouvrez le WebSocket depuis votre serveur, où la clé se trouve déjà, puis retransmettez la progression au navigateur via votre propre canal — un WebSocket ou un flux d'événements envoyés par le serveur que vous contrôlez. Votre frontend affiche le moteur en cours de configuration ; votre clé, elle, ne quitte jamais votre infrastructure.
C'est le même principe que pour les webhooks : la connexion qui échange avec Lingo.dev s'exécute côté serveur, et ce qui parvient à l'utilisateur dépend entièrement de ce que votre propre application choisit de retransmettre.
Où cela s'intègre#
Le WebSocket est la vue en direct — il est lié à une seule tâche et se ferme lorsque cette tâche est terminée. Pour disposer d'une trace durable, de serveur à serveur, du résultat — qui survive à un onglet fermé ou à un déploiement — associez-lui le webhook de fin : le socket alimente la barre de progression tant que la tâche est à l'écran, tandis que le webhook livre le récapitulatif de tout ce que l'IA a créé dès qu'il est disponible. Branchez les deux depuis le même appel de création.
