Caution

This repository has been archived, will no longer be maintained and should not be referenced as an example of consuming our APIs going forward. The bundled version of this widget will continue to be hosted on our CDN until its sunset date of April 15th, 2025.

For the latest details on our APIs see our documentation.

React Chat

A react-based chat widget built to interact seamlessly with Voiceflow's runtime.

Installation

We recommend using yarn to install the package:

yarn add @voiceflow/react-chat

Configuration

interface Configuration {
  verify: {
    /**
     * the ID of your voiceflow project, the project must have `apiPrivacy: public`
     * find this under integrations tab
     */
    projectID: string;
  };

  /**
   * [optional] userID to track users and persist/continue sessions
   */
  userID?: string;

  /**
   * [optional] user metadata for transcripts
   */
  user?: {
    name?: string;
    image?: string;
  };

  /**
   * [optional] the version ID of your project, defaults to 'development'
   * can be a 'development' or 'production' alias or a specific versionID
   */
  versionID?: string;

  /**
   * [optional] voiceflow dialog management runtime endpoint
   * defaults to https://general-runtime.voiceflow.com
   */
  url?: string;

  /**
   * [optional] override configured assistant definitions on integrations tab
   */
  assistant?: {
    title?: string;
    image?: string;
    color?: string;
    description?: string;
    stylesheet?: string;
  };

  launch?: {
    event?: RuntimeAction;
  };
}

Browser Usage

You can use a simple JavaScript snippet to add the chat widget to any HTML page. Ensure that the verify: { projectID: ... } field is replaced with your Voiceflow projectID.

<script type="text/javascript">
  (function (d, t) {
    var v = d.createElement(t),
      s = d.getElementsByTagName(t)[0];
    v.onload = function () {
      window.voiceflow.chat.load({
        verify: { projectID: 'XXXXXX...' },
      });
    };
    v.src = 'https://cdn.voiceflow.com/widget/bundle.mjs';
    v.type = 'text/javascript';
    s.parentNode.insertBefore(v, s);
  })(document, 'script');
</script>

Browser API

When the react-chat script is loaded it will register an API as window.voiceflow.chat. It has the following interface:

interface VoiceflowAPI {
  // (re)load the chat
  // chat will not be visible until called
  load: (config: Configuration) => void;

  // open the chat
  open: () => void;

  // close the chat
  close: () => void;

  // hide the chat + button
  hide: () => void;

  // show the chat + button
  show: () => void;

  // send custom interaction to voiceflow
  interact: (action: RuntimeAction) => void;

  proactive: {
    push: (...messages: Trace[]) => void;
    clear: () => void;
  };
}

Example call:

window.voiceflow.chat.show();

Running Locally

To run the chat locally you will need to create a local .env file with your configuration. This will include our Voiceflow project ID and the runtime endpoint.

Create a new file packages/react-chat/.env.development.local with the following contents:

VITE_VF_PROJECT_ID='< your project ID >'
VITE_VF_VERSION_ID='< your version ID [development | production] >'
VITE_VF_RUNTIME_URL='https://general-runtime.voiceflow.com'

Now that the chat is configured, let's install dependencies and run the development server.

# install dependencies
yarn install

# build all packages
yarn build

# run dev server
yarn local

Once the server is running it should automatically open your browser with the chat widget.