npm package: @inconvo/chat-client
Description: Inconvo chat client.
Author: Inconvo
Latest version: 3.14.0

# Inconvo chat client

Loads an Inconvo chat on any website.

## Installation

```sh
npm install @inconvo/chat-client
```

## Usage

### Import library

```javascript
import * as inconvoChat from '@inconvo/chat-client';
//or
const inconvoChat = require('@inconvo/chat-client');
```

### Create client

```javascript
//synchronously
await inconvoChat.createClient({
    appCode: '{app-code}',
});

//or asynchronously
inconvoChat
    .createClient({
        appCode: '{app-code}',
    })
    .then(() => {
        console.log('loaded');
    });
```

### Start a convo

```javascript
yc.startChat({
    channel: 'channel-slug',
    convo: 'convo-id',
});
```

or

```html
<button onclick="yc.startChat({channel: 'channel-slug', convo: 'convo-id'})">Start Convo</button>
```

### Subscribe to an event

```javascript
chatWidget.addEventListener('openLink', (action) => {});
```

### Unsubscribe from an event

```javascript
chatWidget.removeEventListener('openLink', (action) => {});
```

## API

### createClient({options})

Creates a chat client.

#### options

| Option      | Type     | Required | Default   | Description                                                                                                                                                                                                                                                                                                                                                                                                                |
|-------------|----------|----------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| appCode     | string   | yes      | --        | App code provided by YouGov Chat                                                                                                                                                                                                                                                                                                                                                                                           |
| appKey      | string   | no       | --        | App key provided by YouGov Chat                                                                                                                                                                                                                                                                                                                                                                                            |
| appSecret   | string   | no       | --        | App secret provided by YouGov Chat                                                                                                                                                                                                                                                                                                                                                                                         |
| mode        | string   | no       | 'sidebar' | `sidebar` - opens chat in the right hand side of the window, or <br>  `floating` - creates a floating action button which can be clicked to start a chat or <br>  `full-screen` - the chat window covers the full page or <br>  `host` - it doesn't add button to the screen and doesn't set the position of the chat window, it can be configurable from the host <br> `channel-view` - opens chat in single channel view |
| moduleName  | string   | no       | 'yc'      | The name of the object that will be available to use once the client is created                                                                                                                                                                                                                                                                                                                                            |
| channel     | string   | no       | --        | if provided, opens a chat for this channel (default convo if `convo` is not provided) once the client is created                                                                                                                                                                                                                                                                                                           |
| convo       | string   | no       | --        | if provided, opens a chat for this channel/convo once the client is created                                                                                                                                                                                                                                                                                                                                                |
| standalone  | boolean  | no       | true      | It determines that the chat widget completely integrated to the website. Eg. instead of handling links in the chat widget it emits events.                                                                                                                                                                                                                                                                                 |
| showBubble  | boolean  | no       | false     | It determines if the chat widget will show bubble controls or not.                                                                                                                                                                                                                                                                                                                                                         |
| closable    | boolean  | no       | true      | It determines if the chat widget should close on outside click.                                                                                                                                                                                                                                                                                                                                                            |
| onInit      | function | no       | --        | if provided, executes this function once the client is created                                                                                                                                                                                                                                                                                                                                                             |
| onEvent     | function | no       | --        | if provided, executes this function once an event is triggered                                                                                                                                                                                                                                                                                                                                                             |
| topic       | string   | no       | --        | if provided, start chat won't require a convo or channel, it will start with the first available convo with the specified topic                                                                                                                                                                                                                                                                                            |
| countryCode | string   | no       | --        | if provided, it will filter the topics with country code                                                                                                                                                                                                                                                                                                                                                                   |

#### events

| Event name    | Trigger                                                   | Data                                                       |
|---------------|-----------------------------------------------------------|------------------------------------------------------------|
| userSubscribe | user submits their email address in the subscribe message | Object containing: `channelSlug`, `convoId` (if available) |
| openLink      | user clicks to a link in a message                        | action                                                     |
| sendReply     | user replies to a question                                | Object containing: `question` and `answer`                 |

### startChat({options})

Opens a chat window.

#### options

| Option  | Type            | Required | Description                                                                                                                                |
|---------|-----------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------|
| channel | string / object | yes*     | pass the channel slug and the widget will load the channel or pass the channel object directly  (default convo if `convo` is not provided) |
| convo   | string          | no       | opens a chat for this channel/convo                                                                                                        |

&ast; if a topic is provided in the createClient method, channel won't be mandatory 

### setConvo({options})

Sets the client channel/convo. This is useful for the `floating` mode.

#### options

| Option  | Type   | Required | Description                                                          |
|---------|--------|----------|----------------------------------------------------------------------|
| channel | string | yes      | sets the client's channel (default convo if `convo` is not provided) |
| convo   | string | no       | set's the client's convo                                             |

### changeMode(mode)

Changes the mode at runtime.

#### options

| Option | Type   | Required | Description |
|--------|--------|----------|-------------|
| mode   | string | yes      | floating    | sidebar | full-screen | host| channel-view | 

### show()

Show the chat controls.

#### usage

```javascript
chatWidget.show();
```

### hide()

Hide the chat controls.

#### usage

```javascript
chatWidget.hide();
```

### getConvosByTopic

This method returns with an array of convos filtered by topic id and country code.

#### usage

```typescript
import { getConvosByTopic } from  "@inconvo/chat-client";

const convos = await getConvosByTopic('topic-id', 'country-code');
```
#### parameters

| Parameters      | Type   | Required | Description            |
|-----------------|--------|----------|------------------------|
| TopicId         | string | yes      | YouGov Topic ID        |
| CountryCode     | string | no       | It filters the topics  |