+
+## Join Our Contributors
+
+Ready to make your mark on Chatwoot? Here's how to get started:
+
+### Quick Start
+
+1. **Star the Repository**: [Star Chatwoot on GitHub](https://github.com/chatwoot/chatwoot)
+2. **Join Discord**: [Join our Discord community](https://discord.com/invite/cJXdrwS)
+3. **Pick an Issue**: Find a [good first issue](https://github.com/chatwoot/chatwoot/labels/good%20first%20issue)
+4. **Make Your First Contribution**: Follow our [contribution guide](/contributing/introduction)
+
+### Stay Connected
+
+- **GitHub**: [github.com/chatwoot/chatwoot](https://github.com/chatwoot/chatwoot)
+- **Discord**: [discord.com/invite/cJXdrwS](https://discord.com/invite/cJXdrwS)
+- **Twitter**: [@chatwootapp](https://twitter.com/chatwootapp)
+- **LinkedIn**: [Chatwoot Company Page](https://www.linkedin.com/company/chatwoot)
+
+---
+
+Every contribution, no matter how small, makes Chatwoot better for thousands of users worldwide. Thank you for considering joining our contributor community! 🙏
\ No newline at end of file
diff --git a/developer-docs/contributing/cypress.mdx b/developer-docs/contributing/cypress.mdx
new file mode 100644
index 000000000..f4fbacb80
--- /dev/null
+++ b/developer-docs/contributing/cypress.mdx
@@ -0,0 +1,127 @@
+---
+title: End-to-end testing with Cypress
+description: Guide to running Cypress end-to-end tests for Chatwoot
+sidebarTitle: Cypress Testing
+---
+
+# End-to-end testing with Cypress
+
+Chatwoot uses [Cypress](https://www.cypress.io/) for end-to-end testing. Use the following steps to run the tests on your local machine.
+
+## Prepare the Test Server
+
+Choose any of the given methods to run your Chatwoot test server.
+
+
+
+## Step 2: Enable Windows Subsystem for Linux
+
+Next you have to enable the Windows Subsystem for Linux. Open the "Control Panel" and go to "Programs and Features". Click on the link on the left "Turn Windows features on or off". Look for the "Windows Subsystem for Linux" option and select the checkbox next to it.
+
+
+
+You'll also need to enable "Virtual Machine Platform" for WSL2. Make sure both checkboxes are selected:
+- ✅ Windows Subsystem for Linux
+- ✅ Virtual Machine Platform
+
+After enabling these features, restart your computer.
+
+## Step 3: Install WSL2 and Ubuntu
+
+### Option 1: Using Microsoft Store (Recommended)
+
+1. **Open Microsoft Store** and search for "Ubuntu"
+2. **Install Ubuntu 22.04 LTS** (or latest LTS version)
+3. **Launch Ubuntu** from the Start Menu
+
+### Option 2: Using Command Line
+
+Open PowerShell as Administrator and run:
+
+```powershell
+# Install WSL2 with Ubuntu
+wsl --install -d Ubuntu-22.04
+
+# Set WSL2 as default version
+wsl --set-default-version 2
+```
+
+## Step 4: Initial Ubuntu Setup
+
+When you first launch Ubuntu, you'll be prompted to create a user account:
+
+```bash
+# Create a username and password when prompted
+# This will be your Linux user account
+```
+
+Update the system packages:
+
+```bash
+sudo apt update && sudo apt upgrade -y
+```
+
+## Step 5: Install Core Dependencies
+
+You need core Linux dependencies installed in order to install Ruby and other tools.
+
+```bash
+sudo apt-get update
+sudo apt-get install -y git-core curl zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev
+```
+
+## Installing RVM & Ruby
+
+Install additional dependencies required for RVM:
+
+```bash
+sudo apt-get install -y libgdbm-dev libncurses5-dev automake libtool bison libffi-dev
+```
+
+Install RVM & Ruby version 3.2.2:
+
+```bash
+# Add RVM GPG keys
+gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
+
+# Install RVM
+curl -sSL https://get.rvm.io | bash -s stable
+
+# Load RVM into current session
+source ~/.rvm/scripts/rvm
+
+# Install Ruby 3.2.2
+rvm install 3.2.2
+rvm use 3.2.2 --default
+
+# Verify installation
+ruby -v
+```
+
+## Install Node.js
+
+Chatwoot requires Node.js version 20. Install Node.js from NodeSource using the following commands:
+
+```bash
+curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+Verify Node.js installation:
+
+```bash
+node --version
+# Should output: v20.x.x
+```
+
+## Install pnpm
+
+We use `pnpm` as the package manager for better performance:
+
+```bash
+# Install pnpm globally
+npm install -g pnpm
+
+# Verify installation
+pnpm --version
+```
+
+## Install PostgreSQL
+
+The database used in Chatwoot is PostgreSQL. Use the following commands to install PostgreSQL:
+
+```bash
+sudo apt install -y postgresql postgresql-contrib
+```
+
+The installation procedure created a user account called postgres that is associated with the default Postgres role. In order to use PostgreSQL, you can log into that account:
+
+```bash
+sudo -u postgres psql
+```
+
+Install `libpq-dev` dependencies for Ubuntu:
+
+```bash
+sudo apt-get install -y libpq-dev
+```
+
+Start PostgreSQL service:
+
+```bash
+sudo service postgresql start
+```
+
+Configure PostgreSQL to start automatically:
+
+```bash
+echo 'sudo service postgresql start' >> ~/.bashrc
+```
+
+Create a database user:
+
+```bash
+# Switch to postgres user and create a superuser
+sudo -u postgres createuser --superuser $USER
+
+# Set password for your user
+sudo -u postgres psql -c "ALTER USER $USER PASSWORD 'password';"
+```
+
+## Install Redis Server
+
+Chatwoot uses Redis server for agent assignments and reporting. To install `redis-server`:
+
+```bash
+sudo apt-get install -y redis-server
+```
+
+Start Redis service:
+
+```bash
+sudo service redis-server start
+```
+
+Configure Redis to start automatically:
+
+```bash
+echo 'sudo service redis-server start' >> ~/.bashrc
+```
+
+Enable Redis to start on system boot:
+
+```bash
+sudo systemctl enable redis-server.service
+```
+
+## Install ImageMagick
+
+Chatwoot uses ImageMagick for image processing:
+
+```bash
+sudo apt-get install -y imagemagick libmagickwand-dev
+```
+
+## Configure Git
+
+Set up Git with your information:
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+```
+
+## Windows-Specific Configuration
+
+### Install VS Code with WSL Extension
+
+1. **Install Visual Studio Code** on Windows from [https://code.visualstudio.com/](https://code.visualstudio.com/)
+2. **Install Remote - WSL extension** from the Extensions marketplace
+3. **Open your project in WSL** by running `code .` from your WSL terminal
+
+### Configure File Permissions
+
+WSL2 may have file permission issues. Fix them:
+
+```bash
+# Add to ~/.bashrc for better file permissions
+echo 'umask 022' >> ~/.bashrc
+
+# Configure Git to ignore file mode changes
+git config --global core.filemode false
+```
+
+## Environment Verification
+
+Verify all installations are working correctly:
+
+```bash
+# Check all versions
+ruby --version # Should be 3.2.2
+node --version # Should be v20.x.x
+pnpm --version # Should show pnpm version
+psql --version # Should show PostgreSQL version
+redis-cli ping # Should output: PONG
+convert --version # Should show ImageMagick version
+git --version # Should show Git version
+```
+
+## Troubleshooting Common Issues
+
++Running your application on a Kubernetes cluster lets you deploy, scale and monitor the application reliably. +
Creating a cluster is a one-time process. From here you can add other open source tools or multiple instances of Chatwoot in the same cluster. + + + + + +Any application you deploy in your cluster will be accessible via a free **restack domain**.
Contact the Restack team via chat to set a custom domain for your Chatwoot instances. + +## Deploy Chatwoot on Restack + +1. Click *Add application* from the Cluster description or go to the Applications tab in the left hand side navigation. +2. Click *Chatwoot*. + + + +3. Select the cluster you have already provisioned. +4. Click *Add application*. + +## Start using Chatwoot + +Chatwoot will be deployed on your cluster and you can access it using the link under the *URL* tab. + + + +You can also check the workloads and volumes that are deployed within Chatwoot. + + + +## Deploy multiple instances of Chatwoot + +Restack makes it easier to deploy multiple instances of Chatwoot on the same or multiple clusters.
So you can test the latest version before upgrading or have a dedicated instance for development and for production. \ No newline at end of file diff --git a/developer-docs/self-hosted/configuration/environment-variables.mdx b/developer-docs/self-hosted/configuration/environment-variables.mdx index 4515edd87..01b9f10ab 100644 --- a/developer-docs/self-hosted/configuration/environment-variables.mdx +++ b/developer-docs/self-hosted/configuration/environment-variables.mdx @@ -4,745 +4,261 @@ description: Complete reference for Chatwoot environment variables and configura sidebarTitle: Environment Variables --- -# Environment Variables Reference +## The .env File -Chatwoot uses environment variables for configuration. This guide provides a comprehensive reference for all available environment variables and their usage. +We use the `dotenv-rails` gem to manage the environment variables. There is a file called `env.example` in the root directory of this project with all the environment variables set to empty values. You can set the correct values as per the following options. Once you set the values, you should rename the file to `.env` before you start the server. -## Core Application Settings +## Configure frontend URL (domain) -### Basic Configuration +Provide your chatwoot domain as frontend URL. + +```bash +FRONTEND_URL='https://your-chatwoot-domain.tld' +``` + +## Rails production variables + +For production deployment, you have to set the following variables ```bash -# Rails Environment RAILS_ENV=production - -# Node Environment -NODE_ENV=production - -# Frontend URL (required) -FRONTEND_URL=https://chatwoot.yourdomain.com - -# Force SSL (recommended for production) -FORCE_SSL=true - -# Secret Key Base (auto-generated during installation) -SECRET_KEY_BASE=your-secret-key-base - -# Rails Log Level -RAILS_LOG_LEVEL=info - -# Rails Max Threads -RAILS_MAX_THREADS=5 - -# Web Concurrency (Puma workers) -WEB_CONCURRENCY=2 +SECRET_KEY_BASE=replace_with_your_own_secret_string ``` -### Application Behavior - -```bash -# Enable/disable account signup -ENABLE_ACCOUNT_SIGNUP=false - -# Auto-assign conversations to online agents -AUTO_ASSIGN_CONVERSATIONS=true - -# Enable conversation continuity (link conversations across sessions) -CONVERSATION_CONTINUITY=true - -# Maximum file upload size (in MB) -MAXIMUM_FILE_UPLOAD_SIZE=40 - -# Enable IP-based rate limiting -ENABLE_IP_RATE_LIMIT=true - -# Rate limit per IP (requests per minute) -IP_RATE_LIMIT=100 -``` - -## Database Configuration - -### PostgreSQL - -```bash -# Database URL (primary configuration method) -DATABASE_URL=postgresql://username:password@hostname:port/database_name - -# Alternative: Individual components -POSTGRES_HOST=localhost -POSTGRES_PORT=5432 -POSTGRES_USERNAME=chatwoot -POSTGRES_PASSWORD=your-password -POSTGRES_DATABASE=chatwoot_production - -# Database pool size -DATABASE_POOL_SIZE=5 - -# Database timeout (seconds) -DATABASE_TIMEOUT=5000 - -# Enable prepared statements -DATABASE_PREPARED_STATEMENTS=true -``` - -### Database SSL Configuration - -```bash -# SSL Mode (disable, allow, prefer, require, verify-ca, verify-full) -DATABASE_SSL_MODE=require - -# SSL Certificate paths (for verify-ca and verify-full modes) -DATABASE_SSL_CERT=/path/to/client-cert.pem -DATABASE_SSL_KEY=/path/to/client-key.pem -DATABASE_SSL_ROOT_CERT=/path/to/ca-cert.pem -``` - -## Redis Configuration - -### Basic Redis Settings - -```bash -# Redis URL (primary configuration method) -REDIS_URL=redis://localhost:6379/0 - -# Alternative: Individual components -REDIS_HOST=localhost -REDIS_PORT=6379 -REDIS_DB=0 -REDIS_PASSWORD=your-redis-password - -# Redis connection pool size -REDIS_POOL_SIZE=5 - -# Redis timeout (seconds) -REDIS_TIMEOUT=1 -``` - -### Redis SSL Configuration - -```bash -# Enable SSL for Redis -REDIS_SSL=true - -# Redis SSL certificate verification -REDIS_SSL_VERIFY=true - -# Redis SSL certificate paths -REDIS_SSL_CERT=/path/to/redis-client.crt -REDIS_SSL_KEY=/path/to/redis-client.key -REDIS_SSL_CA=/path/to/redis-ca.crt -``` - -### Sidekiq Configuration - -```bash -# Sidekiq concurrency (number of worker threads) -SIDEKIQ_CONCURRENCY=10 - -# Sidekiq Redis namespace -SIDEKIQ_REDIS_NAMESPACE=chatwoot_sidekiq - -# Sidekiq log level -SIDEKIQ_LOG_LEVEL=info - -# Enable Sidekiq web UI -SIDEKIQ_WEB_UI=true - -# Sidekiq web UI username/password -SIDEKIQ_WEB_USERNAME=admin -SIDEKIQ_WEB_PASSWORD=your-password -``` - -## Email Configuration - -### SMTP Settings - -```bash -# Sender email address -MAILER_SENDER_EMAIL=noreply@yourdomain.com - -# SMTP server configuration -SMTP_ADDRESS=smtp.gmail.com -SMTP_PORT=587 -SMTP_USERNAME=your-email@gmail.com -SMTP_PASSWORD=your-app-password -SMTP_AUTHENTICATION=plain -SMTP_ENABLE_STARTTLS_AUTO=true -SMTP_OPENSSL_VERIFY_MODE=peer - -# SMTP domain (for HELO command) -SMTP_DOMAIN=yourdomain.com - -# Force TLS -SMTP_TLS=true -``` - -### Email Provider Examples - -
+
+- `Installation Identifier`: This is the unique identifier used to identify an installation and associate a license with that installation.
+- `Manage Plan`: Redirects to the Stripe portal where you can purchase the appropriate number of licenses.
+- `Refresh`: Refresh button next to plan details helps to sync your server with the license server in cases where a license purchase is not yet reflected in the system.
+- `Feature Config`: You can configure settings for enterprise features like `Whitelabeling` by clicking on the gear icon next to the feature name under feature settings.
+- `Support Options`: Based on your plan, applicable support options will be displayed.
+
+## FAQ
+
+### Do you have Instance level plans?
+
+No, at the moment Chatwoot only offers per agent per month plans. If you are looking at a large number of agents, you can reach out to us at `sales@chatwoot.com` for custom plans.
+
+### Transferring licenses?
+
+If you are moving the installation between servers and doing so with a database backup, the original installation identifier is retained, and you don't need to activate the license again.
+
+If for some reason you decide to delete an existing licensed installation and want to do a new installation, please reach out to Chatwoot support, and our team can help you transfer the license to your new installation.
\ No newline at end of file
diff --git a/developer-docs/self-hosted/others/faq.mdx b/developer-docs/self-hosted/others/faq.mdx
new file mode 100644
index 000000000..41c4db823
--- /dev/null
+++ b/developer-docs/self-hosted/others/faq.mdx
@@ -0,0 +1,144 @@
+---
+title: 'Frequently Asked Questions'
+description: 'Common questions and answers about self-hosted Chatwoot installation, support, and best practices'
+---
+
+This document is a place to search for frequently asked questions in the Chatwoot community about the processes, support and best practices.
+
+## How to get support?
+
+The chatwoot team provides support over the following channels. Please choose the appropriate medium based on the type of your query and resolution expectations.
+
+**Business Enquiries**: Questions related to the pricing and commercial partnerships.
+
+**Developer Support**: Questions related to Self-hosting Chatwoot, Extending/Contributing to Chatwoot and leveraging Chatwoot APIs
+
+**Product Support**: Bug Reports, Feature Requests and Support related to Chatwoot Cloud Version.
+
+**Premium Support**: Available for customers having a commerical contract with Chatwoot or subscribers of a paid plan. This includes both Chatwoot Cloud Customers and Self-hosted Customers.
+
+| Channel Type | Response Expectations | Query Types |
+|----------|-------------|------|
+| Chat Widget | Real-time responses based on online agent availability. Cloud customers can use the in-product Support option for priority resolutions. Email follow-ups in 2 Business Days or per SLA | Business Enquiries, Premium Support | +| [Email](mailto:hello@chatwoot.com) | Responses in 2 Business Days or as per SLA | Business Enquiries, Premium Support | +| [Github](https://github.com/chatwoot/chatwoot) | Responses in 5 Business Days or per SLA | Developer Support, Product Support, Premium Support | +| [Discord](https://discord.gg/cJXdrwS) | Community Support Based on availability. Contributors support based on availability | Developer Support, Product Support, Premium Support | + +
+ examples: clones of Chatwoot Cloud (SaaS), Rebranding Services, etc + +## How to debug SMTP Email errors in Chatwoot? + +Suppose you run into issues with the agent mailers ( account confirmation, password reset, etc.) and email Channels in Chatwoot. Then, you can go through the following steps to debug your SMTP configurations. + +### Step 1: Check your SMTP configuration + +Ensure that the intended config matches what is configured in the system. If there are discrepancies, you should double-check your environment variables. + +#### Viewing the SMTP config for the Installation + +Run the following command from the [Rails Console](/self-hosted/configuration/monitoring/super-admin-console/). + +```ruby +ActionMailer::Base.smtp_settings +``` + +#### Viewing the SMTP config for an Inbox + +Run the following command from the [Rails Console](/self-hosted/configuration/monitoring/super-admin-console/). + +```ruby +# replace `inbox_id` with your Inbox Id +Inbox.find(inbox_id).channel +``` + +### Step 2: Validate your SMTP config by sending an Email + +If you find the config is as intended, Try sending an email from the Rails Console using your config. + +Run the following script from the [Rails Console](/self-hosted/configuration/monitoring/super-admin-console/). + +```ruby +# Fill values for appropriate settings +# Remove the keys which aren't relevant to your use case +smtp_settings = { + address: '', + port: '', + user_name: '', + password: '', + domain: '', + tls: '', + enable_starttls_auto: '', + openssl_verify_mode: '', + authentication: '', +} + +mailer = ActionMailer::Base.new +# check settings: +mailer.delivery_method = :smtp +mailer.smtp_settings = smtp_settings + +# replace with your values for the mail +mailer.mail(from: 'sender@example.com', to: 'recipient@example.com', subject: 'test', body: "Hello, you've got mail!").deliver +``` + +If the configuration is correct, You should receive the email in the recipient's Inbox. In other cases, Fix the config as per the returned error and reconfigure the values in Chatwoot Environment variables with the correct values. + +
+
+### Go to the App Review Section
+
+Go to the Instagram product and click on "Go to App Review".
+
+
+
+### Confirm the Documentation
+
+Click on "Continue" to confirm the documentation.
+
+
+
+### Select the Permissions
+
+Select the permissions `instagram_business_basic`, `instagram_business_manage_messages`, and `human_agent` and click on "Continue to App Review".
+
+
+
+### Configure App Review Requests
+
+After clicking on "Continue to App Review", you will be redirected to the App Review requests page.
+
+
+
+Click on the "Edit" button to edit the review request.
+
+
+
+### Business Account
+
+You **must** have a Business Account to be able to request these permissions. Please ensure you have a Business Account before requesting the permissions. Submit Business Account details.
+
+
+
+### Data Handling
+
+Please answer all the questions in the Data Handling section and include all the pre-processing steps you perform on the data.
+
+
+
+
+
+### Complete App Settings
+
+Make sure you have an app icon, privacy policy URL, and app category configured. You can update these via the Basic Settings.
+
+
+
+### Review Instructions
+
+Provide the review instructions to the reviewer for the App Review. Essentially, you need to provide the steps to log in to the Dashboard and send a message to the connected Instagram account.
+
+
+
+You can use the following template to provide the review instructions:
+
+1. Go to `[DASHBOARD_URL]`.
+2. Log in using the following credentials. Ensure the credentials are entered exactly as provided, without leading or trailing spaces.
+ Email: `[EMAIL]`
+ Password: `[PASSWORD]`
+3. Once logged in, you will see the Dashboard with an empty chat screen. On the leftmost sidebar, you will find the Settings (gear icon).
+4. Click on Settings > Inboxes > Add Inbox. You can also access the settings page at: `[DASHBOARD_URL]/app/accounts/[ACCOUNT_ID]/settings/inboxes/new`.
+5. On the first step, "Choose a channel," select Instagram. This will take you to the second step, where you will find the "Continue with Instagram" button.
+6. Once the setup is complete, you can send a message to the connected Instagram account.
+7. The message should appear on the Dashboard at `[DASHBOARD_URL]/app/accounts/[ACCOUNT_ID]/dashboard`.
+
+
+
+## Permissions
+
+It is time to request the permissions. Please click on each permission and fill in the details. Once you are done, click on "Submit for Review". Below are sample permission requests you can use as a reference.
+
+
+
+## `instagram_business_basic`
+
+### Why You Are Requesting This Permission
+
+[BRAND_NAME] is a customer support platform that allows businesses to manage conversations across multiple messaging platforms — including Instagram, WhatsApp, Facebook, and more — through a unified inbox.
+
+This permission is used to:
+
+- Retrieve basic metadata (username, user ID, and profile picture) of connected Instagram Business accounts during onboarding.
+- Display sender information (username and ID) when customers message the business through Instagram.
+
+This metadata is essential for correct routing of messages to the appropriate agent, identification of the agent handling the conversation, and accurate profile display in the chat UI, ensuring a seamless customer experience.
+
+- **App URL:** [DASHBOARD_URL]
+- **Test Account:**
+ - Email: [EMAIL]
+ - Password: [PASSWORD]
+
+---
+
+### Screencast Walkthrough
+
+Include a screencast demonstrating the following steps:
+
+1. Log in to the app using the provided credentials.
+2. Navigate to the Dashboard.
+3. Add a new inbox by selecting Instagram as the channel.
+4. Authenticate an Instagram Business account.
+5. Show that the platform uses the `instagram_business_basic` permission to display:
+ - Instagram username
+ - User ID
+ - Profile picture
+6. Simulate receiving a message and show how this metadata appears in the inbox.
+
+---
+
+## `instagram_business_manage_messages`
+
+### Why You Are Requesting This Permission
+
+[BRAND_NAME] is a customer support platform that allows businesses to manage conversations across multiple messaging platforms — including Instagram, WhatsApp, Facebook, and more — through a unified inbox.
+
+This permission allows the platform to manage and respond to Instagram messages on behalf of the connected Instagram Business account.
+
+It is used to:
+
+- Receive messages via the Instagram webhook.
+- Display conversations in the agent inbox.
+- Allow agents to reply from within the platform.
+- Keep conversations synced in real time.
+
+The webhook setup works by configuring a URL endpoint on the platform to receive incoming messages from Instagram. When a message is sent to the connected Instagram Business account, it triggers a webhook event that delivers the message to the specified endpoint. The backend processes this message, stores it in the database, and updates the agent's inbox in real time.
+
+Without this permission, users would not be able to communicate with their Instagram audience via the support platform.
+
+- **App URL:** [DASHBOARD_URL]
+- **Test Account:**
+ - Email: [EMAIL]
+ - Password: [PASSWORD]
+
+---
+
+### Screencast Walkthrough
+
+Include a screencast demonstrating the following steps:
+
+1. Log in to the Dashboard.
+2. Connect an Instagram Business account as described in the previous section.
+3. From another Instagram user account, send a direct message to the connected business.
+4. Show that the message appears in the inbox UI.
+5. Reply from the inbox.
+6. Switch back to Instagram to show that the user received the reply.
+7. Demonstrate real-time syncing.
+
+---
+
+## `human_agent`
+
+### Why You Are Requesting This Permission
+
+[BRAND_NAME] is a customer support platform that allows businesses to manage conversations across multiple messaging platforms — including Instagram, WhatsApp, Facebook, and more — through a unified inbox.
+
+We are requesting the Human Agent permission to allow support agents to follow up on customer conversations beyond the 24-hour window, especially when customers reach out after business hours or over the weekend.
+
+Example use case:
+
+- A customer sends a message Friday night.
+- The business is closed on weekends.
+- On Monday morning, the agent cannot reply because the 24-hour window has expired.
+- With the Human Agent tag, the agent can now follow up on Monday morning and resolve the query.
+
+This enhances customer experience and ensures critical messages are not left unresolved due to timing limitations.
+
+This permission is essential to allow human agents to continue conversations in a natural, respectful, and supportive way without forcing customers to message again just to reopen the window.
+
+- **App URL:** [DASHBOARD_URL]
+- **Test Account:**
+ - Email: [EMAIL]
+ - Password: [PASSWORD]
+
+---
+
+### Screencast Walkthrough
+
+Include a screencast demonstrating the following steps:
+
+1. Log in to the platform.
+2. Open an existing Instagram conversation that is **older than 24 hours**.
+3. Attempt to respond to the message and explain how current Meta policy restricts the reply.
+4. Explain why a response is still needed — for example, the support agent was unavailable during a weekend or the issue required escalation.
+5. Describe how the `human_agent` tag will be used to allow the response within the extended 7-day window.
+
+## Notes
+
+- Do not include Instagram account credentials.
+- Only share test Dashboard credentials (non-super admin access recommended).
+- Ensure your screencast clearly shows the platform UI and relevant workflows.
+- Keep your permission usage aligned with Meta's policy for message tags and user privacy.
+- Speak aloud or add captions in your video for reviewer clarity.
+- Video should be as detailed as possible.
+
+Hi {{user.available_name}},
+Time to save the world. A new conversation has been assigned to you
+Click here to get cracking.
+``` + +### 2. Conversation Creation + +```html +Hi {{user.available_name}}
+ +Time to save the world. A new conversation has been created in {{ inbox.name }}
++Click here to get cracking. +
+``` + +We use [Liquid templating engine](https://shopify.github.io/liquid/) internally, so all valid operators can be used here. \ No newline at end of file diff --git a/developer-docs/self-hosted/runbook/enable-ip-logging.mdx b/developer-docs/self-hosted/runbook/enable-ip-logging.mdx new file mode 100644 index 000000000..3377b0618 --- /dev/null +++ b/developer-docs/self-hosted/runbook/enable-ip-logging.mdx @@ -0,0 +1,42 @@ +--- +title: How to enable IP identification in Chatwoot? +description: Guide to enabling IP address geocoding and location identification in Chatwoot +sidebarTitle: Enable IP Logging +--- + +Chatwoot lets you identify the user's location by geocoding the IP address. For IP Address geocoding, we support MaxmindDB services. This lookup provides methods for geocoding IP addresses without calling a remote API every time. You can follow the steps below to set up your self-hosted instance with the geocoding. + +## Step 1: Create MaxmindDB Account + +Create an account at [MaxmindDB](https://www.maxmind.com) and create an API key. + +## Step 2: Add Environment Variables + +Add the following environment variables. + +```bash +IP_LOOKUP_API_KEY=your-api-key +``` + +With this step, Chatwoot would automatically download the [MaxmindDB downloadable databases](https://dev.maxmind.com/geoip/geoip2/downloadable/) and cache it locally. + +## Step 3: Enable IP Lookup + +Enable IP Lookup on your account. You can do this in two ways. + +### Method 1: Via Superadmin Console UI + +Log into the super admin and select accounts. Select your account, click edit, and toggle the `ip_lookup` feature. + +### Method 2: Via Rails Console + +```bash +RAILS_ENV=production bundle exec rails console +``` + +```rb +account_id = 1 // Please fill your account id instead of 1 +account = Account.find(account_id) +account.enable_features('ip_lookup') +account.save! +``` \ No newline at end of file diff --git a/developer-docs/self-hosted/runbook/migrate-chatwoot-database.mdx b/developer-docs/self-hosted/runbook/migrate-chatwoot-database.mdx new file mode 100644 index 000000000..5355f5a8c --- /dev/null +++ b/developer-docs/self-hosted/runbook/migrate-chatwoot-database.mdx @@ -0,0 +1,76 @@ +--- +title: "How to migrate Chatwoot database?" +description: "Learn how to migrate your Chatwoot database from bundled PostgreSQL to managed database services like AWS RDS" +--- + +## Chatwoot database migration + +Follow along If you started out with a bundled install of postgres, redis and chatwoot in a single instance +and now wants to migrate to managed database service. + +In this guide, we assume you want to migrate to AWS RDS. This guide should be equally applicable to any other +managed database service or even migrating data between different Chatwoot installations. + +### Step 1: Stop Chatwoot service + +Stop Chatwoot service to stop database activity. + +```bash +sudo systemctl stop chatwoot.target +``` + +### Step 2: Back up the database + +Back up the database using `pg_dump` tool. + +```bash +pg_dump -Fc --no-acl --no-owner -U postgres chatwoot_production > /tmp/cw.dump +``` + +### Step 3: Create RDS instance + +Create an RDS Postgres instance in your AWS account. Refer to the [AWS documentation](https://aws.amazon.com/getting-started/hands-on/create-connect-postgresql-db/). + +### Step 4: Verify connectivity + +Verify connectivity to the new RDS instance from your Chatwoot installation. + +```bash +psql -h