Elevate

Overview

The Elevate message enhances an agent's response by improving tone, correcting mistakes, and adding context. It provides comprehensive feedback and scoring on various aspects of agent performance.

API Reference

Endpoint

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

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

Request Payload

The elevate message requires a payload containing the conversation history (conversations), connections.threadId, connections.parentId (ID of the message to edit), the content to be elevated (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: "Hello! How can I assist you today?", // REQUIRED - content of the edited message
      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
      caseId: "",
      departmentId: "",
      operatorId: "",
      organizationId: "f7e8d9c0-b1a2-3456-7890-123456789abc", // REQUIRED
      userId: ""
    },
    reference: {
      ids: [
        { name: "", value: "" }
      ],
      labels: [],
      tags: []
    },
    resources: {
      codes: [],
      links: [],
      offers: []
    },
    scope: {
      conversations: [ // REQUIRED
        {
          conversationId: "",
          participants: [
            {
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              displayName: "John Doe",
              role: "user"
            }
          ],
          messages: [
            {
              content: "Hi, can you help me?",
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              timestamp: "2024-01-15T10:30:00.000Z"
            }
          ],
          metadata: {}
        }
      ],
      interactions: [
        {
          content: "Support ticket T12345 has been created for user John Doe",
          id: "1",
          name: "ticket_created",
          role: "system",
          timestamp: "2024-01-15T10:29:45.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: "elevate",
    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: "Hello! How can I assist you today?", // REQUIRED - content of the edited message
        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
        caseId: "",
        departmentId: "",
        operatorId: "",
        organizationId: "f7e8d9c0-b1a2-3456-7890-123456789abc", // REQUIRED
        userId: ""
      },
      reference: {
        ids: [
          { name: "", value: "" }
        ],
        labels: [],
        tags: []
      },
      resources: {
        codes: [],
        links: [],
        offers: []
      },
      scope: {
        conversations: [ // REQUIRED
          {
            conversationId: "",
            participants: [
              {
                participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
                displayName: "John Doe",
                role: "user"
              }
            ],
            messages: [
              {
                content: "Hi, can you help me?",
                participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
                timestamp: "2024-01-15T10:30:00.000Z"
              }
            ],
            metadata: {}
          }
        ],
        interactions: [
          {
            content: "Support ticket T12345 has been created for user John Doe",
            id: "1",
            name: "ticket_created",
            role: "system",
            timestamp: "2024-01-15T10:29:45.000Z"
          }
        ]
      }
    }
  },
  action: "message"
}

Responses

🟢 Success (200-201)

The response consists of an improve_answer superpower.

{
  action: "superpower",
  actionType: "improve_answer",
  state: "completed",
  message: {
    results: [
      {
        response: [
          {
            content: "Hello, John! I'd be happy to assist you today. Could you please share more details about your request so I can help you faster?"
          }
        ]
      }
    ]
  }
}

When using the WebSocket, multiple superpowers and different state updates will be received. Each additional superpower will be sent as a separate message with its specific actionType and relevant results.

🔴 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'
          }
        ]
      }
    ]
  }
}