xChatBot Integration

Overview

This document details the integration between the xFlow system and the xChatbot system via REST API. The integration includes communication protocols, data structures, and the sequence of interactions. All communication follows the CloudEvent specification and is conducted in JSON format.

Communication Protocol

• Protocol: REST API

• Data Format: JSON, following CloudEvent specification

• Request Initiator: xChatbot system

• Response Receiver: xChatbot system (via webhook)

API Endpoints

• Request Endpoint: https://xfai/api/aiQuery/query

• Response Webhook Endpoint: https://xchatbot/api/aiagent/reply

Integration Flow Details

Detailed Integration Flow

xChatbot and xFlow Integration Flow

1. Initialization and Request Construction:

   • The xChatbot system prepares a request to the xFlow system whenever a user poses a question or provides a reply.

   • This request is structured according to the CloudEvent specification and includes key attributes, extensions, and data. The main content of the request is a JSON object containing the user's message. (See detail in CloudEvent Request Structure)
2. Sending the Request:

   • The constructed CloudEvent request is sent from the xChatbot system to the xFlow system using the endpoint https://xfai/api/aiQuery/query.

   • The xFlow system acknowledges receipt of the request and begins processing.

3. Processing the Request:

   • The xFlow system identifies the appropriate agent workflow using the agentcode provided in the request.

   • The xFlow system processes the request based on the logic defined in the serverless workflow associated with the agentcode.

4. Handling Different Response Scenarios:

   • Final Answer or Informative Response:

     • If the AI agent determines that it can provide a final answer or needs to inform the user, xFlow prepares a response event. (See details in CloudEvent Response Structure)
     • This response does not include subconversationid and subconversationtype.

     • The response is sent back to xChatbot via the webhook endpoint https://xchatbot/api/aiagent/reply.

   • Request for More Information:

     • If the AI agent requires additional information from the user, it initiates a new sub-conversation.

     • The response event includes newly created subconversationid and subconversationtype. (See details in CloudEvent Response Structure)
     • The response is sent back to xChatbot via the webhook endpoint https://xchatbot/api/aiagent/reply, and the AI agent waits for the user's reply.

5. Subconversation Handling:

   • When a new subconversation is initiated, xChatbot handles the user interaction until the required information is gathered.

   • The new messages are sent to xFlow using the same request format but include the subconversationid and subconversationtype to maintain the context.

Data Structures and Properties

CloudEvent Request Structure

Attributes

Property	Type	Description
id	string	Unique identifier for the event
source	string	Event source URL
specversion	string	CloudEvent specification version
type	string	Event type (com.a4b.xfai.ai.query.model.AskQuestionQuery)

Extensions

Property	Type	Description
agentcode	string	The agent code that xChatbot intends to use corresponds to the ID of a serverless workflow definition in the xFlow system.
conversationid	string	The unique identifier for the conversation between the chatbot and the user
subconversationid	string	(Optional) The unique identifier of the sub-conversation created by the AI agent to gather more information from the user.
subconversationtype	string	(Optional) The type of sub-conversation, used by the AI agent to classify the conversation.
{extension_key}	various	Other information that xChatbot wants to return in the response event will be added as extensions in the request CloudEvent. xFlow will include all of them in the response event with the convention: Added as extensions in the response event. The extension name will be the original extension key prefixed by "req": req{extension_key}

Data

Property	Type	Description
message	string	String data representing the user's question or reply message.

CloudEvent Response Structure

Attributes

Property	Type	Description
id	string	Unique identifier for the event
source	string	Event source URL
specversion	string	CloudEvent specification version
type	string	Event type (com.a4b.xfai.ai.query.model.JsonNodeAiQueryResponse)

Extensions

Property	Type	Description
conversationid	string	The unique identifier for the conversation between the chatbot and the user.
subconversationid	string	(Optional) The unique identifier of the sub-conversation created by the AI agent to gather more information from the user.
subconversationtype	string	(Optional) The type of sub-conversation, used by the AI agent to classify the conversation.
req{original_extension_key}	various	Other information that xChatbot wants to return in the response event will be added as extensions in the request CloudEvent. xFlow will include all of them in the response event with the convention: Added as extensions in the response event. The extension name will be the original extension key prefixed by "req": req{original_extension_key}

Data

Property	Type	Description
message	string	String data representing the response message from the AI agent to the user.
images	array	(Optional): A list of media contents included with the text message. Each media content structure defined in Image Object Structure

Image Object Structure

Property	Type	Description
uuid	string	The unique identifier of media content.
url	string	The URL where xChatbot can access the media content.
base64Data	string	The media content in base64 format.
mimeType	string	The MIME type of the content.
description	string	The description of media content.

Example Requests and Responses

Example CloudEvent Request

Request:

{
  "id": "12345",
  "source": "https://cloudevents.a4b.com/ms-chatbot",
  "specversion": "1.0",
  "type": "com.a4b.xfai.ai.query.model.AskQuestionQuery",
  "agentcode": "agent123",
  "conversationid": "conv001",
  "subconversationid": "subconv001",
  "subconversationtype": "USER_PROXY_AGENT",
  "data": {
    "message": "What is the weather like today?"
  }
}

Example CloudEvent Response (Final Answer)

Response:

{
  "id": "54321",
  "source": "https://cloudevents.a4b.com/xplatform/xfai",
  "specversion": "1.0",
  "type": "com.a4b.xfai.ai.query.model.JsonNodeAiQueryResponse",
  "conversationid": "conv001",
  "data": {
    "message": "The weather is sunny today.",
    "images": [
      {
        "uuid": "5e388fd7-871f-4500-8c3b-b0363eb907c1",
        "url": "https://example.com/weather_image.jpg",
        "base64Data": null,
        "mimeType": "image/jpeg",
        "description": null
      }
    ]
  }
}

Example CloudEvent Response (Request for More Information)

Response:

{
  "id": "54321",
  "source": "https://cloudevents.a4b.com/xplatform/xfai",
  "specversion": "1.0",
  "type": "com.a4b.xfai.ai.query.model.JsonNodeAiQueryResponse",
  "conversationid": "conv001",
  "subconversationid": "subconv002",
  "subconversationtype": "USER_PROXY_AGENT",
  "data": {
    "message": "Could you please specify the city for the weather information?"
  }
}

xChatBot configuration

For each chatbot, xChatbot allows users to define the AI Agent to answer user questions. This AI Agent is configured with the integration details with xFlow, including the xpApiKey and agentCode to map to a serverless workflow that implements the detailed logic of the AI Agent. Below is a screenshot of the configuration screen in the xChatbot application:

AI Agent Configuration Screen

By following this detailed documentation, developers can ensure a smooth integration between the xFlow system and the xChatbot system, enabling efficient orchestration and execution of AI-driven tasks while maintaining structured and standardized communication.