Persona Inquiry JavaScript SDK

Common errors

• ReferenceError: Inquiry is not defined

  cause Attempting to import `Inquiry` from 'persona' when it has been moved to 'persona-react' (since v5.0.0).
  fix If using React, install `persona-react` (`npm install persona-react`) and update your import to `import Inquiry from 'persona-react'`.

• TypeError: Cannot read properties of undefined (reading 'inquiryId')

  cause Using the old positional argument signature for the `onComplete` callback after upgrading to `persona@5.0.0` or later.
  fix Update your `onComplete` callback to use destructuring keyword arguments: `onComplete: ({ inquiryId, status, fields }) => { ... }`.

• TypeError: Client is not a constructor

  cause Incorrectly importing `Client` in a CommonJS environment or mixing CommonJS `require()` syntax with ES Modules `import` syntax.
  fix For CommonJS, use `const { Client } = require('persona');`. Ensure your build setup correctly handles ES Modules if you intend to use `import` statements.

• Persona: Invalid configuration. Missing 'templateId'.

  cause The `templateId` option is a required parameter for initializing the Persona `Client`.
  fix Ensure the `templateId` property is correctly provided in the `Client` constructor options, for example: `templateId: 'your_template_id'`.

Warnings

• breaking Starting with `persona@5.0.0`, the `Inquiry` export (previously used for React integration) has been moved to a separate package, `persona-react`. Direct imports of `Inquiry` from `persona` will fail.
  Fix: If using React, install `persona-react` and change `import { Inquiry } from 'persona'` to `import Inquiry from 'persona-react'`.
• breaking The `onComplete` callback signature was significantly changed in `persona@5.0.0`. It now uses keyword arguments `{ inquiryId, status, fields }` instead of positional arguments. The `onFail` callback was removed entirely.
  Fix: Update your `onComplete` callback function signature to accept destructuring `({ inquiryId, status, fields }) => { ... }` and migrate any logic from `onFail` into `onComplete` by checking the `status` parameter.
• breaking The `onStart` callback was removed in `persona@5.0.0`. `onExit` and `client.exit()` were renamed to `onCancel` and `client.cancel()` respectively. The `accessToken` parameter was renamed to `sessionToken`.
  Fix: Replace `onStart` with the `onEvent` callback (listening for `Event.Start`), rename `onExit` to `onCancel` and `client.exit()` to `client.cancel()`, and update references of `accessToken` to `sessionToken` in callback arguments.
• deprecated Features such as `prefill`, `lockedAttributes`, `themeId`, and the `InquiryAttributes` type export, which were deprecated in `persona@4.0.0`, have been completely removed in `persona@5.0.0`.
  Fix: Migrate to using the `fields` parameter for prefilling and attribute locking, and rely on template-level configuration for themes. Remove any usage of `InquiryAttributes` type.
• gotcha The package `persona` provides its own TypeScript type definitions. Installing `@types/persona` is unnecessary and the `@types` package is deprecated, which can lead to type conflicts or confusion.
  Fix: Uninstall `@types/persona` if it is present in your project. The types are included directly with the `persona` package.

Install

• npm install persona npm
• yarn add persona yarn
• pnpm add persona pnpm

Imports

• Client
  wrong:

  const Client = require('persona');

  correct:

  import { Client } from 'persona';

  The Client class is a named export. CommonJS users should use destructuring from require().
• PersonaInquiryOptions

  import type { PersonaInquiryOptions } from 'persona';

  TypeScript type for the configuration object passed to the Client constructor.
• ClientCallbacks

  import type { ClientCallbacks } from 'persona';

  TypeScript type for the various event callback functions (onComplete, onCancel, onError, onEvent).

Quickstart

Demonstrates how to initialize the Persona `Client` for an embedded inquiry flow, configure its environment, and set up essential event callbacks for `onReady`, `onComplete`, `onCancel`, and `onError` to manage the user journey.

import { Client } from 'persona';

// Initialize the Persona client for an embedded inquiry flow.
const client = new Client({
  // Replace with your actual template ID, or use the provided demo template for testing.
  templateId: 'itmpl_Ygs16MKTkA6obnF8C3Rb17dm',
  // Use 'sandbox' for development and testing, 'production' for live applications.
  environment: 'sandbox',
  // Callback executed when the Persona flow is ready to be opened.
  onReady: () => {
    console.log('Persona client is ready, opening flow...');
    client.open();
  },
  // Callback for when the inquiry process is successfully completed.
  onComplete: ({ inquiryId, status, fields }) => {
    console.log('Inquiry completed:', { inquiryId, status, fields });
    // Handle post-completion logic, e.g., notify your backend, update UI.
  },
  // Callback for when the user cancels the inquiry flow.
  onCancel: ({ inquiryId, sessionToken }) => {
    console.log('Inquiry cancelled:', { inquiryId, sessionToken });
    // Handle cancellation, e.g., log, return user to previous state.
  },
  // Callback for any errors encountered during the inquiry process.
  onError: (error) => {
    console.error('Persona inquiry error:', error);
    // Implement robust error handling and user feedback.
  },
  // Optional: Set allowed events for the onEvent callback (e.g., ['step-transitioned', 'click']).
  // eventsAllowlist: ['all']
});

console.log('Persona client initialized.');