@risecx/carespace-chat-ui
Version:
carespace-chat-ui React component
288 lines (251 loc) • 8.81 kB
Markdown
# carespace-chat-ui
`carespace-chat-ui` provides an intercom-like chat window that can be included easily in any project for free. It provides no messaging facilities, only the view component.
## Features
- Customizeable
- Backend agnostic
- Free
## [Demo](https://www.carespace.ai/carespace-chat-ui/)
## Table of Contents
- [Installation](#installation)
- [Example](#example)
- [Components](#api)
## Installation
```
$ npm install carespace-chat-ui
```
## Example
```javascript
import React, { Component } from "react";
import { Launcher } from "carespace-chat-ui";
class Demo extends Component {
constructor() {
super();
this.state = {
messageList: []
};
}
_onMessageWasSent(message) {
this.setState({
messageList: [...this.state.messageList, message]
});
}
_sendMessage(text) {
if (text.length > 0) {
this.setState({
messageList: [
...this.state.messageList,
{
author: "them",
type: "text",
data: { text }
}
]
});
}
}
render() {
return (
<div>
<Launcher
agentProfile={{
teamName: "carespace-chat-ui",
avatarImageUrl:
"https://a.slack-edge.com/66f9/img/avatars-teams/ava_0001-34.png"
}}
onMessageWasSent={this._onMessageWasSent.bind(this)}
messageList={this.state.messageList}
showEmoji
/>
</div>
);
}
}
```
For more detailed examples see the demo folder.
## Components
# Launcher
`Launcher` is the only component needed to use carespace-chat-ui. It will react dynamically to changes in messages. All new messages must be added via a change in props as shown in the example.
Launcher props:
| prop | type | required | description |
| ---------------- | ------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| agentProfile | [object](#agent-profile-objects) | yes | Represents your product or service's customer service agent. Fields: avatarImageUrl (string), teamName (string). |
| handleClick | function | yes | Intercept the click event on the launcher. No argument sent when function is called. |
| isOpen | boolean | yes | Force the open/close state of the chat window. If this is not set, it will open and close when clicked. |
| messageList | [[message](#message-objects)] | yes | An array of message objects to be rendered as a conversation. |
| mute | boolean | no | Don't play sound for incoming messages. Defaults to `false`. |
| newMessagesCount | number | no | The number of new messages. If greater than 0, this number will be displayed in a badge on the launcher. Defaults to `0`. |
| onFilesSelected | function([fileList](https://developer.mozilla.org/en-US/docs/Web/API/FileList)) | no | Called after file has been selected from dialogue in chat window. |
| onMessageWasSent | function([message](#message-objects)) | yes | Called when a message is sent, with a message object as an argument. |
| showEmoji | boolean | no | Whether or not to show the emoji button in the input bar. Defaults to `true`. |
| launcherIcon | string | no | A image url which represents the chat launcher icon |
### Message Objects
Message objects are rendered differently depending on their type. Currently, only text, file, and emoji types are supported. Each message object has an `author` field which can have the value 'me' or 'them'.
```javascript
{
author: 'them',
type: 'text',
data: {
text: 'some text'
}
}
{
author: 'me',
type: 'emoji',
data: {
code: 'someCode'
}
}
{
author: 'me',
type: 'file',
data: {
url: 'somefile.mp3',
fileName: 'Any old name'
}
}
{
author: "them",
type: "card",
data: {
title: "Welcome!",
image_url: "https://via.placeholder.com/300.png/09f/fff",
subtitle: "We have the right hat for everyone.",
buttons: [
{
type: "web_url",
url: "https://petersfancybrownhats.com",
title: "View Website"
},
{
type: "postback",
title: "Start Chatting",
payload: "DEVELOPER_DEFINED_PAYLOAD"
}
]
}
}
{
author: "them",
type: "list",
data: {
title: "Welcome!",
image_url: "https://www.fillmurray.com/300/300",
subtitle: "We have the right hat for everyone.",
elements: [
{
title: "Classic T-Shirt Collection",
subtitle: "See all our colors",
image_url: "https://www.fillmurray.com/60/60",
buttons: [
{
title: "View",
type: "web_url",
url: "https://peterssendreceiveapp.ngrok.io/collection",
messenger_extensions: true,
webview_height_ratio: "tall",
fallback_url: "https://peterssendreceiveapp.ngrok.io/"
}
]
},
{
title: "Classic Blue T-Shirt",
image_url: "http://placeimg.com/60/60/any",
subtitle: "100% Cotton, 200% Comfortable",
default_action: {
type: "web_url",
url: "https://peterssendreceiveapp.ngrok.io/view?item=101",
messenger_extensions: true,
webview_height_ratio: "tall",
fallback_url: "https://peterssendreceiveapp.ngrok.io/"
},
buttons: [
{
title: "Shop Now",
type: "web_url",
url: "https://peterssendreceiveapp.ngrok.io/shop?item=101",
messenger_extensions: true,
webview_height_ratio: "tall",
fallback_url: "https://peterssendreceiveapp.ngrok.io/"
}
]
}
]
}
}
{
author: "them",
type: "quickResponse",
data: {
text: "What do you want to do next?",
buttons: [
{
type: "web_url",
url: "https://www.messenger.com",
title: "Visit Messenger"
},
{
type: "web_url",
url: "https://www.messenger.com",
title: "Visit Page"
},
{
type: "postback",
payload: "BACK_SLEEP",
title: "Back to Sleep"
}
]
}
}
{
author: "them",
type: "gallery",
data: {
elements: [
{
title: "Welcome!",
image_url: "https://via.placeholder.com/300.png/09f/fff",
subtitle: "We have the right hat for everyone.",
buttons: [
{
type: "web_url",
url: "https://petersfancybrownhats.com",
title: "View Website"
},
{
type: "postback",
title: "Start Chatting",
payload: "DEVELOPER_DEFINED_PAYLOAD"
}
]
},
{
title: "Good Bye!!",
image_url: "https://via.placeholder.com/300.png/09f/fff",
subtitle: "Cya babe.",
buttons: [
{
type: "web_url",
url: "https://petersfancybrownhats.com",
title: "View Website"
},
{
type: "postback",
title: "Start Chatting",
payload: "DEVELOPER_DEFINED_PAYLOAD"
}
]
}
]
}
}
```
### Agent Profile Objects
Look like this:
```js
{
avatarImageUrl: 'https://somewhere.on/the_web.png',
teamName: 'Da best'
}
```
## People Using carespace-chat-ui
If you're using carespace-chat-ui in a product I'd love to see what you're making! Email me at cristofer@risecx.com