chatwoot/docs

Official docs, handbook for Chatwoot

Chatwoot Handbook

This repository contains the documentation for self-hosted installations, features in the product and a complete guide on how we run the organization.

---

Installation

yarn install

Local Development

yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Please feel free to suggest any changes. See our contributing guide to get started.

docs's Issues

Update instagram callback events

chore: Use consistent version of node.js across chatwoot using nvm

• Set the base version of node. [16.1.0 ] [ PR: https://github.com/chatwoot/chatwoot/pull/2400 ]
• Change the ubuntu installation scripts to use specified node version.
• Ensure docker images stays consistent with specified node version
• Update environment set up documentation to use nvm

chore: Create a video tutorial of configuring Facebook in Chatwoot end to end

@pranavrajs could you please also create some video for self hosted configuration of FB creds? I tried to integrate but it is not clear what all permissions must be given to the business app created on developers dashboard ? A details video on facebook setup for chatwoot would be really beneficial. Thanks for wonderful product. It will be good if you can maintain separate code for community edition and enterprise edition.

Originally posted by @rahulmr in chatwoot/chatwoot#3578 (comment)

Sidebar: Support for third level menu

• Current sidebar only support 2 levels of navigation, need to come up with design and functionality for sidebar

doc: Email channel using postfix

Creating documentation on how to set up a self-hosted chatwoot, where the email channel works with postfix

Updation in Readme.md

Hello,
There is a grammatical error in the Readme.md that I'd like to work on. Please assign this to me since I would like to work on this issue.

doc: Documentation about changing chatwoot branding

• have an FAQ section about chatwoot branding / changing that
  ref: https://discord.com/channels/897869226579222540/897872508034879490/922442589230227476

Documentation for forward to email feature in email channel.

Create documentation for Forward to Email feature in the email channel.

doc: update caprover documentations to address the following

ref: https://discord.com/channels/647412545203994635/704008423468957707/895926998755581983

Caprover install on DigitalOcean is pretty straight forward. But from there on it's a nightmare to get the Chatwoot to behave in a proper way. I will list down the 2-3 days struggle here. Still no success.

1. After the one-click app install and all the DNS settings all done and verified, immediately go for an upgrade to latest docker versions.
2. Then access rails console to enable super_admin interface,
3. Then enable email_channel, inbound_emails etc. (lots of search in docs for self hosted chatwoot, and tried everything that makes sense )
   the environment variable settings are another saga. Somehow most of it is now working. except conversation continuity and email channel. Figured out Postmark config, and I can see inbound emails being processed. The webhook to chatwoot from there is also tested to be working. The "check" gives http 204 status.
   What now?
   Only Sendgrid is supported or any documentaton for postmark too?
   Will the active storage work without any .env setting explicitly?
   In the Cprover deployment log, I have a warning: [Warning] One or more build-args [SECRET_KEY_BASE POSTGRES_HOST POSTGRES_USERNAME MAILER_SENDER_EMAIL VAPID_PRIVATE_KEY RAILS_LOG_TO_STDOUT POSTGRES_PASSWORD REDIS_URL REDIS_PASSWORD FRONTEND_URL RAILS_INBOUND_EMAIL_PASSWORD VAPID_PUBLIC_KEY MAILER_INBOUND_EMAIL_DOMAIN RAILS_ENV ACTIVE_STORAGE_SERVICE POSTGRES_DATABASE SMTP_ADDRESS SMTP_PASSWORD RAILS_INBOUND_EMAIL_SERVICE POSTMARK_INGRESS_API_KEY SMTP_USERNAME] were not consumed
   Is that serous?

Improve the documentation for caprover

Email forwarded from Cpanel and parsed by Sendgrid is not captured email channel

Self-hosted digital ocean, Caprover. (Chatwoot version v1.21.1 )
Emails forwarded to email channel address from Cpanel, with 'Forwarder' as well as 'Global Filter' feature of Cpanel. Email arrives in Chatwoot as evident from the app log. Conversation is not created with many tries.
No difference with Sendgrid SPAM check on or off.
No difference from different mail clients like gmail web, 'Mail' on iPhone, etc.
However sending directly to the cryptic address of the email channel works okay.
Problem is only when Cpanel forwarder is involved.

App log excerpts:
...
2021-10-21T03:41:29.098915585Z I, [2021-10-21T03:41:29.098802 #1] INFO -- : [7840f094-e28d-4480-b7e9-6675fa47e63d] Processing by ActionMailbox::Ingresses::Sendgrid::InboundEmailsController#create as HTML
....
2021-10-21T03:41:29.134000382Z I, [2021-10-21T03:41:29.133834 #1] INFO -- : [7840f094-e28d-4480-b7e9-6675fa47e63d] S3 Storage (17.1ms) Uploaded file to key: 0udzyf9hwx4hw2x4le7eg5n42eef (checksum: GgDmIgk8BgwQN0pFrVegPg==)
2021-10-21T03:41:29.136376300Z I, [2021-10-21T03:41:29.136234 #1] INFO -- : [7840f094-e28d-4480-b7e9-6675fa47e63d] [ActiveJob] Enqueued ActionMailbox::RoutingJob (Job ID: de834955-b287-4ccd-9f53-5631917755c5) to Sidekiq(action_mailbox_routing) with arguments: #<GlobalID:0x00007f4b716e5938 @uri=#<URI::GID gid://chatwoot/ActionMailbox::InboundEmail/74>>
2021-10-21T03:41:29.141726324Z I, [2021-10-21T03:41:29.141581 #1] INFO -- : [7840f094-e28d-4480-b7e9-6675fa47e63d] No template found for ActionMailbox::Ingresses::Sendgrid::InboundEmailsController#create, rendering head :no_content
2021-10-21T03:41:29.142128850Z I, [2021-10-21T03:41:29.142007 #1] INFO -- : [7840f094-e28d-4480-b7e9-6675fa47e63d] Completed 204 No Content in 42ms (ActiveRecord: 6.7ms | Allocations: 7512)

doc: setup instagram inbox

How it works? for automation rules and actions works

Telegram Channel (Prod setup)

Create documentation for setting up a telegram channel in production.

doc: Update ruby versions across different environment setup pages

Hi, it is observed that ruby versions in contributing-guide are not consistent, matching with the version (3.0.2) Chatwoot is currently running on.

MAC OS

https://www.chatwoot.com/docs/contributing-guide/environment-setup/mac-os

Ubuntu OS

https://www.chatwoot.com/docs/contributing-guide/environment-setup/ubuntu

Same goes for Windows.

Thanks and Chatwoot is awesome.

Improve doc for Identity validation section

Hi :)

In your documentation, you describe how to add identifier_hash (https://www.chatwoot.com/docs/website-sdk#identity-validation) and how to generate it (https://www.chatwoot.com/docs/website-sdk/identity-validation). But not clear how it works. Maybe I missing something but should be a possibility to disable unsigned requests (without identifier_hash).

I added identifier_hash, but don't understand how it works and protects my setup.

If it possible could you extend a bit your documentation with an explanation of this moment? Thanks!

doc: Update required fields for Create Contact API

When I was trying to create a contact through the API, I was getting Bad request response. The API docs said it would give me appropriate error messages but it didn't unfortunately. Anyway, I found out it was because I was not sending the name field in request body. It simply doesn't make sense to create a contact without a name 😅 Even though I still feel it's better to update the docs.

https://www.chatwoot.com/developers/api/#operation/contactCreate

Markdown code highlighting breaks in Docker Setup

In the above image, the bash code highlighting breaks. And also no need to add the '$' sign before each line of command (If we copy the command block, it will include the dollar).

Add docs for upgrading self hosted version

Is your enhancement request related to a problem? Please describe.
Hard to know if we're going the right way about upgrading our instance.

Describe the solution you'd like
Some documentation similar to what Metabase has:
https://www.metabase.com/docs/latest/operations-guide/upgrading-metabase.html

Describe alternatives you've considered
We've gone about it just hoping we wouldn't break anything.

Additional context
No further details.

doc: Ongoing and one-off campaigns

https://www.chatwoot.com/docs/product/features/campaigns

Add doc for automation rules, example and result.

chatwoot/chatwoot#3195

Documentation for this epic

doc: Hosting on railway.app

Is your feature request related to a problem? Please describe.
I don't know how to host this on railway.app

Describe the solution you'd like
Write guide how to host chatwoot on service https://railway.app
railway supports database plugins, so both database and chatwoot can be hosted on one plane

Describe alternatives you've considered
Write a guide for https://fly.io or https://replit.com

Additional context
Add any other context or screenshots about the feature request here.

doc: Document fair use policy and enterprise edition implications

• Add docs describing fair use policies for the community edition
• Document enterprise edition usage restrictions

ref: https://discord.com/channels/897869226579222540/897872508034879490/922444480844550174

What is the Callback URL which FB has to hit in order to integrate FB inbox

Describe the bug

There is no documentation on the webhook callback URL that has to be provided to FB in order for the integration to work.
For example: app.chatwoot.com/{path_name_required}

To Reproduce

https://ibb.co/NCkf6dK

Expected behavior

The doc should include the callback URL path

Screenshots

https://ibb.co/NCkf6dK
Browser logs

NA
Server logs

NA
Environment

Docker

Desktop (please complete the following information):

• OS: [e.g. iOS] MacOS
• Browser [e.g. chrome, safari] Chrome
• Version [e.g. 22] 56

Smartphone (please complete the following information):

• Device: [e.g. iPhone6] NA
• OS: [e.g. iOS8.1]. NA
• Browser [e.g. stock browser, safari] NA
• Version [e.g. 22] NA

Additional context

NA

doc: Keyboard shortcuts

• Add doc for keyboard shortcuts.

Please add a few details to README about Engineering details

Would like to know what languages this is being developed in. eg Frontend is in Vue 2.x, Backend in Ruby (?), using PostgreSQL db.

I saw https://www.chatwoot.com/docs/deployment/architecture, maybe there would be best to put the details for each. The current README link would become "Software & Deployment architecture".

It would also be beneficial to potential contributors.

Thanks!

Add documentation to upgrade ruby / pg in Linux VMs

The ruby upgrade or pg update process on Linux VMs are not documented. This creates a confusion.

More specificity on mandrill/inbound email routing setup

So, it took me a little while to realize that I needed to create a catchall route in mandrill: "*@example.com"

Might be useful to update the docs to specify that?

Thanks!

Add documentation for folders/segments

• Create a product documentation for segments and how it works.
• Create a product documentation for folders and how it works.

Provide in detail documentation on the ideal AWS hosting architecture + services for self hosted Chatwoot

Is your enhancement request related to a problem? Please describe.
I would love a tutorial on how and what different AWS services do I use and how do I connect them all for a self-hosted Chatwoot for internal user. Im sure the team would have hosted many instances on AWS but not documented it for public use.

Describe the solution you'd like
Documentation or tutorials.

Describe alternatives you've considered
Trying out self-hosting with glue tape like solutions.

Additional context
N/A

Add documentation for IMAP and SMTP configuration for email channel.

#2520

chore: Add style guide and storybook to docs

doc: Migration Guide to move existing Chatwoot installation to a new server

Is your feature request related to a problem? Please describe.
No.

Trying to debug the earlier issue, we've created a new server and wish to move our existing data.

Outside of moving the chatwoot_production database, what other data needs to be moved?

On moving that and restarting chatwoot, we are still getting the onboarding page. Although old data is there as we can login to the super_admin with previous credentials.

environment variables link is broken on caprover deployment page

https://www.chatwoot.com/docs/deployment/deploy-chatwoot-with-caprover

doc: Custom Attributes

chore: Create a documentation page for the cookies used by chatwoot

• chatwoot widget creates cw_conversation and _chatwoot_session cookies. Create a documentation page to detail why they are required.

Documentation for LINE channel in production and development.

Create documentation for setting up a line channel in production and development.

Add the pages_read_engagement advanced access in instagram doc

Permissions
The manage_pages permission has been deprecated and replaced with 4 new permissions:

pages_manage_ads
pages_manage_metadata
pages_read_engagement
pages_read_user_content

doc: CSAT feature

Add react-native-widget instructions

https://github.com/chatwoot/chatwoot-react-native-widget

doc: updating interactive messages through client APIs

Add documentation for Automation

• Add documentation for different automation we support.
• How it works.
• How can an admin enable automation.

doc: improve environment variable section

• sort env vars according to priority
• add pre-req section
• remove env vars no longer applicable

Mention if setting a particular env variable is required based on the deployment method used.

Add documentation around the formal vs informal choices in translation

For more context: chatwoot/chatwoot#2062

Add documentation on email settings under account settings

Problem
As of now, when a user has to configure inbound emails, there are some settings related to this under the account settings page. This is confusing and does not really say anything more about each of the settings.

Solution
Required more documentation on guiding a user to configure this.

doc: Mobile number in `setUser` method

https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-the-user-in-the-widget

doc: How to uninstall Chatwoot from linux vm

verify and add documentation on how to remove chatwoot from a Linux VM to the page
https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm

it's much easier to purge the VM and spin up a new server instead. But in cases where you can't do that follow the steps.

---

• make sure to back up data from postgres / storage if required
• stop the chatwoot server : systemctl stop chatwoot.target
• ref https://github.com/chatwoot/chatwoot/blob/develop/deployment/setup_20.04.sh and uninstall the dependencies that you don't require [ postgres, redis , nginx ]
• remove chatwoot directory

sudo -i -u chatwoot 
rm -rf chatwoot

Minor typo in documentation

"Chatwoot has been made available as a one-click app in Chatwoot"
It should read:
"Chatwoot has been made available as a one-click app in Caprover"

On page:
https://www.chatwoot.com/docs/self-hosted/deployment/caprover
First paragraph.

doc: Updated assignment rules

Please add information about how the function is used, this is necessary to fill out an application on Facebook. If possible, then also a screencast for the application.

Please add information about how the function is used, this is necessary to fill out an application on Facebook. If possible, then also a screencast for the application. Thanks.

Tell us how your use of instagram_basic follows established usage guidelines
Tell us how your use of instagram_manage_messages follows established usage guidelines
Tell us how your use of pages_manage_metadata follows established usage guidelines
Tell us how your use of pages_show_list follows established usage guidelines
Tell us how your use of pages_messaging follows established usage guidelines

Docs required

Notes: Write docs for both agent and admin

Self-hosted

• Deploy on AWS (@vishnu-narayanan)
• Deploy on Google Cloud (@vishnu-narayanan)
• Deploy on Azure (@vishnu-narayanan)
• Deploy on DigitalOcean (@vishnu-narayanan)
• Deploy using Cloudron (@vishnu-narayanan)

Integration

• Slack integration user guide (@tejaswinichile)

Features

• Facebook connection expired, how to reconnect? (@tejaswinichile)
• Configuring interactive messages in dialogflow (@sojan-official)
• CSAT (@muhsin-k)
• Commandbar (@fayazara)
• Keyboard Shortcuts (@iamsivin)
• User mentions (@pranavrajs)
• Teams (Create a team, assign a team, conversation view for teams) (@nithindavid)
• Contacts (Add contacts, Filter Contacts, Search Contacts, Import Contacts) (@fayazara)
• Contact Notes (Add, delete notes) (@nithindavid)
• Campaigns - One off (@muhsin-k)
• Reports (@fayazara)

Channels

• Email Channel : forwarding email part (@aswindevps)
• Telegram Channel (Prod setup) (@aswindevps)
• Line Channel (Prod setup, Dev setup) (@aswindevps)
• 360 Dialog (@sojan-official)