JavaScript SDK - SiteGPT Docs

The SiteGPT JavaScript SDK allows you to embed your AI chatbot on any website with a simple script tag.

Quick start

Add your chatbot to your website in under 60 seconds:

Get your chatbot ID

Find your chatbot ID in your dashboard under Installation.

Add the script

Copy and paste this code before the closing </body> tag:

<script type="text/javascript">
window.$sitegpt=[];
(function(){
  d=document;
  s=d.createElement("script");
  s.src="https://sitegpt.ai/widget/YOUR_CHATBOT_ID.js";
  s.async=1;
  d.getElementsByTagName("head")[0].appendChild(s);
})();
</script>

Test

Reload your page and click the chat bubble to test your chatbot.

Installation

The simplest way to add your chatbot:

<script type="text/javascript">
window.$sitegpt=[];
(function(){
  d=document;
  s=d.createElement("script");
  s.src="https://sitegpt.ai/widget/YOUR_CHATBOT_ID.js";
  s.async=1;
  d.getElementsByTagName("head")[0].appendChild(s);
})();
</script>

Replace YOUR_CHATBOT_ID with your actual chatbot ID from the Installation page.

Configuration via URL parameters

You can customize the chatbot behavior by adding URL parameters to the widget script:

hideBubble=true - Hide the default chat bubble
open=true - Open the chat widget automatically
mobile=false - Hide the chat widget on mobile devices
delay=2000 - Delay widget initialization (in milliseconds)

Example:

<script type="text/javascript">
window.$sitegpt=[];
(function(){
  d=document;
  s=d.createElement("script");
  s.src="https://sitegpt.ai/widget/YOUR_CHATBOT_ID.js?hideBubble=true&open=true";
  s.async=1;
  d.getElementsByTagName("head")[0].appendChild(s);
})();
</script>

SDK methods reference

Control your chatbot programmatically using the $sitegpt JavaScript SDK. All commands use the push method: window.$sitegpt.push([command, ...args])

For a complete interactive reference with copy-paste examples, visit the SDK Methods page in your chatbot dashboard under Installation.

Programmatically opens the chat widget window.

window.$sitegpt.push(['open']);

Example: Open chat when user clicks a custom button

document.getElementById('my-custom-chat-button').addEventListener('click', function() {
  window.$sitegpt.push(['open']);
});

Programmatically closes the chat widget window.

window.$sitegpt.push(['close']);

Example: Close chat from another element

document.getElementById('close-chat-link').addEventListener('click', function() {
  window.$sitegpt.push(['close']);
});

Opens the chat widget if it’s closed, and closes it if it’s open.

window.$sitegpt.push(['toggle']);

Example: Use a single button to open or close the chat

document.getElementById('toggle-chat-button').addEventListener('click', function() {
  window.$sitegpt.push(['toggle']);
});

Open with fresh conversation

Opens the chat widget and resets the conversation in a single flicker-free step. If there is an existing conversation, it will be cleared and a new one will be started.

window.$sitegpt.push(['open', { reset: true }]);

Example: Always start a fresh conversation when user clicks your custom button

document.getElementById('chat-button').addEventListener('click', function() {
  window.$sitegpt.push(['open', { reset: true }]);
});

Use ['open', { reset: true }] instead of calling ['open'] followed by ['do', 'conversation:reset'] separately. It avoids the visual flicker of the old conversation appearing briefly before the reset.

Send messages programmatically

Send a message immediately

Sends a message to the chatbot immediately. The chat widget will open automatically if it’s closed.

window.$sitegpt.push(['do', 'message:send', 'What are your pricing plans?']);

Example: Send message when user clicks a pricing button

document.getElementById('pricing-button').addEventListener('click', function() {
  window.$sitegpt.push(['do', 'message:send', 'What are your pricing plans?']);
});

Example: Complete flow - open chat and send message

window.$sitegpt.push(['open']);
setTimeout(() => {
  window.$sitegpt.push(['do', 'message:send', 'I need help with my account']);
}, 100);

Prefill the message input

Prefills the message input field with text. Users can edit the message before sending. The input field will be focused automatically.

window.$sitegpt.push(['set', 'message:text', "Hi! I'd like to get help with..."]);

Example: Prefill input when user clicks a help button

document.getElementById('help-button').addEventListener('click', function() {
  window.$sitegpt.push(['set', 'message:text', "Hi! I'd like to get help with..."]);
});

Example: Open chat and prefill input

window.$sitegpt.push(['open']);
setTimeout(() => {
  window.$sitegpt.push(['set', 'message:text', 'I have a question about billing']);
}, 100);

Use ['do', 'message:send', ...] when you want to send a message automatically without user interaction. Use ['set', 'message:text', ...] when you want to suggest a message but let the user edit it before sending.

Manage conversations

Reset the current conversation

Resets the current conversation thread and returns to the widget home page. This clears the conversation history and allows the user to start over.

window.$sitegpt.push(['do', 'conversation:reset']);

Example: Add a “Start new conversation” button

document.getElementById('new-conversation-button').addEventListener('click', function() {
  window.$sitegpt.push(['do', 'conversation:reset']);
});

