Adjust

Overview

The Adjust message allows an agent to request modifications to previously returned replies. It provides the ability to refine and improve content based on specific instructions given in plain English.

API Reference

Endpoint

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

To be able to send messages, it is necessary to authenticate first.

Request Payload

The adjust message requires a payload containing the conversation history (conversations), connections.threadId, connections.parentId (ID of the message to adjust), the adjustment instructions in attributes (instruction and content), and context.organizationId (your client-specific organization ID). The other fields are optional.

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?", // REQUIRED - content to adjust
      instruction: "Make it very friendly and funny", // REQUIRED - adjustment instruction
      variant: "A"
    },
    connections: {
      journeyId: "",
      parentId: "9e8d7c6b-5a4f-3e2d-1c0b-0987654321ab", // REQUIRED - ID of the message to edit
      threadId: "9e8d7c6b-5a49-3827-1605-948372615abc" // REQUIRED
    },
    context: { // generated by optave
      organizationId: "f7e8d9c0-b1a2-3456-7890-123456789abc", // REQUIRED
    },
    reference: {
      ids: [
        { name: "", value: "" }
      ],
      labels: [],
      tags: []
    },
    resources: {
      codes: [],
      links: [],
      offers: []
    },
    scope: {
      conversations: [ // REQUIRED
        {
          conversationId: "",
          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"
            }
          ],
          metadata: {}
        }
      ]
    }
  }
}

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?", // REQUIRED - content to adjust
        instruction: "Make it very friendly and funny", // REQUIRED - adjustment instruction
        variant: "A"
      },
      connections: {
        journeyId: "",
        parentId: "9e8d7c6b-5a4f-3e2d-1c0b-0987654321ab", // REQUIRED - ID of the message to edit
        threadId: "9e8d7c6b-5a49-3827-1605-948372615abc" // REQUIRED
      },
      context: { // generated by optave
        organizationId: "f7e8d9c0-b1a2-3456-7890-123456789abc", // REQUIRED
      },
      reference: {
        ids: [
          { name: "", value: "" }
        ],
        labels: [],
        tags: []
      },
      resources: {
        codes: [],
        links: [],
        offers: []
      },
      scope: {
        conversations: [ // REQUIRED
          {
            conversationId: "",
            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"
              }
            ],
            metadata: {}
          }
        ]
      }
    }
  },
  action: "message"
}

Responses

🟢 Success (200-201)

The response consists of an adjust_suggestion superpower.

When using the Websocket, multiple other superpowers and different state updates will also be received.

{
  action: "superpower",
  actionType: "adjust_suggestion",
  state: "completed",
  message: {
    results: [
      {
        response: [
          {
            content: 'Friendlier response'
          }
        ]
      }
    ]
  }
}

🔴 Error

Error messages are similar in format to success messages, but contain an error state and a "response" JSON object:

{
  action: "superpower",
  actionType: "<superpower-name>",
  state: "error",
  message: {
    results: [
      {
        response: [
          {
            content: 'Error while fetching results'
          }
        ]
      }
    ]
  }
}