API Documentation

Sesame Group Virtual Assistant API Documentation

The integration of artificial intelligence Virtual Assistants represents a significant advancement in automated service delivery. This comprehensive guide outlines both the technical framework and practical implementation details required for establishing effective communication with Sesame Group's AI Virtual Assistants through our application programming interfaces (APIs).

Fundamentals of Virtual Assistant API Communication

The Virtual Assistant application programming interface establishes a structured communication protocol that facilitates seamless interaction between client applications and our AI conversational systems. These interfaces handle bidirectional data exchange, allowing developers to programmatically submit queries to the AI system and receive processed responses in a standardized format. Our API implementation significantly reduces development overhead by abstracting the complexities of the underlying machine learning models, enabling developers to focus primarily on integration logic and user experience considerations.

Message Exchange Protocol

The foundation of our Virtual Assistant API functionality lies in its message exchange protocol, which governs how information is transmitted between your client and our AI system. When implementing API calls, developers must structure requests according to specified parameters, including authentication credentials, message content, and contextual metadata. The system processes these inputs through multiple computational layers before generating appropriate responses. This bidirectional communication pathway maintains consistent performance regardless of message complexity, ensuring that user experience remains seamless across diverse use cases.

How to Use the Virtual Assistant API

The Virtual Assistant API allows you to send queries and receive AI-generated responses. To maintain chat history, you must generate a unique chat_id at the beginning of a conversation and reuse it for all subsequent messages.

API Endpoint

A unique URL is generated for you to access the API endpoint.

POST /api/query - Sends a query to the Virtual Assistant and receives a response.

POST /api/history - Retrieves the chat history based on chat_id.

Authentication

Include the API token generated for you as a Bearer token in the Authorization header. The secure implementation of Virtual Assistant API integration necessitates robust authentication mechanisms that protect the service and user data. Your API credentials must be securely stored within application environments and properly transmitted with each API request.

Conversation State Management

Effective conversation management represents one of the most critical aspects of Virtual Assistant API implementation. Our system requires persistence mechanisms that track conversation history to maintain conversational context and enable meaningful multi-turn dialogues. This functionality is primarily implemented through generating and utilizing a unique conversation identifier, referred to as a chat_id.

The chat_id parameter must be created at initiating a new conversation thread and subsequently included in all related API calls. This identifier allows our AI system to associate incoming messages with their appropriate conversation context, enabling more coherent and contextually relevant responses. Without proper implementation of conversation state management, Virtual Assistant responses may lack contextual awareness, significantly diminishing the quality of user interaction.

Request Format for /api/query

                  {
                      "chat_id": "your-unique-chat-id",
                      "query": "What is Sesame Group?",
                      "include_metadata": false
                  }

Note: The include_metadata parameter is optional and should only be used for debugging purposes. When set to true, it returns additional metadata along with the response.

Request Format for /api/history

                  {
                      "chat_id": "your-unique-chat-id"
                  }

Implementation Examples

When implementing a connection to our API, it's essential to properly generate and maintain the chat_id throughout the conversation lifecycle. The following examples demonstrate how to implement this pattern in various programming languages.

Example in Python

      import requests
      import uuid
      
      url_query = "https://your-api-url.com/api/query"
      url_history = "https://your-api-url.com/api/history"
      headers = {
          "Authorization": "Bearer YOUR_API_TOKEN",
          "Content-Type": "application/json"
      }
      
      # Generate and store chat_id for the entire session
      chat_id = str(uuid.uuid4())

Then use the generated chat_id in all future requests associated to the current conversation with the bot:

        def send_query(query, include_metadata=False):
          data = {
              "chat_id": chat_id,  # Reuse the same chat_id
              "query": query,
              "include_metadata": include_metadata
          }
          response = requests.post(url_query, json=data, headers=headers)
          return response.json()
      
      def get_chat_history():
          data = {"chat_id": chat_id}
          response = requests.post(url_history, json=data, headers=headers)
          return response.json()
      
      # Example usage
      print(send_query("What is Sesame Group?"))
      print(send_query("Tell me more about the pricing", include_metadata=True))
      print(get_chat_history())

Example in JavaScript

First, generate a chat_id and store it for the session:

      
const url = "https://your-api-url.com/api/query";
const headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
};

// Generate a chat_id once and reuse it
const chatId = localStorage.getItem("chat_id") || (() => {
    const newId = crypto.randomUUID();
    localStorage.setItem("chat_id", newId);
    return newId;
})();

Then use the generated chat_id in all future requests associated to the current conversation with the bot:

function sendQuery(query) {
    const data = {
        chat_id: chatId, // Reuse the same chat_id
        query: query
    };
    fetch(url, {
        method: "POST",
        headers: headers,
        body: JSON.stringify(data)
    })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error("Error:", error));
}

// Example usage
sendQuery("What is Sesame Group?");
sendQuery("Tell me more about the pricing");

Technical Considerations & Best Practices

The technical implementation of Virtual Assistant API integration requires careful attention to several critical components directly impacting performance, security, and scalability. These considerations should inform your development approach from planning through deployment.

Request Structure and Optimization

The structure of API requests significantly impacts system performance and response quality. Properly formatted requests should include all necessary parameters while avoiding extraneous information that could increase computational overhead. When formulating query content, consider potential character limitations and optimize message length to balance information completeness with processing efficiency. Implementing intelligent request batching and throttling mechanisms helps manage API rate limits while maximizing throughput for applications with high transaction volumes.

Effective Conversation Management Strategies

For optimal conversation management, applications should generate cryptographically secure unique identifiers to serve as the chat_id parameter. These identifiers should be persistently stored throughout the conversation lifecycle, either in server-side session management systems or secure client-side storage mechanisms as demonstrated in our code examples. Conversation contexts should be periodically persisted to prevent data loss during unexpected service interruptions. Consider implementing conversation timeouts and explicit termination endpoints to enable proper resource management, preventing the accumulation of stale conversation states that could impact system performance.

Response Processing Considerations

The processing and presentation of Virtual Assistant API responses require careful consideration to ensure optimal user experience. Response data often requires post-processing to extract relevant information, format content appropriately, and handle special cases such as error conditions or incomplete responses. Implementing progressive rendering techniques can improve perceived performance by displaying partial responses while awaiting complete data. Consider implementing appropriate content filtering and validation to ensure that displayed responses meet quality standards and adhere to your platform policies.

Response Example

      {
          "response": "Sesame Group is a company..."
      }

When include_metadata is enabled:

      {
          "response": "Sesame Group is a company...",
          "metadata": {"source": "https://sesamegroup.sg/about"}
      }

History response:

      {
          "response": [
              {"user": "What is Sesame Group?", "assistant": "Sesame Group is a company..."},
              {"user": "Tell me more about the pricing", "assistant": "Our plans start at..."}
          ]
      }

Conclusion

The integration of our AI Virtual Assistant functionality through API interfaces represents a powerful capability for modern applications. It enables sophisticated conversational experiences without requiring extensive machine learning expertise. Properly implementing these interfaces, with particular attention to conversation state management through the chat_id mechanism, ensures coherent multi-turn dialogues that enhance user engagement.

Technical teams should approach Virtual Assistant API integration with careful consideration of security requirements, performance optimization, and user experience design to maximize the value of these powerful conversational interfaces. The documentation and examples provided in this guide should serve as a comprehensive foundation for successfully implementing Sesame Group's AI Virtual Assistant services into your applications.