Example: Reset conversation after form submission

document.getElementById('contact-form').addEventListener('submit', function(e) {
  e.preventDefault();
  // Handle form submission
  // Then reset the chat and return to home
  window.$sitegpt.push(['do', 'conversation:reset']);
});

This command is useful when you want to give users a clean slate, such as after completing a transaction, switching topics, or when they explicitly request to start over. The user will be returned to the widget home page where they can see their conversation history.

If you want to reset and open the chat in a single flicker-free step, use window.$sitegpt.push(['open', { reset: true }]) instead. See Open with fresh conversation.

Enhance chatbot context

Give extra context

Provide additional information to your SiteGPT bot for more relevant and contextual conversations, such as the current page the user is on.

window.$sitegpt.push(['set', 'context', [
  'You are an experienced sales executive. You need to guide the user to book a demo call.',
  'Current Page: Pricing Page \n Current Page URL: https://sitegpt.ai/pricing'
]]);

Example: Provide page-specific context

window.$sitegpt.push(['set', 'context', [
  'You are helping a premium customer.',
  'Current page: ' + document.title
]]);

Manage user sessions

Automatically log the user in

Automatically log users into the chatbot without requiring email verification. This requires generating a secure signature on your backend.

window.$sitegpt.push(['set', 'user:email', [
  'user@example.com',
  'cd7cc422ea97c82d844b2373fdcd6259c9ee6e135af65ab6fe6ca85e3f07abb1'
]]);

Never generate signatures in your frontend. Always generate signatures on your backend to keep your API key secure.

Generating signatures (Node.js backend example)

const crypto = require('crypto');

// Your API key from sitegpt.ai/billing (keep it private!)
const apiKey = '6338d1ac-9afc-4a7c-8812-ba9e3f8c48eb';

// Sign an email using HMAC-SHA256
function signEmail(email) {
  return crypto.createHmac('sha256', apiKey).update(email).digest('hex');
}

// Generate signature for your user
const signature = signEmail('user@example.com');
console.log('Signature:', signature);

Security notes:

Use HMAC-SHA256 algorithm only
Generate signatures on your backend server
Never expose your API key in frontend code
Each signature is unique to the email and your API key

Security of user verification

User verification uses the HMAC-SHA256 signature algorithm, a standard and secure method for authenticating data. When setting a user email via the $sitegpt object, you must provide the signature computed on your backend. This signature uses your secret API key, known only to you and SiteGPT. Because only you and SiteGPT can generate valid signatures for a given email, an attacker without your API key cannot impersonate users.

Never generate signatures directly in your front-end code. Doing so would expose your API key in the browser, allowing anyone to impersonate your users. Always generate signatures on your backend server and never leak your API key.

Add custom CSS

Apply your own CSS to the chatbot widget and style it according to your branding.

window.$sitegpt.push(['set', 'css', ':root { --chat-color: green; }']);

Example: Changing the font family

window.$sitegpt.push(['set', 'css', 'body { font-family: "Your Custom Font", sans-serif; }']);

Common use cases

Custom chat trigger

Hide the default bubble and use your own button:

<button id="chat-button">Chat with us</button>

<script type="text/javascript">
  window.$sitegpt=[];
  (function(){
    d=document;
    s=d.createElement("script");
    s.src="https://sitegpt.ai/widget/YOUR_CHATBOT_ID.js?hideBubble=true";
    s.async=1;
    d.getElementsByTagName("head")[0].appendChild(s);
  })();
  
  document.getElementById('chat-button').addEventListener('click', function() {
    window.$sitegpt.push(['open']);
  });
</script>

Context-aware chatbot

Provide page-specific context:

<script type="text/javascript">
  window.$sitegpt=[];
  (function(){
    d=document;
    s=d.createElement("script");
    s.src="https://sitegpt.ai/widget/YOUR_CHATBOT_ID.js";
    s.async=1;
    d.getElementsByTagName("head")[0].appendChild(s);
  })();
  
  // Set context after page loads
  window.addEventListener('load', function() {
    window.$sitegpt.push(['set', 'context', [
      'You are helping with ' + document.title,
      'Current URL: ' + window.location.href
    ]]);
  });
</script>

Pre-filled messages

Suggest messages based on user actions:

<button id="pricing-question">Ask about pricing</button>

<script>
  document.getElementById('pricing-question').addEventListener('click', function() {
    window.$sitegpt.push(['open']);
    setTimeout(function() {
      window.$sitegpt.push(['set', 'message:text', 'What are your pricing plans?']);
    }, 100);
  });
</script>

Authenticated users

Auto-login authenticated users by fetching signature from your backend:

<script type="text/javascript">
  window.$sitegpt=[];
  (function(){
    d=document;
    s=d.createElement("script");
    s.src="https://sitegpt.ai/widget/YOUR_CHATBOT_ID.js";
    s.async=1;
    d.getElementsByTagName("head")[0].appendChild(s);
  })();
  
  // Fetch user email and signature from your backend API
  fetch('/api/chatbot-auth')
    .then(res => res.json())
    .then(data => {
      window.$sitegpt.push(['set', 'user:email', [
        data.email,
        data.signature
      ]]);
    });
