Website Widget Integration

Embed your AI chatbot on any website with one snippet

Quick Start

The dashboard generates a ready-to-paste snippet that already contains your widget API key and the correct server URL. You never need to edit it by hand.

Get your embed code

1Open Dashboard → Chatbots and select your chatbot
2Make sure the status badge in the header says Active (the widget refuses to load for inactive chatbots)
3Go to the Embed Code tab, copy the snippet and paste it just before </body> on every page where the chat should appear

The embed snippet

Embed Code (example)

<!-- AgentPro Chat Widget -->
<script>
  window.chatbotProConfig = {
    apiKey: "cbp_YOUR_WIDGET_API_KEY",
    apiUrl: "https://api.your-agentpro-host.com",
    position: "bottom-right",
    primaryColor: "#6366f1"
  };
</script>
<script src="https://api.your-agentpro-host.com/widget.js" async></script>

How it works

The snippet sets window.chatbotProConfig and loads widget.js from your AgentPro API server. The widget authenticates every request with the apiKey (it starts with cbp_). If you regenerate the key in the dashboard, update the snippet on your site.

Configuration

Only a handful of options live in the snippet. Everything else (welcome message, pre-chat form, widget size, business hours, themes, allowed domains) is managed in the dashboard and fetched by the widget at load time.

window.chatbotProConfig

window.chatbotProConfig = {
  apiKey: "cbp_YOUR_WIDGET_API_KEY", // required
  apiUrl: "https://api.your-agentpro-host.com", // optional: defaults to the origin widget.js was loaded from
  position: "bottom-right", // bottom-right | bottom-left | top-right | top-left
  primaryColor: "#6366f1",  // 6-digit hex; overrides the chatbot colour
  language: "en"            // optional: sets the lang attribute on the widget
};

Options

Option	Type	Default	Description
apiKey	string	required	The chatbot's widget API key (cbp_...). Shown in the Embed Code tab.
apiUrl	string	origin of widget.js	Base URL of the AgentPro API. Only needed when widget.js is served from a different host.
position	string	chatbot setting	bottom-right, bottom-left, top-right or top-left.
primaryColor	string	chatbot setting	6-digit hex colour for the launcher, header and buttons. An active widget theme can override the rest of the palette.
language	string	chatbot setting	BCP-47 language tag applied to the widget markup for screen readers.

JavaScript API

After the script loads it exposes window.AgentProWidget so you can wire the chat to your own buttons and identify logged-in users.

window.AgentProWidget

// Available once widget.js has loaded (listen for the "agentpro:ready" event)
document.addEventListener('agentpro:ready', function () {
  // Open, close or toggle the chat window
  AgentProWidget.open();
  AgentProWidget.close();
  AgentProWidget.toggle();

  // Send a message on the visitor's behalf (opens the window first)
  AgentProWidget.sendMessage('I would like to know more about pricing');

  // Identify the visitor (skips the pre-chat form, shown in the inbox)
  AgentProWidget.setVisitor({
    name: 'Jane Doe',
    email: 'jane@example.com',
    phone: '+1 555 0100'
  });
});

// window.ChatBotProWidget is an alias of window.AgentProWidget

Allowed domains

Because the API key is visible in your page source, restrict where it can be used. In the chatbot's Settings → Widget Appearance → Allowed domains enter a comma-separated list such asexample.com, app.example.com.

Leave the list empty to allow every website (useful while testing).
An entry matches itself and all of its subdomains: example.com also allows www.example.com. Protocols, ports, paths and *. prefixes are ignored.
Requests from any other origin receive HTTP 403 and the launcher button is hidden on that site.
Add localhost if you need to test on a local dev server.

What you get

Appearance

Widget themes: colours, fonts, radius, logo, company name, custom CSS
Small, medium or large window; full-screen on phones
Rendered in a Shadow DOM so your site's CSS never clashes
Optional "Powered by AgentPro" footer

Behaviour

Conversations persist across page loads for the same visitor
Human handoff: agent replies from the Inbox appear in the widget
Pre-chat form for name, email and phone (configurable)
Business hours with an offline greeting, knowledge-base source links, keyboard accessible

Troubleshooting

Launcher button not appearing?

• The chatbot must be Active. Inactive chatbots return 403 and the widget hides itself.
• Check the domain allow-list: the page's hostname must match an entry (or the list must be empty).
• Open the browser console: the widget logs a single [AgentPro] warning with the reason.
• Verify apiUrl points at your API server and that /widget.js loads (HTTP 200).
• The snippet must be present only once per page; a second copy is ignored.

Chat opens but replies fail?

• "Too quickly" errors mean the per-chatbot rate limit (Settings → messages per minute) or the per-visitor limit was hit; the widget shows a Retry button.
• Make sure an AI model is configured and the organization has remaining usage.
• If an agent replied from the Inbox, AI answers pause for that conversation until the agent re-enables them.