Chat
Chat — Integration Guidelink
The New Instance Chat product is an embeddable live-chat + AI chatbot widget. Add it to your site with the embed script or the JavaScript API.
Configure your chat widgetlink
- Log in to the merchant dashboard
- Navigate to Dashboard → Org → Chat (
/dashboard/org/[orgId]/chat) - Configure your widget: appearance, AI chatbot, routing rules, agent availability
- Copy your Widget API Key — this is the key ID only (e.g.
sk_live_abc123), not thekeyId:secretform. The widget runs in a browser; the secret must never appear in client-side code.
Embed the widget via script tag (auto-init)link
Add this to your HTML <head> or just before </body>:
<script
src="https://widget.newinstance.cloud/embed.js"
data-api-key="sk_live_abc123"
data-theme="dark"
data-position="bottom-right"
></script>data attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
data-api-key | string (required) | — | Widget key ID (NOT the full secret) |
data-theme | dark | light | system |
data-position | bottom-right | bottom-left | bottom-right |
Embed via JavaScript API (full control)link
<script src="https://widget.newinstance.cloud/embed.js"></script>
<script>
const widget = NInstanceChat.init({
apiKey: 'sk_live_abc123', // key ID only — never the secret
theme: 'dark',
position: 'bottom-right',
customerName: 'John',
customerEmail: 'john@example.com',
customerId: 'usr_123',
autoOpen: false,
callbacks: {
onAuth: (info) => console.log('Chat auth:', info.valid, info.status),
onOpen: () => console.log('Chat opened'),
onClose: () => console.log('Chat closed'),
},
});
// Programmatic control
widget.open();
widget.close();
widget.toggle();
widget.destroy();
// File attachments (before opening composer)
widget.attachFile(file);
widget.openComposer();
</script>NInstanceChat.init(config) options
| Option | Type | Description |
|---|---|---|
apiKey | string (required) | Widget key ID |
theme | dark | light |
transport | sse | ws |
customerName | string | Pre-fill customer name |
customerEmail | string | Pre-fill customer email |
customerId | string | Your internal customer ID |
position | bottom-right | bottom-left |
autoOpen | boolean | Open the chat on load |
buttonSize | number | Launcher button size in px |
panelWidth | number | Chat panel width in px |
panelHeight | number | Chat panel height in px |
zIndex | number | CSS z-index for the widget |
callbacks | object | onReady, onAuth, onOpen, onClose, onDestroy |
How the iframe bridge workslink
The widget loads in a sandboxed <iframe>. All communication between the host page and the widget uses postMessage with source-tag and origin validation:
- Host → widget messages are tagged with
ninstance-chat-host - Widget → host messages are tagged with
ninstance-chat
The widget fires onAuth after API key validation. The button stays hidden until onAuth confirms valid: true.
Permission scopes for Chat API keyslink
| Scope code | Description |
|---|---|
full-access | All chat permissions (recommended) |
ai-chatbot-access | Interact with AI chatbot |
live-chat-operations | Manage live chat sessions |
chat-configuration | Configure widget settings |