Skip to main content

AI12Z WebSocket API Documentation

Overview​

The AI12Z WebSocket API enables real-time communication between the client and the AI12Z server. This allows for dynamic interactions, such as submitting queries and receiving responses asynchronously. This documentation will guide you through setting up and using the WebSocket API with an example client implementation.

Connecting to the WebSocket API​

To connect to the AI12Z WebSocket API, you will need the following:

  • apiKey: Your API key.
  • endpoint: The WebSocket endpoint URL.

URL Format​

The WebSocket URL is constructed based on the environment you are working in. For example:

  • Production: wss://api.ai12z.net

Establishing a Connection​

To establish a WebSocket connection, you need to use the io.connect method from the socket.io library:

const socket = io.connect(endpoint)

Sending a Query​

To send a query to the AI12Z server, you need to emit the evaluate_query event with the required data:

const data = {
  apiKey: apiKey,
  query: query,
  conversationId: conversationId, // optional, for follow-up queries
  event: "evaluate_query",
}

socket.emit("evaluate_query", data)

Sending a Query and Images​

To send a query to the AI12Z server, you need to emit the evaluate_query when sending images, you can send more than one: There is a max payload size of 16 Meg when doing the emit, on client size you could resize the image width, for example 1024px and compress before converting to base64Image. If your payload is excedding 16 Meg

const data = {
  apiKey: apiKey,
  query: query,
  conversationId: conversationId, // optional, for follow-up queries
  event: "evaluate_query",
  base64Images: [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAS....",
    "data:image/png;base64...",
  ],
  includeTags: [], // Optional
  excludeTags: [], // Optional
  requestMetadata: {}, // Optional
}

socket.emit("evaluate_query", data)

Receiving Responses​

The server sends responses back through the response event. You can handle these responses by listening for the response event:

socket.on("response", function (event) {
  handleMessage(event.data, aiMessageId) // Process the received message
})

socket.on("end_response", function (data) {
  //The end response includes the total markdown for the bubble
  // it will update the links and images and youtube vidoe for the bubble content
  conversationId = data.conversationId
  //  data.answer  - answer, that contains the hyperlinks, images and videos
  //  data.formModel - if form this is the form model data to use on client side
  //  data.controlData - if agent is returning data that skips the LLM
  //  data.controlType - type, form, carousel, custom, this list will grow, it is what is set in custom agent
  //  data.title - if AnswerAI, most relevent title, from vector db
  //  data.link - if AnswerAI, most relevent link, from vector db
  //  data.description  - if AnswerAI, most relevent description, from vector db
  //  data.relevanceScore - if AnswerAI, the relevancy score, from vector db
  //  data.assetType - web, pdf, docx,
  //  data.didAnswer - true / false
  //  data.context - if AnswerAI, vector db data
  //  data.insightId - used if liking or not liking content
  //  data.error -  should be null
  //  data.conversationId - comes from ai12z platform with the answer to a question, use this id, if you want to continue the conversation or set it to empty string

  handleEndResponse(data.answer, data.formModel) // If the LLM is sending back a a form model
})

Handling Partial Responses​

The response event sends partial responses (tokens) in Markdown format. You should accumulate these tokens in a hidden field and convert the accumulated Markdown to HTML for display. The end_response event sends the complete response, which can include updates to links and images.

Example Client Code​

Below is a simple example client implementation that connects to the AI12Z WebSocket API, sends a query, and handles the response:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>AI12Z WebSocket Client</title>
    <script src="https://cdn.socket.io/4.0.1/socket.io.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/showdown/dist/showdown.min.js"></script>
  </head>
  <body>
    <input type="text" id="queryInput" placeholder="Type your question here" />
    <button onclick="askAI()">Ask AI</button>
    <div id="responseContainer"></div>

    <script>
      const apiKey = "your-api-key"
      let conversationId = ""
      const endpoint = "wss://api.ai12z.net"
      let socket
      let markdownBuffer = ""

      function connectWebSocket() {
        socket = io.connect(endpoint)

        socket.on("response", function (event) {
          handleResponse(event.data)
        })

        socket.on("end_response", function (data) {
          conversationId = data.conversationId || conversationId
          handleEndResponse(data.answer, data.formModel)
        })
      }

      function askAI() {
        const query = document.getElementById("queryInput").value
        const data = {
          apiKey: apiKey,
          query: query,
          conversationId: conversationId,
          event: "evaluate_query",
          base64Images: [],
        }

        socket.emit("evaluate_query", data)
      }

      function handleResponse(data) {
        markdownBuffer += data // Accumulate markdown data
        updateResponseContainer()
      }

      function handleEndResponse(answer, formModel) {
        markdownBuffer = answer // Update markdown buffer with the complete response
        updateResponseContainer()
        if (formModel) {
          console.log("Form Model:", formModel)
          // the form model is used with the ai12z form client code, when present your replacing a formPlaceholder with a real form
        }
      }

      function updateResponseContainer() {
        const converter = new showdown.Converter()
        const html = converter.makeHtml(markdownBuffer)
        const responseContainer = document.getElementById("responseContainer")
        responseContainer.innerHTML = html
      }

      // Connect to WebSocket on page load
      window.onload = connectWebSocket
    </script>
  </body>
</html>

Explanation​

  1. HTML Elements: The HTML file contains an input field for the user to type their query and a button to send the query to the AI. The response from the AI is displayed in the responseContainer div.

  2. JavaScript:

    • connectWebSocket: Establishes the WebSocket connection and sets up event listeners for response and end_response.
    • askAI: Sends the user's query to the AI12Z server.
    • handleResponse: Handles partial responses by accumulating them in a markdownBuffer and updating the response container.
    • handleEndResponse: Handles the complete response by updating the markdownBuffer and the response container. Also, it logs the formModel to the console, which can be further processed if needed.
    • updateResponseContainer: Converts the accumulated Markdown in markdownBuffer to HTML and updates the response container.

This example demonstrates the basics of connecting to the AI12Z WebSocket API, sending a query, handling partial and complete responses, and converting Markdown to HTML for display. Modify the parameters and endpoint as needed to match your specific use case and environment.