Reprendre une conversation existante
Guide pratique - continuer une conversation multi-tour entre plusieurs requêtes de canal API en utilisant conversation_id.
Utilisez ce guide lorsque vous devez maintenir le contexte entre plusieurs requêtes sur le même canal - par exemple, un chat de support multi-tour ou un workflow avec état.
Résultat attendu : les requêtes suivantes continuent le même fil de conversation, préservant le contexte du flow des tours précédents.
Fonctionnement des conversations
- L'omission de
conversation_iddémarre une nouvelle conversation. Le serveur assigne un UUID et le retourne dansconversation_id(réponse JSON ou événement SSEdata-run). - La fourniture de
conversation_idreprend une conversation existante, qui porte l'état construit par le flow lors des tours précédents. - Une conversation appartient à un canal et un tenant spécifiques. Vous ne pouvez pas reprendre une conversation du canal A sur le canal B.
Étape 1 - Démarrer une conversation
Envoyez la première requête sans conversation_id :
curl -X POST "https://api.example.com/public/v1/api/execute" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"payload":"J'"'"'ai besoin d'"'"'aide avec la commande #12345"}'Réponse :
{
"run_id": "9c1d…",
"conversation_id": "b1f2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "success",
"output": { "text": "Je peux vous aider. Quel est le problème avec la commande #12345 ?" }
}Stockez le conversation_id.
Étape 2 - Envoyer un message de suivi
Incluez conversation_id dans la requête suivante :
curl -X POST "https://api.example.com/public/v1/api/execute" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"payload":"Je ne l'"'"'ai jamais reçue","conversation_id":"b1f2c3d4-e5f6-7890-abcd-ef1234567890"}'Le flow reçoit l'historique complet de la conversation et répond en conséquence.
Exemple TypeScript
class ApiConversation {
private conversationId: string | null = null;
constructor(private readonly apiKey: string) {}
async send(message: string): Promise<string> {
const body = JSON.stringify({
payload: message,
stream: false,
...(this.conversationId ? { conversation_id: this.conversationId } : {}),
});
const response = await fetch('https://api.example.com/public/v1/api/execute', {
method: 'POST',
headers: {
Authorization: `Bearer ${this.apiKey}`,
'Content-Type': 'application/json',
},
body,
});
const data = await response.json();
if (!response.ok) throw new Error(data.error?.code);
this.conversationId = data.conversation_id;
return data.output?.text ?? '';
}
}Reprise inter-canal
Tenter de reprendre une conversation sur un canal différent retourne conversation_not_found (404) - la même erreur utilisée pour les identifiants inconnus. C'est intentionnel : le serveur ne révèle pas si une conversation existe sur un autre canal.
Référence
Pour les contraintes du champ conversation_id et les codes d'erreur, voir la référence d'API - section Conversations.
Construire votre première intégration API
Tutoriel - connecter un service backend à un flow nAIxus via le canal API. Un parcours complet de la création du canal à la réponse JSON et au streaming.
Renouveler les credentials
Guide pratique - renouveler la clé d'API ou le secret de signature HMAC d'un canal API sans interruption de service.