Ajuster

Aperçu

Le message « Adjust » permet à un agent de demander des modifications à une réponse précédemment renvoyée. Il offre la possibilité d'affiner et d'améliorer le contenu en fonction d'instructions spécifiques données en langage naturel.

Référence API

Point de Terminaison

• URL WebSocket : wss://ws-{{tenant}}.oco.optave.{{tld}}
• Point de Terminaison REST (POST) : https://{{tenant}}.oco.optave.{{tld}}/message/adjust

Pour pouvoir envoyer des messages, il est nécessaire de s'authentifier d'abord.

Charge Utile de Requête

Le message adjust requiert un payload contenant l'historique de conversation (conversations), connections.threadId, connections.parentId (ID du message à ajuster), les instructions d'ajustement dans attributes (instruction et content), et context.organizationId (l'identifiant d'organisation spécifique à votre client). Les autres champs sont optionnels.

REST

{
  session: {
    sessionId: "a1b2c3d4-e5f6-7890-abcd-123456789012",
    channel: { language: "en-US" },
    interface: { type: "chat" }
  },
  request: {
    requestId: "a1b2c3d4-e5f6-7890-1234-56789ab2345",
    attributes: {
      content: "Sure, Lucy! What would you like to know about the helicopter trip?", // REQUIS - contenu à ajuster
      instruction: "Make it very friendly and funny", // REQUIS - instruction d'ajustement
      variant: "A"
    },
    connections: {
      journeyId: "",
      parentId: "9e8d7c6b-5a4f-3e2d-1c0b-0987654321ab", // REQUIS - ID du message à éditer
      threadId: "9e8d7c6b-5a49-3827-1605-948372615abc" // REQUIS
    },
    context: { // généré par optave
      organizationId: "f7e8d9c0-b1a2-3456-7890-123456789abc", // REQUIS
    },
    reference: {
      ids: [
        { name: "", value: "" }
      ],
      labels: [],
      tags: []
    },
    resources: {
      codes: [],
      links: [],
      offers: []
    },
    scope: {
      conversations: [ // REQUIS
        {
          conversationId: "conv-789",
          participants: [
            {
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              displayName: "Lucy Carmichael",
              role: "user"
            }
          ],
          messages: [
            {
              content: "Hi, I have a question about the helicopter trip",
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              timestamp: "2024-01-15T10:30:00.000Z"
            }
          ]
        }
      ]
    }
  }
}

WebSocket

{
  headers: {
    correlationId: "20e35101-61e8-46e0-926d-6af84b378d95",
    tenantId: "6e3j5hdgemmjmoqih5u9b4mmqhrr",
    traceId: "405101-61e8-46e0-926d-6af84b378d95",
    idempotencyKey: "30e35101-61e8-46e0-926d-6af84b378d95",
    identifier: "message",
    action: "adjust",
    schemaRef: "optave.message.v3",
    sdkVersion: "3.2.1",
    timestamp: "2025-09-05T16:30:00.000Z"
  },
  payload: {
    session: {
      sessionId: "a1b2c3d4-e5f6-7890-abcd-123456789012",
      channel: { language: "en-US" },
      interface: { type: "chat" }
    },
    request: {
      requestId: "a1b2c3d4-e5f6-7890-1234-56789ab2345",
      attributes: {
        content: "Sure, Lucy! What would you like to know about the helicopter trip?", // REQUIS - contenu à ajuster
        instruction: "Make it very friendly and funny", // REQUIS - instruction d'ajustement
        variant: "A"
      },
      connections: {
        journeyId: "",
        parentId: "9e8d7c6b-5a4f-3e2d-1c0b-0987654321ab", // REQUIS - ID du message à éditer
        threadId: "9e8d7c6b-5a49-3827-1605-948372615abc" // REQUIS
      },
      context: { // généré par optave
        organizationId: "f7e8d9c0-b1a2-3456-7890-123456789abc", // REQUIS
      },
      reference: {
        ids: [
          { name: "", value: "" }
        ],
        labels: [],
        tags: []
      },
      resources: {
        codes: [],
        links: [],
        offers: []
      },
      scope: {
        conversations: [ // REQUIS
          {
            conversationId: "conv-789",
            participants: [
              {
                participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
                displayName: "Lucy Carmichael",
                role: "user"
              }
            ],
            messages: [
              {
                content: "Hi, I have a question about the helicopter trip",
                participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
                timestamp: "2024-01-15T10:30:00.000Z"
              }
            ]
          }
        ]
      }
    }
  },
  action: "message"
}

Réponses

🟢 Succès (200-201)

La réponse consiste en un superpouvoir adjust_suggestion.

Lors de l'utilisation du WebSocket, plusieurs autres superpouvoirs ainsi que différentes mises à jour d'état peuvent également être reçus.

{
  action: "superpower",
  actionType: "adjust_suggestion",
  state: "completed",
  message: {
    results: [
      {
        response: [
          {
            content: 'Réponse plus amicale'
          }
        ]
      }
    ]
  }
}

🔴 Erreur

Les messages d'erreur ont un format similaire aux messages de succès mais contiennent un état error et un objet JSON "response" :

{
  action: "superpower",
  actionType: "<superpower-name>",
  state: "error",
  message: {
    results: [
      {
        response: [
          {
            content: 'Erreur lors de la récupération des résultats'
          }
        ]
      }
    ]
  }
}