Documentation Index
Fetch the complete documentation index at: https://docs.inploi.com/llms.txt
Use this file to discover all available pages before exploring further.
Chatbot Plugin
The Chatbot plugin provides conversational flows for job applications and other interactions.
Installation
npm install @inploi/plugin-chatbot
pnpm add @inploi/plugin-chatbot
<script defer src="https://sdk.inploi.com/@inploi/sdk/cdn/index.js"></script>
<script defer src="https://sdk.inploi.com/@inploi/plugin-chatbot/cdn/index.js"></script>
Basic usage
import { initialiseSdk } from '@inploi/sdk';
import { chatbotPlugin } from '@inploi/plugin-chatbot';
const sdk = initialiseSdk({ publishableKey: 'pk_...', env: 'sandbox' });
const chatbot = sdk.register(chatbotPlugin({
theme: { hue: 260, mode: 'light' },
}));
// Prepare UI eagerly (optional but recommended)
await chatbot.prepare();
// Fetch and open a flow by job ID
const flow = chatbot.fetchFlowByJobId('12345');
chatbot.open(flow);
<script defer src="https://sdk.inploi.com/@inploi/sdk/cdn/index.js"></script>
<script defer src="https://sdk.inploi.com/@inploi/plugin-chatbot/cdn/index.js"></script>
<script>
document.addEventListener('DOMContentLoaded', async () => {
const sdk = inploi.initialiseSdk({ publishableKey: 'pk_...', env: 'sandbox' });
const chatbot = sdk.register(inploi.chatbotPlugin({
theme: { hue: 260, mode: 'light' },
}));
await chatbot.prepare();
// Open chatbot when user clicks apply
document.querySelector('#apply-btn').addEventListener('click', () => {
const flow = chatbot.fetchFlowByJobId('12345');
chatbot.open(flow);
});
});
</script>
Configuration
Theme
type ChatbotTheme = {
hue: number; // 0–360 color angle (e.g. 260 for purple, 33 for orange)
chroma?: number; // 0–1.5 color intensity multiplier (default 1)
mode: 'light' | 'dark';
};
Feedback integration
Collect feedback after conversations:
import { feedbackPlugin } from '@inploi/plugin-feedback';
const chatbot = sdk.register(chatbotPlugin({
feedback: {
plugin: feedbackPlugin(),
params: {
terms: {
negative_heading: "We're sorry to hear that. What went wrong?",
},
},
},
}));
Custom terms
Override default UI text. Common keys include send, skip, undo, maximize, minimize, close_application, upload_file, address_search, and various validation_* messages.
const chatbot = sdk.register(chatbotPlugin({
terms: {
send: 'Submit',
skip: 'Skip this',
undo: 'Go back',
},
}));
API
prepare()
Preloads UI assets. Optional but recommended to avoid delays.
open(flow)
Opens the chatbot with a flow (or a promise that resolves to a flow).
close()
Closes the chatbot UI and clears the in-memory flow state. The widget stays in the DOM and can be reopened with open().
destroy()
Fully tears down the chatbot — unmounts the UI, removes the DOM element, and resets all runtime state. Use this when the widget is no longer needed on the current page. After destroy(), call prepare() to re-initialise.
Use close() to hide the chatbot temporarily. Use destroy() for a full cleanup — for example, during page transitions on sites with client-side navigation.
fetchFlowByJobId(jobId, options?)
Fetches a conversation flow for a specific job. By default, the jobId is treated as the external (ATS) ID.
const flow = chatbot.fetchFlowByJobId('12345');
| Option | Type | Description |
|---|
idType | 'inploi' | 'ats' | ID type (default ats) |
context | Record<string, unknown> | Key-value variables available to the flow |
analytics | { customProperties?: Record<string, unknown> } | Custom data forwarded to analytics events |
locationOrigin | { lat?: number, lng?: number } | Coordinates for sorting address suggestions by proximity |
fetchFlowById(flowId, options?)
Fetches a conversation flow by its ID. Accepts the same options as fetchFlowByJobId (except idType).
const flow = chatbot.fetchFlowById('flow_abc123');
Soft navigation
If your site uses client-side navigation (e.g. Turbo, HTMX, SPA routers), the chatbot’s DOM can be removed without it knowing. Use destroy() before the page content is replaced, and re-initialise on the new page.
Turbo / Turbolinks
HTMX (hx-boost)
SPA routers
document.addEventListener('turbo:before-cache', () => chatbot.destroy());
document.addEventListener('turbo:load', () => chatbot.prepare());
document.addEventListener('htmx:beforeSwap', () => chatbot.destroy());
document.addEventListener('htmx:afterSettle', () => chatbot.prepare());
// Call destroy() in your route guard or unmount hook
router.beforeEach(() => chatbot.destroy());
router.afterEach(() => chatbot.prepare());
inploi.ready() is a DOM-ready helper — it replaces document.addEventListener('DOMContentLoaded', ...) for the initial page load. It does not replace framework-specific navigation hooks like turbo:load or htmx:afterSettle.
Full configuration reference
type ChatbotPluginParams = {
theme: ChatbotTheme;
feedback?: {
plugin: FeedbackPlugin;
/** When set, `terms` overrides feedback copy for this embed. */
params?: { terms: Partial<FeedbackTranslationTerms> };
};
terms?: Partial<ChatbotTranslationTerms>;
};
type ChatbotTheme = {
hue: number; // 0–360 color angle
chroma?: number; // 0–1.5 intensity multiplier (default 1)
mode: 'light' | 'dark';
};
type OpenChatbotParams = {
flow: Flow;
flowKeys: string[];
title: string;
context?: Record<string, unknown>;
analytics?: { customProperties?: Record<string, unknown> };
job?: { id: string; id_type: 'internal' | 'external' };
locationOrigin?: { lat?: number; lng?: number };
};