</script>

Backend API example (Node.js):

// /api/chatbot-auth endpoint
const crypto = require('crypto');

app.get('/api/chatbot-auth', (req, res) => {
  // Get the logged-in user's email from your session/auth system
  const userEmail = req.user.email;
  
  // Your SiteGPT API key (keep it secret!)
  const apiKey = process.env.SITEGPT_API_KEY;
  
  // Generate signature
  const signature = crypto
    .createHmac('sha256', apiKey)
    .update(userEmail)
    .digest('hex');
  
  res.json({
    email: userEmail,
    signature: signature
  });
});

Styling

Custom CSS

Apply custom styles to the chat widget:

window.$sitegpt.push(['set', 'css', `
  :root {
    --chat-color: #155DEE;
    --chat-text-color: #FFFFFF;
    --chat-font-size: 16px;
  }
`]);

Available CSS variables

The widget supports these CSS variables:

--chat-color - Primary brand color (used for bubble, buttons, etc.)
--chat-text-color - Text color for elements using the brand color
--chat-font-size - Base font size for the chat interface

The widget uses Tailwind CSS internally. You can target specific elements with custom CSS, but the available CSS variables are limited to those listed above.

Best practices

Load asynchronously

The recommended installation method already loads the SDK asynchronously to avoid blocking page rendering:

<script type="text/javascript">
window.$sitegpt=[];
(function(){
  d=document;
  s=d.createElement("script");
  s.src="https://sitegpt.ai/widget/YOUR_CHATBOT_ID.js";
  s.async=1;
  d.getElementsByTagName("head")[0].appendChild(s);
})();
</script>

Handle loading state

Check if the SDK is loaded before calling methods:

function callSiteGPT(command) {
  if (window.$sitegpt && window.$sitegpt.push) {
    window.$sitegpt.push(command);
  } else {
    // SDK not loaded yet, queue the command
    window.$sitegpt = window.$sitegpt || [];
    window.$sitegpt.push(command);
  }
}

Provide context

Give your chatbot context about the current page:

window.$sitegpt.push(['set', 'context', [
  '',
  `Page: ${document.title}\nURL: ${window.location.href}`
]]);

Test thoroughly

Test your integration across:

Different browsers (Chrome, Firefox, Safari, Edge)
Mobile devices (iOS, Android)
Different screen sizes
With ad blockers enabled

Troubleshooting

Chatbot not appearing

If your chatbot doesn’t appear, try these solutions:

Check the script tag
Ensure the script is added before </body> and the chatbot ID is correct.Check browser console
Look for JavaScript errors that might prevent loading.Verify chatbot is published
Ensure your chatbot is published in the dashboard.Test in incognito mode
Rule out browser extensions or cached files.

Methods not working

If SDK methods aren’t working, verify these items:

Wait for SDK to load
Ensure the SDK is fully loaded before calling methods.Check syntax
Verify you’re using the correct method syntax.Review console errors
Check for JavaScript errors in the browser console.

Styling issues

If custom styles aren’t applying, try these fixes:

Check CSS specificity
Your styles may need !important to override defaults.Verify CSS syntax
Ensure your CSS is valid.Clear cache
Clear browser cache and reload the page.

Next steps

Installation guide

Detailed installation instructions

Tracking events

Track chatbot activity in GTM, GA4, or custom analytics

Webhooks

Set up webhooks for real-time events

Appearance

Customize chatbot appearance

API reference

Explore the REST API

​Quick start

​Installation

​Configuration via URL parameters

​SDK methods reference

​Control widget visibility

​Open the chat widget

​Close the chat widget

​Toggle the chat widget

​Open with fresh conversation

​Send messages programmatically

​Send a message immediately

​Prefill the message input

​Manage conversations

​Reset the current conversation

​Enhance chatbot context

​Give extra context

​Manage user sessions

​Automatically log the user in

​Generating signatures (Node.js backend example)

​Security of user verification

​Customize widget appearance

​Add custom CSS

​Common use cases

​Custom chat trigger

​Context-aware chatbot

​Pre-filled messages

​Authenticated users

​Styling

​Custom CSS

​Available CSS variables

​Best practices

​Load asynchronously

​Handle loading state

​Provide context

​Test thoroughly

​Troubleshooting

​Next steps

Installation guide

Tracking events

Webhooks

Appearance

API reference

Quick start

Installation

Configuration via URL parameters

SDK methods reference

Control widget visibility

Open the chat widget

Close the chat widget

Toggle the chat widget

Open with fresh conversation

Send messages programmatically

Send a message immediately

Prefill the message input

Manage conversations

Reset the current conversation

Enhance chatbot context

Give extra context

Manage user sessions

Automatically log the user in

Generating signatures (Node.js backend example)

Security of user verification

Customize widget appearance

Add custom CSS

Common use cases

Custom chat trigger

Context-aware chatbot

Pre-filled messages

Authenticated users

Styling

Custom CSS

Available CSS variables

Best practices

Load asynchronously

Handle loading state

Provide context

Test thoroughly

Troubleshooting

Next steps