Skip to main content
Version: 3.2.x

Recommend

Overview​

The Recommend message provides suggestions based on the conversation context. It helps agents with relevant recommendations to enhance customer interactions.

API Reference​

Endpoint​

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

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

Request Payload​

The recommend message requires a payload containing the conversation history (conversations), connections.threadId, resources.offers, 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: {
      offers: [ // REQUIRED
        {
          // Please contact your optave representative to define the object you should send here
        }
      ]
    },
    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: "I am looking for holiday destinations in December",
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              timestamp: "2024-01-15T10:30:00.000Z"
            },
            {
              content: "I would be happy to help you find the perfect holiday destination. Do you have any specific preferences?",
              participantId: "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
              timestamp: "2024-01-15T10:30:30.000Z"
            },
            {
              content: "I enjoy warm weather and beaches, but also interested in local culture",
              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, you'll receive recommendations and additional evaluation metrics:

{
  action: "superpower",
  actionType: "recommend",
  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/recommend   --header "Authorization: Bearer your-access-token-here"   --header "Content-Type: application/json"   --data '{
    "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"
      },
      "resources": {
        "offers": [
          {

          }
        ]
      },
      "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": "I am looking for holiday destinations in December",
                "participantId": "2c4f8a9b-1d3e-5f70-8293-456789012def",
                "timestamp": "2024-01-15T10:30:00.000Z"
              },
              {
                "content": "I would be happy to help you find the perfect holiday destination. Do you have any specific preferences?",
                "participantId": "5b8c9d0e-2f4a-6b1c-9d8e-123456789abc",
                "timestamp": "2024-01-15T10:30:30.000Z"
              },
              {
                "content": "I enjoy warm weather and beaches, but also interested in local culture",
                "participantId": "2c4f8a9b-1d3e-5f70-8293-456789012def",
                "timestamp": "2024-01-15T10:31:00.000Z"
              }
            ],
            "metadata": {}
          }
        ]
      }
    }
  }'
{
  action: "superpower",
  actionType: "recommend",
  state: "completed",
  message: {
    results: [
      { 
        
      }
    ]
  }
}