Skip to main content

​
Chatbot Plugin

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

​
Installation

npm install @inploi/plugin-chatbot

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

​
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:
OptionTypeDescription
idType'inploi' | 'ats'ID type (default ats)
contextRecord<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.
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 };
};