Expertise AI Knowledge Base

   Miscellaneous  Triggering with our API

Triggering with our API

Last updated on October 1, 2025

ChatSimple API Documentation

The Chatsimple AI Nav & Widget expose a JavaScript API that allows you to programmatically interact with the them from your website's code. This API is available globally as window.expertiseAi once the AI Nav has loaded or window.chatsimpleWidget once the widget has loaded.
 
 

Quick Glimpse of why Trigger with our API

 
 
 

For the AI Nav

Checking API Availability

Before using the API, ensure the widget has loaded and the API is available:
Embed to ensure available.
if (window.expertiseAi && window.expertiseAi._isInitialized) {
  // API is ready to use
  window.expertiseAi.open();
  console.log('API LIVE!')
} else {
  console.warn('ChatSimple Widget API not yet available');
}
 

open()

To programmatically open the AI Nav. Recommended before asking a question.
window.expertiseAi.open();

Parameters: None

Returns: `void`
 

onOpen()

Allow triggering custom logic when a user opens up the AI Nav, likely by asking a question.
window.expertiseAi.onOpen = () => {
  // Your custom logic here
  console.log('Its open')
}
 

query()

To programmatically ask question in the AI Nav.
window.expertiseAi.open();
window.expertiseAi.onOpen = () => {
  window.expertiseAi.query("I need help with pricing", true, "typed");
}

window.expertiseAi.query(query, addUserMessage, querySourceType?)

Parameters:
- `query` (string, required): The query text to send to the chatbot
- `addUserMessage` (boolean, required): Whether to add the query as a user message in the chat
- `querySourceType` (string, optional): The source type of the query. Options: `"engagement"`, `"engagement_answer"`, `"suggested"`, `"typed"`, `"follow_up"`, `"other"`

Returns: `Promise`
 

startVoice()

To programmatically trigger voice in our AI Nav.
window.expertiseAi.startVoice()

Parameters: None

Returns: `void`
 

restart()

To clear the previous conversation history and restart the AI Nav in closed mode.
window.expertiseAi.restart()

Parameters: None

Returns: `void`
 

For the Widget or iFrame

Checking API Availability

Before using the API, ensure the widget has loaded and the API is available:
Embed to ensure available.
if (window.chatsimpleWidget && window.chatsimpleWidget._isInitialized) {
  // API is ready to use
  window.chatsimpleWidget.open();
  console.log('API LIVE!')
} else {
  console.warn('ChatSimple Widget API not yet available');
}
 

open()


window.chatsimpleWidget.open()

Parameters: None

Returns: `void`

Example:
// Open the widget when user clicks a custom button
document.getElementById('chat-help').addEventListener('click', () => {
  window.chatsimpleWidget.open();
});
 

sendMessage()

Programmatically send a message to the chat widget and open the widget if it's closed.
window.chatsimpleWidget.sendMessage(message)

Parameters:
- `message` (string, required): The message text to send to the chatbot

Returns: `void`

Example:
// Simple message
window.chatsimpleWidget.sendMessage("I need help with pricing");
 

restart()


window.chatsimpleWidget.restart()

Parameters: None

Returns: `void`

// Reset chat for a new user session
function startFreshChat() {
  window.chatsimpleWidget.restart();
  window.chatsimpleWidget.sendMessage("I'm a new visitor, can you help me?");
}
 

identify()

Syntax:
window.chatsimpleWidget.identify(metadata)

Parameters:
- `metadata` (object, required): An object containing user information

Common metadata fields:
- `name` (string): Full name
- `first_name` (string): First name  
- `last_name` (string): Last name
- `email` (string): Email address
- `phone` (string): Phone number
- `company` (string): Company name
- Custom fields as configured in your ChatSimple dashboard

Returns: `void`

Example:
// Basic user identification
window.chatsimpleWidget.identify({
  name: "John Doe",
  email: "john@example.com",
  phone: "+1-555-0123"
});

// With custom fields
window.chatsimpleWidget.identify({
  first_name: "John",
  last_name: "Doe", 
  email: "john@example.com",
  company: "Acme Corp",
  role: "CTO",
  source: "website-signup"
});