Translate

Overview

The Translate message converts content into specified languages while preserving the original formatting. Markdown formatting is recommended for optimal results.

API Reference

Endpoint

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

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

Request Payload

The translate message requires a payload containing a session object and a request object with a connections.threadId, a scope.conversations array that includes the conversation history, 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: {
      variant: "A"
    },
    connections: {
      threadId: "9e8d7c6b-5a49-3827-1605-948372615abc" // REQUIRED
    },
    context: { // generated by optave
      organizationId: "f7e8d9c0-b1a2-3456-7890-123456789abc" // REQUIRED
    },
    scope: {
      conversations: [ // REQUIRED
        {
          conversationId: "7f6e5d4c-3b2a-1098-fedc-ba9876543210",
          participants: [
            {
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              displayName: "John Doe",
              role: "user"
            },
            {
              participantId: "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
              displayName: "Sarah Smith",
              role: "operator"
            }
          ],
          messages: [
            {
              content: "Hola, ¿me puede ayudar con mi consulta?",
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              timestamp: "2024-01-15T10:30:00.000Z"
            },
            {
              content: "¡Por supuesto! Estaré encantada de ayudarle con su consulta.",
              participantId: "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
              timestamp: "2024-01-15T10:30:15.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: "translate",
    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: {
        variant: "A"
      },
      connections: {
        threadId: "9e8d7c6b-5a49-3827-1605-948372615abc" // REQUIRED
      },
      context: { // generated by optave
        organizationId: "f7e8d9c0-b1a2-3456-7890-123456789abc" // REQUIRED
      },
      scope: {
        conversations: [ // REQUIRED
          {
            conversationId: "7f6e5d4c-3b2a-1098-fedc-ba9876543210",
            participants: [
              {
                participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
                displayName: "John Doe",
                role: "user"
              },
              {
                participantId: "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
                displayName: "Sarah Smith",
                role: "operator"
              }
            ],
            messages: [
              {
                content: "Hola, ¿me puede ayudar con mi consulta?",
                participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
                timestamp: "2024-01-15T10:30:00.000Z"
              },
              {
                content: "¡Por supuesto! Estaré encantada de ayudarle con su consulta.",
                participantId: "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
                timestamp: "2024-01-15T10:30:15.000Z"
              }
            ],
            metadata: {}
          }
        ]
      }
    }
  },
  action: "message"
}

Responses

🟢 Success (200-201)

The response consists of a translate superpower.

{
  action: "superpower",
  actionType: "translate",
  state: "completed",
  message: {
    results: [
      {
        response: [
          {
            content: "¡Bienvenido a nuestro servicio! ¿Cómo puedo ayudarte hoy?"
          }
        ]
      }
    ]
  }
}

The response includes the translated content while maintaining any formatting present in the original text.

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