User Guide

Get the Embed Code

Go to your agent's detail page. In the Embed Widget section on the right, you'll find a script tag ready to copy:

<script src="https://chatnexus.cloud/js/embed.js?id=YOUR_AGENT_UUID"></script>

Hover over the code block and click Copy to copy it to your clipboard.

ℹ️

By embedding this widget, you confirm that your website's privacy policy discloses ChatNexus and the underlying language model provider as data processors, and that you have obtained end-user consent for data collection.

Add to Your Website

Paste the embed script into your website's HTML - typically just before the closing </body> tag. The script automatically injects a floating chat widget into the page.

<html>
<body>
    <!-- Your website content -->

    <script src="https://chatnexus.cloud/js/embed.js?id=YOUR_AGENT_UUID"></script>
</body>
</html>

💡

Tip: The embed script handles all the positioning and styling automatically. No iframe or CSS setup is needed - just paste the single script tag and you're done.

Whitelist Your Domain (Paid Plans)

On paid plans, you can restrict the widget to whitelisted domains. On the agent detail page, use Allowed Domains and add each domain where you'll embed the widget (one per line):

mywebsite.com

app.mywebsite.com

⚠️

Important: If domain restrictions are configured, requests from unlisted domains are rejected. On Free plan, this restriction setting is unavailable and the widget can run on any domain.

Enable Voice Mode (Optional)

If Voice Input is enabled for your agent, the widget shows a microphone button. In some cross-origin embeds, browser microphone permissions can be blocked inside iframes.

Voice settings panel with voice input enabled

ℹ️

How ChatNexus handles this: the widget can open a first-party voice popup (/widget/{agentUuid}/voice) and relay transcription securely back to the widget, so voice input still works without host-site header changes.

API Endpoint (Advanced)

In addition to the embed widget, your agent exposes a REST API - a direct way to talk to your agent programmatically, without any pre-built chat interface.

Widget vs. API - which should you use?

Embed Widget (script tag)

✔ Ready-made floating chat button
✔ No coding required - paste & done
✔ ChatNexus handles the UI for you
✘ Fixed look and feel

REST API

✔ Full control over your own custom UI
✔ Works in mobile apps, backends, dashboards
✔ Automate workflows without a human present
✘ Requires developer knowledge

Use the API when you want to build your own chat interface inside your product, send automated messages from your backend, or integrate the agent into a mobile app - anywhere the embed script can't go.

Your endpoint details

You'll find these values in the API Endpoint section on your agent's detail page:

Agent UUID

your-agent-uuid

Chat Endpoint

POST https://chatnexus.cloud/api/agents/YOUR_AGENT_UUID/chat

API Endpoint section on the agent detail page

Example: sending a message via JavaScript

Here's how to call your agent from any webpage or JavaScript application:

fetch('https://chatnexus.cloud/api/agents/YOUR_AGENT_UUID/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Hello, what can you help me with?' })
})
  .then(res => res.json())
  .then(data => console.log(data.reply));

The API responds with a JSON object containing your agent's reply, which you can display however you like in your own interface.

ℹ️

Not a developer? Skip this step - the embed widget from Steps 1–2 is all you need to get a fully functional chat bot on your website. The API is only needed if you want a fully custom-built experience.

Branding Control

Depending on your plan:

Free The widget displays a "Powered by ChatNexus" badge.

Paid Custom domain whitelisting is enabled and the ChatNexus branding badge can be hidden - giving you a fully white-label experience.

Preview the Widget

After embedding, visit your website to see the chat widget in action. It should appear as a floating chat button that expands into a chat panel when clicked.

Integrating Your Agent