# Get Started with Webchat Plugins

**Cognigy Support**

February 1, 2022

Cognigy Webchat Plugins are built on top of [React](https://reactjs.org/). If you are unfamiliar with `React` or the `jsx` file format, I would recommend taking the Tutorial on their site first.

## Setting up your development environment

Since we are using React, we need a bit of setup before coding. The easiest way is to use a bundler called [parcel](https://parceljs.org/).

> If your parcel installation is slow, make sure to update to the newest NPM version

- `npm init`
- `npm i -D parcel`
- `npm i react`

Open your `package.json` file and add a new "build" job at the "scripts" field:

```
{
    ...,
    "scripts": {
        ...,
        "build": "parcel build --out-file webchat-plugin.js src/index.jsx"
    },
    "alias": {
        "react": "./alias/react"
    }
    ...
}
```

- create a folder called `alias`
- in this new folder, create a file called `react.js`
- insert the following code in it:

```
if (!window.__COGNIGY_WEBCHAT)
    throw new Error('Cognigy Webchat v2.7 or higher has to be loaded before this plugin');

module.exports = window.__COGNIGY_WEBCHAT.React;
```

- this configuration will make the webchat plugin use the webchat's built-in react version
- create src/index.jsx

## Define a Message Component

In the first step, we will create a React Component that will be used to render a message. Via its `props`, it will get a `message` property representing the content of the message we want to render. Inside that `message` object, we have a `text` property containing the raw text of the message. We will return a `<span>` with red font color containing the `text` value of the message.

```javascript
// src/index.jsx

import * as React from 'react'

const RedText = (props) => {
    const text = props.message.text

return (
        <span style={{ color: 'red' }}>
            {text}
        </span>
    )
}
```

## Create a Plugin Object

Now that we have our Message Component, it's time to use it in a plugin definition. A Message Plugin definition is an object that must contain a `match` and a `component` value. The `match` value is used to decide for which messages this plugin should be used, and the `component` value tells the webchat what Message Component to use with this plugin.

```javascript
// src/index.jsx (continued)

const redTextPlugin = {
    match: 'red-text',
    component: RedText
}
```

Setting `match` to `'red-text'` means that this plugin will match if a message has `data` that is set up like this:

```
{
  "_plugin": {
    "type": "red-text"
  }
}
```

## Register the Plugin

In order to cause the plugin to be recognized by the webchat, it needs to be put at a specific location in the `window` object. At that location, we have a list of [webchat plugins](https://github.com/Cognigy/WebchatPlugins) where we want to append our plugin. Because our plugin might be registered first, it may be that the list does not exist yet, so we have to make sure to create it if it does not exist yet.

```javascript
// src/index.jsx (continued)

// create if it does not exist yet
if (!window.cognigyWebchatMessagePlugins) {
    window.cognigyWebchatMessagePlugins = []
}

window.cognigyWebchatMessagePlugins.push(redTextPlugin);
```

## Intermediate Recap

By now, our plugin code should contain

- a Message Component
- a Plugin definition
- a 'registration' of our plugin definition

```
import * as React from 'react'

const RedText = (props) => {
    const text = props.message.text

return (
        <span style={{ color: 'red' }}>
            {text}
        </span>
    )
}

const redTextPlugin = {
    match: 'red-text',
    component: RedText
}

if (!window.cognigyWebchatMessagePlugins) {
    window.cognigyWebchatMessagePlugins = []
}

window.cognigyWebchatMessagePlugins.push(redTextPlugin);
```

## Building the Plugin

Now that we have our complete plugin code ready, we can go on and build it by running `npm run build` in the command line within the plugin folder. It should create a `webchat-plugin.js` file. Load that file into a website before calling `initWebchat` and you are set!

## Notes

If you run into problems when building the plugin, please try to change the version of parcel to 1.12.3, by running

```
npm i --save-dev parcel@1.12.3
```

### Webchat Plugins

- [Webchat Plugins Overview](https://support.cognigy.com/hc/en-us/articles/360019600399-Webchat-Plugins-Overview)
- [Get Started with Webchat Plugins](https://support.cognigy.com/hc/en-us/articles/360019600619-Get-Started-with-Webchat-Plugins)
- [Webchat Plugins Installation](https://support.cognigy.com/hc/en-us/articles/360019611899-Webchat-Plugins-Installation)
- [Display Plugin in Webchat](https://support.cognigy.com/hc/en-us/articles/360019613419-Display-Plugin-in-Webchat)