Skip to main content
Version: 3.2.x

Customer Interaction

Deprecation Notice

The Customer Interaction message type will be deprecated in future versions. Please migrate to the new Interaction message type, which provides enhanced features and improved performance for all customer interaction analysis needs.

Overview​

The Customer Interaction message analyzes conversation data to provide comprehensive insights, including sentiment analysis, risk assessment, and other specialized responses.

API Reference​

Endpoint​

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

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

Request Payload​

The customerinteraction 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
      organizationId: "f7e8d9c0-b1a2-3456-7890-123456789abc", // REQUIRED
    },
    reference: {
      ids: [
        { name: "ticket_id", value: "T12345" }
      ],
      labels: [],
      tags: []
    },
    resources: {
      codes: [],
      links: [],
      offers: []
    },
    scope: {
      conversations: [ // REQUIRED
        {
          conversationId: "",
          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: "Hi, can you help me?",
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              timestamp: "2024-01-15T10:30:00.000Z"
            },
            {
              content: "Hello! I'd be happy to assist you today. What can I help you with?",
              participantId: "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
              timestamp: "2024-01-15T10:30:15.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"
        }
      ]
    }
  }
}

Responses​

🟢 Success (200-201)

When using the WebSocket, multiple superpowers and different state updates will be received, such as:

  • Sentiment Analysis
  • Risk Assessment (Media, Hacker, Financial)
  • Escalation Need
  • Language Identification
  • Search Requirements

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

curl
  --request POST
  --url https://{{tenant}}.oco.optave.{{tld}}/message/customerinteraction   
  --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": "John Doe",
                "role": "user"
              },
              {
                "participantId": "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
                "displayName": "Sarah Smith",
                "role": "operator"
              }
            ],
            "messages": [
              {
                "content": "Hi, can you help me?",
                "participantId": "2c4f8a9b-1d3e-5f70-8293-456789012def",
                "timestamp": "2024-01-15T10:30:00.000Z"
              },
              {
                "content": "Hello! I would be happy to assist you today. What can I help you with?",
                "participantId": "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
                "timestamp": "2024-01-15T10:30:15.000Z"
              }
            ],
            "metadata": {}
          }
        ]
      }
    }
  }'
{
  action: "superpower",
  actionType: "<superpower-name>",
  state: "completed",
  message: {
    results: [
      {
        response: [
          {
            // Content depends on superpower
          }
        ]
      }
    ]
  }
}