Skip to main content
Version: 3.2.x

Insights

Overview​

The Insights message provides detailed evaluation of agent performance and customer sentiment analysis. It uses multiple criteria to assess the conversation quality without generating AI suggestions.

API Reference​

Endpoint​

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

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

Request Payload​

The insights message requires a payload containing the conversation history (conversations), connections.threadId, and context.organizationId (your client-specific organization ID). The other fields are optional.

{
  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: {
      journeyId: "",
      parentId: "",
      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: "Alice Hawthorne",
              role: "user"
            },
            {
              participantId: "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
              displayName: "Tom Callahan",
              role: "operator"
            }
          ],
          messages: [
            {
              content: "My flight was cancelled and I need to rebook",
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              timestamp: "2024-01-15T10:30:00.000Z"
            },
            {
              content: "I understand this is frustrating. Let me help you with rebooking your flight. Could you please provide your booking reference?",
              participantId: "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
              timestamp: "2024-01-15T10:30:30.000Z"
            },
            {
              content: "Sure, it is XYZ789",
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              timestamp: "2024-01-15T10:31:00.000Z"
            }
          ],
          metadata: {}
        }
      ],
      interactions: [
        {
          content: "Support ticket T12345 has been created for user Alice Hawthorne",
          id: "1",
          name: "ticket_created",
          role: "system",
          timestamp: "2024-01-15T10:29:45.000Z"
        }
      ]
    }
  }
}

Responses​

🟢 Success (200-201)

When using the WebSocket, multiple evaluation criteria and sentiment analysis can be received as separate messages. The responses might include examples as below:

{
  action: "superpower",
  actionType: "performance_criteria",
  state: "completed",
  message: {
    results: [
      {
        //?
      }
    ]
  }
}
{
  action: "superpower",
  actionType: "sentiment_analysis",
  state: "completed",
  message: {
    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"
          }
        ]
      }
    ]
  }
}

curl 
  --request POST 
  --url https://{{tenant}}.oco.optave.{{tld}}/message/insights  
  --header "Authorization: Bearer your-access-token-here"  
  --header "Content-Type: application/json"  
  -d '{
    "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"
      },
      "context": {
        "organizationId": "f7e8d9c0-b1a2-3456-7890-123456789abc"
      },
      "scope": {
        "conversations": [
          {
            "conversationId": "7f6e5d4c-3b2a-1098-fedc-ba9876543210",
            "participants": [
              {
                "participantId": "2c4f8a9b-1d3e-5f70-8293-456789012def",
                "displayName": "Alice Hawthorne",
                "role": "user"
              },
              {
                "participantId": "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
                "displayName": "Tom Callahan",
                "role": "operator"
              }
            ],
            "messages": [
              {
                "content": "My flight was cancelled and I need to rebook",
                "participantId": "2c4f8a9b-1d3e-5f70-8293-456789012def",
                "timestamp": "2024-01-15T10:30:00.000Z"
              },
              {
                "content": "I understand this is frustrating. Let me help you with rebooking your flight. Could you please provide your booking reference?",
                "participantId": "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
                "timestamp": "2024-01-15T10:30:30.000Z"
              },
              {
                "content": "Sure, it is XYZ789",
                "participantId": "2c4f8a9b-1d3e-5f70-8293-456789012def",
                "timestamp": "2024-01-15T10:31:00.000Z"
              }
            ],
            "metadata": {}
          }
        ]
      }
    }
  }'
{
  action: "superpower",
  actionType: "<superpower-name>",
  state: "completed",
  message: {
    results: [
      {
        response: [
          {
            // Content depends on superpower
          }
        ]
      }
    ]
  }
}