super-great-testing-chat-temp v0.1.89

Carbon for watsonx web chat with React

Be sure to review the chat documentation.

Installation

To install using npm:

npm install super-great-testing-chat-temp

Or using yarn:

yarn add super-great-testing-chat-temp

Using ChatContainer

Basic example

The WebChatContainer function component is intended to make it as easy as possible to include web chat in your React application. To use, you simply need to render this component anywhere in your application and provide the web chat configuration options object as a prop.

import React from 'react';
import { ChatContainer } from 'super-great-testing-chat-temp';

const webChatOptions = {
  // Your configuration object.
};

function App() {
  return <ChatContainer config={webChatOptions} />;
}

Props

ChatContainer has the following props.

Using ChatCustomElement

This library provides the component ChatCustomElement which can be used to aid in rendering web chat inside a custom element. This is needed if you want to be able to change the location where web chat is rendered. This component will render an element in your React app and use that element as the custom element for rendering web chat.

The default behavior of this component will add and remove a classname from the web chat main window as well as your custom element to control the visibility of web chat when it is opened or closed. It will also inject a style tag into your application to define the rules for these classnames. When web chat is closed, a classname will be added to the web chat main window to hide the element and a classname will be added to your custom element to set its width and height to 0 so it doesn't take up space. Note that the custom element should remain visible if you want to use the built-in web chat launcher which is also contained in your custom element.

If you don't want these behaviors, then provide your own onViewChange prop to ChatCustomElement and provide your own logic for controlling the visibility of web chat. If you want custom animations when web chat is opened and closed, this would be the mechanism to do that.

The simplest example is this:

import React from 'react';
import { ChatCustomElement } from 'super-great-testing-chat-temp';

import './App.css';

const webChatOptions = { /* Web chat options */ };

function App() {
  return <ChatCustomElement className="MyCustomElement" config={webChatOptions} />;
}

.MyCustomElement {
  position: absolute;
  left: 100px;
  top: 100px;
  width: 500px;
  height: 500px;
}

Props

ChatCustomElement inherits all of the props from ChatContainer. It also has the following additional optional props.

Accessing instance methods

You can use the onBeforeRender or onAfterRender props to get access to the instance of web chat if you need call instance methods later. This example renders a button that toggles web chat open and is only rendered after the instance has become available.

import React, { useCallback, useState } from 'react';
import { ChatContainer } from 'super-great-testing-chat-temp';

const webChatOptions = {
  // Your configuration object.
};

function App() {
  const [instance, setInstance] = useState(null);

  const toggleWebChat = useCallback(() => {
    instance.toggleOpen();
  }, [instance]);

  return (
    <>
      {instance && (
        <button type="button" onClick={toggleWebChat}>
          Toggle web chat
        </button>
      )}
      <ChatContainer config={webChatOptions} onBeforeRender={(instance) => onBeforeRender(instance, setInstance)} />
    </>
  );
}

function onBeforeRender(instance, setInstance) {
  // Make the instance available to the React components.
  setInstance(instance);

  // Do any other work you might want to do before rendering. If you don't need any other work here, you can just use
  // onBeforeRender={setInstance} in the component above.
}

User defined responses

This component is also capable of managing user defined responses. To do so, you need to pass a renderUserDefinedResponse function as a render prop. This function should return a React component that will render the content for the specific message for that response. You should make sure that the ChatContainer component does not get unmounted in the middle of the life of your application because it will lose all user defined responses that were previously received by web chat.

You should treat the renderUserDefinedResponse prop like any typical React render prop; it is different from the userDefinedResponse event or a typical event handler. The event is fired only once when web chat initially receives the response from the server. The renderUserDefinedResponse prop however is called every time the App re-renders and it should return an up-to-date React component for the provided message item just like the render function would for a typical React component.

import React from 'react';
import { ChatContainer } from 'super-great-testing-chat-temp';

const webChatOptions = {
  // Your configuration object.
};

function App() {
  return <ChatContainer renderUserDefinedResponse={renderUserDefinedResponse} config={webChatOptions} />;
}

function renderUserDefinedResponse(event) {
  // The event here will contain details for each user defined response that needs to be rendered.
  // The "user_defined_type" property is just an example; it is not required. You can use any other property or
  // condition you want here. This makes it easier to handle different response types if you have more than
  // one user defined response type.
  if (event.data.message.user_defined && event.data.message.user_defined.user_defined_type === 'my-custom-type') {
    return <div>My custom content</div> // This can be any full React component.
  }
}