Chatbot Plugin

The Chatbot plugin provides conversational flows for job applications and other interactions.

Installation

npm
pnpm
CDN

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

Package
CDN

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.

await chatbot.prepare();

`open(flow)`

Opens the chatbot with a flow (or a promise that resolves to a flow).

chatbot.open(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().

chatbot.close();

`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.

chatbot.destroy();

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');

Options:

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');

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 };
};

Overview

Plugins

Chatbot Plugin

Chatbot Plugin

Installation

Basic usage

Configuration

Theme

Feedback integration

Custom terms

API

`prepare()`

`open(flow)`

`close()`

`destroy()`

`fetchFlowByJobId(jobId, options?)`

`fetchFlowById(flowId, options?)`

Soft navigation

Full configuration reference

​Chatbot Plugin

​Installation

​Basic usage

​Configuration

​Theme

​Feedback integration

​Custom terms

​API

​prepare()

​open(flow)

​close()

​destroy()

​fetchFlowByJobId(jobId, options?)

​fetchFlowById(flowId, options?)

​Soft navigation

​Full configuration reference

Chatbot Plugin

Installation

Basic usage

Configuration

Theme

Feedback integration

Custom terms

API

`prepare()`

`open(flow)`

`close()`

`destroy()`

`fetchFlowByJobId(jobId, options?)`

`fetchFlowById(flowId, options?)`

Soft navigation

Full configuration reference