README.md

Distribute Aid in-app-chat UI

This provides the UI for the in-app-chat as a standalone micro-frontend.

Installation

Installation depends on the approach you are using, at minimum:

• include the Chat UI Bundle attached to the releases

Launch the chat:

DAChat({
  context: "general", // identifies the context to open
  apiKey: "da2-XXX", // API key for the Twilio Integration API
  apiEndpoint: "https://xxx.appsync-api.yyy.amazonaws.com/graphql", // AppSync endpoint of the Twilio Integration API
  token: "", // JWT generated by your backend
});

Here is the Toolbox example which has a feature flag and lazy loading.

Development

ℹ️ These instructions apply to Unix-based development environments; Linux and Mac users should be fine. Windows users could look into setting up their development environment using WSL2.

Configuration

ℹ️ Linux users can use direnv to simplify the process.

Provide the integration API's settings in the environment variables:

export GRAPHQL_API_ENDPOINT=https://xxx.appsync-api.yyy.amazonaws.com/graphql
export GRAPHQL_API_KEY=xxx-yyy

Running the development server

Start the development server

npm ci
npm start

Tokens

The chat expects a valid JWT which will be verified by the integration, follow the instructions here to create a token.

Lazy loading the Chat widget

The Chat UI provides a light-weight chat button which can be shown to the user which only has a weight of 4KB (a loader for JS files and the chat icon), only after the user clicks the button, the JavaScript for the entire chat widget will be loaded. A cookie will remember whether the chat should be open.

The small chat button is only show if a localStorage setting is enabled: window.localStorage.setItem('DAChat:enabled', '1'), this way we can test the feature without needing a feature flag in the toolbox.

Introduction to the project structure

UI and features

Note: This documentation is for version 1.17.1 of the chat-ui.

Getting started

Enabling the chat for your browser

Note: The chat feature is hidden by default, and the following steps need to done only once, but for every browser you are using.

1. Go to https://toolbox.distributeaid.org/
2. Log in
3. Open the browser console (by pressing F12).
4. Copy the following line and paste it in the command line: window.localStorage.setItem('DAChat:enabled', '1')
5. Press Enter.
6. Press F12 again to close the browser console.
7. Reload the page.

The chat button will now show up.

Opening the chat

Click the blue chat icon to open the chat window.

Note: If this is the first time, it may take a few seconds to load the client, however this will only happen once, and cached so that on subsequent page loads the chat will be available immediately.

The chat window will open and you will be able to chat in the #general and the #random channel.

Error on first connect: Failed to join channel "general"

You may see an error message at the bottom of the chat UI:

This is known and on the todo list, simply reload the page and the error should go away.

Writing chat messages

Enter your message in the input field on the bottom, press enter or click the send icon. Markdown is supported.

You can delete messages by clicking the delete icon.

Switching channels

Click on the top bars to switch between your channels:

Leave a channel

Click the close icon to leave a channel. For now, the channel will be restored on the next page reload. You cannot leave the last remaining channel.

Minimize Chat

Click the minimize icon to minimize the chat UI:

Slash Commands

The chat supports slash commands which you run by typing / and a command. Try /help, it will list all available commands.

Architecture decision records (ADRs)

see ./adr.