add intro documentation and user guide
This commit is contained in:
Tanmay Deep Sharma
@@ -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
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Gmail">
|
||||
```bash
|
||||
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
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="SendGrid">
|
||||
```bash
|
||||
SMTP_ADDRESS=smtp.sendgrid.net
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=apikey
|
||||
SMTP_PASSWORD=your-sendgrid-api-key
|
||||
SMTP_AUTHENTICATION=plain
|
||||
SMTP_ENABLE_STARTTLS_AUTO=true
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Mailgun">
|
||||
```bash
|
||||
SMTP_ADDRESS=smtp.mailgun.org
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=postmaster@mg.yourdomain.com
|
||||
SMTP_PASSWORD=your-mailgun-password
|
||||
SMTP_AUTHENTICATION=plain
|
||||
SMTP_ENABLE_STARTTLS_AUTO=true
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="AWS SES">
|
||||
```bash
|
||||
SMTP_ADDRESS=email-smtp.us-east-1.amazonaws.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=your-ses-username
|
||||
SMTP_PASSWORD=your-ses-password
|
||||
SMTP_AUTHENTICATION=plain
|
||||
SMTP_ENABLE_STARTTLS_AUTO=true
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Email Templates
|
||||
|
||||
```bash
|
||||
# Custom email template path
|
||||
CUSTOM_EMAIL_TEMPLATE_PATH=/path/to/custom/templates
|
||||
|
||||
# Email template language
|
||||
EMAIL_TEMPLATE_LANGUAGE=en
|
||||
|
||||
# Enable email tracking
|
||||
EMAIL_TRACKING_ENABLED=true
|
||||
|
||||
# Email delivery method (smtp, sendmail, test)
|
||||
EMAIL_DELIVERY_METHOD=smtp
|
||||
```
|
||||
|
||||
## File Storage Configuration
|
||||
|
||||
### Local Storage
|
||||
|
||||
```bash
|
||||
# Active storage service
|
||||
ACTIVE_STORAGE_SERVICE=local
|
||||
|
||||
# Local storage path
|
||||
LOCAL_STORAGE_PATH=/home/chatwoot/chatwoot/storage
|
||||
```
|
||||
|
||||
### Amazon S3
|
||||
|
||||
```bash
|
||||
# Active storage service
|
||||
ACTIVE_STORAGE_SERVICE=amazon
|
||||
|
||||
# S3 configuration
|
||||
S3_BUCKET_NAME=your-chatwoot-bucket
|
||||
AWS_ACCESS_KEY_ID=your-access-key
|
||||
AWS_SECRET_ACCESS_KEY=your-secret-key
|
||||
AWS_REGION=us-east-1
|
||||
|
||||
# S3 endpoint (for S3-compatible services)
|
||||
S3_ENDPOINT=https://s3.amazonaws.com
|
||||
|
||||
# S3 force path style (for MinIO and other S3-compatible services)
|
||||
S3_FORCE_PATH_STYLE=false
|
||||
|
||||
# S3 public URL (for CDN)
|
||||
S3_PUBLIC_URL=https://cdn.yourdomain.com
|
||||
```
|
||||
|
||||
### Google Cloud Storage
|
||||
|
||||
```bash
|
||||
# Active storage service
|
||||
ACTIVE_STORAGE_SERVICE=google
|
||||
|
||||
# GCS configuration
|
||||
GCS_PROJECT=your-project-id
|
||||
GCS_BUCKET=your-chatwoot-bucket
|
||||
|
||||
# GCS credentials (JSON key file path)
|
||||
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
|
||||
|
||||
# GCS public URL (for CDN)
|
||||
GCS_PUBLIC_URL=https://cdn.yourdomain.com
|
||||
```
|
||||
|
||||
### Azure Blob Storage
|
||||
|
||||
```bash
|
||||
# Active storage service
|
||||
ACTIVE_STORAGE_SERVICE=azure
|
||||
|
||||
# Azure configuration
|
||||
AZURE_STORAGE_ACCOUNT_NAME=your-storage-account
|
||||
AZURE_STORAGE_ACCESS_KEY=your-access-key
|
||||
AZURE_STORAGE_CONTAINER=your-container-name
|
||||
|
||||
# Azure public URL (for CDN)
|
||||
AZURE_PUBLIC_URL=https://cdn.yourdomain.com
|
||||
```
|
||||
|
||||
## Third-Party Integrations
|
||||
|
||||
### Facebook
|
||||
|
||||
```bash
|
||||
# Facebook App ID and Secret
|
||||
FB_APP_ID=your-facebook-app-id
|
||||
FB_APP_SECRET=your-facebook-app-secret
|
||||
|
||||
# Facebook Verify Token
|
||||
FB_VERIFY_TOKEN=your-verify-token
|
||||
|
||||
# Facebook API Version
|
||||
FB_API_VERSION=v13.0
|
||||
```
|
||||
|
||||
### Twitter
|
||||
|
||||
```bash
|
||||
# Twitter API credentials
|
||||
TWITTER_APP_ID=your-twitter-app-id
|
||||
TWITTER_CONSUMER_KEY=your-consumer-key
|
||||
TWITTER_CONSUMER_SECRET=your-consumer-secret
|
||||
TWITTER_ENVIRONMENT=your-twitter-environment
|
||||
```
|
||||
|
||||
### Slack
|
||||
|
||||
```bash
|
||||
# Slack App credentials
|
||||
SLACK_CLIENT_ID=your-slack-client-id
|
||||
SLACK_CLIENT_SECRET=your-slack-client-secret
|
||||
```
|
||||
|
||||
### Google OAuth
|
||||
|
||||
```bash
|
||||
# Google OAuth credentials
|
||||
GOOGLE_OAUTH_CLIENT_ID=your-google-client-id
|
||||
GOOGLE_OAUTH_CLIENT_SECRET=your-google-client-secret
|
||||
```
|
||||
|
||||
### Microsoft OAuth
|
||||
|
||||
```bash
|
||||
# Microsoft OAuth credentials
|
||||
MICROSOFT_APP_ID=your-microsoft-app-id
|
||||
MICROSOFT_APP_SECRET=your-microsoft-app-secret
|
||||
```
|
||||
|
||||
## Push Notifications
|
||||
|
||||
### FCM (Firebase Cloud Messaging)
|
||||
|
||||
```bash
|
||||
# FCM Server Key
|
||||
FCM_SERVER_KEY=your-fcm-server-key
|
||||
|
||||
# FCM Project ID
|
||||
FCM_PROJECT_ID=your-firebase-project-id
|
||||
|
||||
# FCM credentials file
|
||||
GOOGLE_APPLICATION_CREDENTIALS=/path/to/firebase-service-account.json
|
||||
```
|
||||
|
||||
### Vapid Keys (Web Push)
|
||||
|
||||
```bash
|
||||
# Vapid public and private keys
|
||||
VAPID_PUBLIC_KEY=your-vapid-public-key
|
||||
VAPID_PRIVATE_KEY=your-vapid-private-key
|
||||
|
||||
# Vapid subject (email or URL)
|
||||
VAPID_SUBJECT=mailto:admin@yourdomain.com
|
||||
```
|
||||
|
||||
## Analytics and Monitoring
|
||||
|
||||
### Application Monitoring
|
||||
|
||||
```bash
|
||||
# Enable application metrics
|
||||
ENABLE_METRICS=true
|
||||
|
||||
# Metrics endpoint path
|
||||
METRICS_PATH=/metrics
|
||||
|
||||
# Prometheus exporter
|
||||
PROMETHEUS_EXPORTER=true
|
||||
PROMETHEUS_EXPORTER_PORT=9394
|
||||
|
||||
# New Relic
|
||||
NEW_RELIC_LICENSE_KEY=your-newrelic-license-key
|
||||
NEW_RELIC_APP_NAME=Chatwoot
|
||||
|
||||
# Sentry error tracking
|
||||
SENTRY_DSN=your-sentry-dsn
|
||||
```
|
||||
|
||||
### Google Analytics
|
||||
|
||||
```bash
|
||||
# Google Analytics tracking ID
|
||||
GOOGLE_ANALYTICS_ID=UA-XXXXXXXXX-X
|
||||
|
||||
# Google Tag Manager ID
|
||||
GOOGLE_TAG_MANAGER_ID=GTM-XXXXXXX
|
||||
```
|
||||
|
||||
### Hotjar
|
||||
|
||||
```bash
|
||||
# Hotjar site ID
|
||||
HOTJAR_SITE_ID=your-hotjar-site-id
|
||||
```
|
||||
|
||||
## Security Configuration
|
||||
|
||||
### Authentication
|
||||
|
||||
```bash
|
||||
# JWT secret key
|
||||
JWT_SECRET_KEY=your-jwt-secret-key
|
||||
|
||||
# Session timeout (in seconds)
|
||||
SESSION_TIMEOUT=86400
|
||||
|
||||
# Password minimum length
|
||||
PASSWORD_MIN_LENGTH=8
|
||||
|
||||
# Enable two-factor authentication
|
||||
ENABLE_2FA=true
|
||||
|
||||
# TOTP issuer name
|
||||
TOTP_ISSUER_NAME=Chatwoot
|
||||
```
|
||||
|
||||
### CORS Configuration
|
||||
|
||||
```bash
|
||||
# Allowed origins for CORS
|
||||
CORS_ORIGINS=https://yourdomain.com,https://www.yourdomain.com
|
||||
|
||||
# Enable CORS credentials
|
||||
CORS_CREDENTIALS=true
|
||||
```
|
||||
|
||||
### Content Security Policy
|
||||
|
||||
```bash
|
||||
# Enable CSP
|
||||
ENABLE_CSP=true
|
||||
|
||||
# CSP report URI
|
||||
CSP_REPORT_URI=/csp-report
|
||||
|
||||
# CSP directives
|
||||
CSP_DEFAULT_SRC='self'
|
||||
CSP_SCRIPT_SRC='self' 'unsafe-inline' 'unsafe-eval'
|
||||
CSP_STYLE_SRC='self' 'unsafe-inline'
|
||||
```
|
||||
|
||||
## Performance Configuration
|
||||
|
||||
### Caching
|
||||
|
||||
```bash
|
||||
# Enable caching
|
||||
ENABLE_CACHING=true
|
||||
|
||||
# Cache store (memory_store, redis_cache_store)
|
||||
CACHE_STORE=redis_cache_store
|
||||
|
||||
# Cache namespace
|
||||
CACHE_NAMESPACE=chatwoot_cache
|
||||
|
||||
# Cache TTL (seconds)
|
||||
CACHE_TTL=3600
|
||||
```
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
```bash
|
||||
# Enable rate limiting
|
||||
ENABLE_RATE_LIMITING=true
|
||||
|
||||
# Rate limit store (memory_store, redis_store)
|
||||
RATE_LIMIT_STORE=redis_store
|
||||
|
||||
# API rate limit (requests per minute)
|
||||
API_RATE_LIMIT=100
|
||||
|
||||
# Login rate limit (attempts per minute)
|
||||
LOGIN_RATE_LIMIT=5
|
||||
```
|
||||
|
||||
### Asset Configuration
|
||||
|
||||
```bash
|
||||
# Asset host (for CDN)
|
||||
ASSET_HOST=https://cdn.yourdomain.com
|
||||
|
||||
# Enable asset compression
|
||||
ENABLE_ASSET_COMPRESSION=true
|
||||
|
||||
# Asset cache TTL (seconds)
|
||||
ASSET_CACHE_TTL=31536000
|
||||
```
|
||||
|
||||
## Development and Testing
|
||||
|
||||
### Development Settings
|
||||
|
||||
```bash
|
||||
# Enable development features
|
||||
ENABLE_DEVELOPMENT_FEATURES=false
|
||||
|
||||
# Development email delivery
|
||||
DEVELOPMENT_EMAIL_DELIVERY=true
|
||||
|
||||
# Development file storage
|
||||
DEVELOPMENT_FILE_STORAGE=local
|
||||
|
||||
# Enable SQL logging
|
||||
ENABLE_SQL_LOGGING=false
|
||||
```
|
||||
|
||||
### Testing Configuration
|
||||
|
||||
```bash
|
||||
# Test database URL
|
||||
TEST_DATABASE_URL=postgresql://username:password@localhost/chatwoot_test
|
||||
|
||||
# Test Redis URL
|
||||
TEST_REDIS_URL=redis://localhost:6379/1
|
||||
|
||||
# Enable test coverage
|
||||
ENABLE_TEST_COVERAGE=true
|
||||
|
||||
# Test email delivery
|
||||
TEST_EMAIL_DELIVERY=test
|
||||
```
|
||||
|
||||
## Logging Configuration
|
||||
|
||||
### Log Settings
|
||||
|
||||
```bash
|
||||
# Log level (debug, info, warn, error, fatal)
|
||||
LOG_LEVEL=info
|
||||
|
||||
# Log format (text, json)
|
||||
LOG_FORMAT=text
|
||||
|
||||
# Log to stdout
|
||||
LOG_TO_STDOUT=true
|
||||
|
||||
# Log file path
|
||||
LOG_FILE_PATH=/var/log/chatwoot/chatwoot.log
|
||||
|
||||
# Log rotation
|
||||
LOG_ROTATION=daily
|
||||
LOG_RETENTION=30
|
||||
```
|
||||
|
||||
### Structured Logging
|
||||
|
||||
```bash
|
||||
# Enable structured logging
|
||||
ENABLE_STRUCTURED_LOGGING=true
|
||||
|
||||
# Log correlation ID
|
||||
LOG_CORRELATION_ID=true
|
||||
|
||||
# Log request ID
|
||||
LOG_REQUEST_ID=true
|
||||
|
||||
# Log user context
|
||||
LOG_USER_CONTEXT=true
|
||||
```
|
||||
|
||||
## Feature Flags
|
||||
|
||||
### Experimental Features
|
||||
|
||||
```bash
|
||||
# Enable experimental features
|
||||
ENABLE_EXPERIMENTAL_FEATURES=false
|
||||
|
||||
# Feature flags
|
||||
FEATURE_FLAG_CONVERSATION_CONTINUITY=true
|
||||
FEATURE_FLAG_AUTO_RESOLVE=false
|
||||
FEATURE_FLAG_CUSTOM_ATTRIBUTES=true
|
||||
FEATURE_FLAG_TEAM_MANAGEMENT=true
|
||||
```
|
||||
|
||||
## Webhook Configuration
|
||||
|
||||
```bash
|
||||
# Webhook URL for external integrations
|
||||
WEBHOOK_URL=https://your-webhook-endpoint.com/chatwoot
|
||||
|
||||
# Webhook secret for verification
|
||||
WEBHOOK_SECRET=your-webhook-secret
|
||||
|
||||
# Webhook timeout (seconds)
|
||||
WEBHOOK_TIMEOUT=30
|
||||
|
||||
# Webhook retry attempts
|
||||
WEBHOOK_RETRY_ATTEMPTS=3
|
||||
```
|
||||
|
||||
## Custom Branding
|
||||
|
||||
```bash
|
||||
# Custom brand name
|
||||
BRAND_NAME=Your Company
|
||||
|
||||
# Custom logo URL
|
||||
BRAND_LOGO_URL=https://yourdomain.com/logo.png
|
||||
|
||||
# Custom favicon URL
|
||||
BRAND_FAVICON_URL=https://yourdomain.com/favicon.ico
|
||||
|
||||
# Custom primary color
|
||||
BRAND_PRIMARY_COLOR=#1f93ff
|
||||
|
||||
# Custom secondary color
|
||||
BRAND_SECONDARY_COLOR=#f0f0f0
|
||||
```
|
||||
|
||||
## Environment-Specific Examples
|
||||
|
||||
### Production Environment
|
||||
|
||||
```bash
|
||||
# Production .env example
|
||||
RAILS_ENV=production
|
||||
NODE_ENV=production
|
||||
FRONTEND_URL=https://chat.yourcompany.com
|
||||
FORCE_SSL=true
|
||||
SECRET_KEY_BASE=your-production-secret-key
|
||||
|
||||
# Database
|
||||
DATABASE_URL=postgresql://chatwoot:secure-password@db.yourcompany.com:5432/chatwoot_production
|
||||
|
||||
# Redis
|
||||
REDIS_URL=redis://redis.yourcompany.com:6379/0
|
||||
|
||||
# Email
|
||||
MAILER_SENDER_EMAIL=noreply@yourcompany.com
|
||||
SMTP_ADDRESS=smtp.yourcompany.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=noreply@yourcompany.com
|
||||
SMTP_PASSWORD=your-smtp-password
|
||||
|
||||
# Storage
|
||||
ACTIVE_STORAGE_SERVICE=amazon
|
||||
S3_BUCKET_NAME=yourcompany-chatwoot
|
||||
AWS_ACCESS_KEY_ID=your-aws-key
|
||||
AWS_SECRET_ACCESS_KEY=your-aws-secret
|
||||
AWS_REGION=us-east-1
|
||||
|
||||
# Security
|
||||
ENABLE_2FA=true
|
||||
ENABLE_RATE_LIMITING=true
|
||||
CORS_ORIGINS=https://yourcompany.com
|
||||
|
||||
# Monitoring
|
||||
SENTRY_DSN=your-sentry-dsn
|
||||
NEW_RELIC_LICENSE_KEY=your-newrelic-key
|
||||
```
|
||||
|
||||
### Development Environment
|
||||
|
||||
```bash
|
||||
# Development .env example
|
||||
RAILS_ENV=development
|
||||
NODE_ENV=development
|
||||
FRONTEND_URL=http://localhost:3000
|
||||
FORCE_SSL=false
|
||||
|
||||
# Database
|
||||
DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
|
||||
|
||||
# Redis
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
|
||||
# Email (development)
|
||||
MAILER_SENDER_EMAIL=dev@localhost
|
||||
EMAIL_DELIVERY_METHOD=test
|
||||
|
||||
# Storage (local)
|
||||
ACTIVE_STORAGE_SERVICE=local
|
||||
|
||||
# Development features
|
||||
ENABLE_DEVELOPMENT_FEATURES=true
|
||||
ENABLE_SQL_LOGGING=true
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
## Validation and Best Practices
|
||||
|
||||
### Required Variables
|
||||
|
||||
<Warning>
|
||||
These environment variables are required for Chatwoot to function properly:
|
||||
- `FRONTEND_URL`
|
||||
- `SECRET_KEY_BASE`
|
||||
- `DATABASE_URL` or individual database components
|
||||
- `REDIS_URL` or individual Redis components
|
||||
</Warning>
|
||||
|
||||
### Security Best Practices
|
||||
|
||||
<Tip>
|
||||
**Security Recommendations:**
|
||||
- Use strong, unique passwords for all services
|
||||
- Enable SSL/TLS for all external connections
|
||||
- Use environment-specific secret keys
|
||||
- Enable rate limiting and CORS protection
|
||||
- Regularly rotate API keys and passwords
|
||||
- Use managed services for databases when possible
|
||||
</Tip>
|
||||
|
||||
### Performance Optimization
|
||||
You can generate `SECRET_KEY_BASE` using `rake secret` command from the project root folder. If you dont have rails installed, use `head /dev/urandom | tr -dc A-Za-z0-9 | head -c 63 ; echo ''`.
|
||||
|
||||
<Note>
|
||||
**Performance Tips:**
|
||||
- Adjust `SIDEKIQ_CONCURRENCY` based on your server resources
|
||||
- Use Redis for caching and session storage
|
||||
- Configure CDN for static assets
|
||||
- Enable compression and caching
|
||||
- Monitor and adjust database pool sizes
|
||||
SECRET_KEY_BASE should be alphanumeric. Avoid special characters or symbols.
|
||||
</Note>
|
||||
|
||||
---
|
||||
## Database configuration
|
||||
|
||||
This comprehensive environment variables reference covers all aspects of Chatwoot configuration. Customize these settings based on your specific deployment requirements and infrastructure setup.
|
||||
Postgres can be configured in two ways: via `DATABASE_URL` or setting up independent Postgres variables.
|
||||
|
||||
### Configure Postgres
|
||||
|
||||
Set the `DATABASE_URL` variable with value as Postgres connection URI to connect to the database.
|
||||
|
||||
The URI is of the format
|
||||
|
||||
```bash
|
||||
postgresql://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]
|
||||
```
|
||||
|
||||
Or you can set the following environment variables to configure Postgres. Replace the values here with yours. Skip this
|
||||
if you have configured `DATABASE_URL`.
|
||||
|
||||
```bash
|
||||
POSTGRES_HOST=localhost
|
||||
POSTGRES_PORT=5432
|
||||
POSTGRES_DATABASE=chatwoot_production
|
||||
POSTGRES_USERNAME=admin
|
||||
POSTGRES_PASSWORD=password
|
||||
```
|
||||
|
||||
### Configure Redis
|
||||
|
||||
For development, you can use the following URL to connect to Redis. For production, configure your Redis URL.
|
||||
|
||||
```bash
|
||||
REDIS_URL='redis://127.0.0.1:6379'
|
||||
```
|
||||
|
||||
To authenticate Redis connections made by the app server and sidekick, if it's protected by a password, use the following environment variable to set the password.
|
||||
|
||||
```bash
|
||||
REDIS_PASSWORD=
|
||||
```
|
||||
|
||||
## Configure emails
|
||||
|
||||
For development, you don't need an email provider. Chatwoot uses the [letter-opener](https://github.com/ryanb/letter_opener) gem to test emails locally
|
||||
|
||||
For production use, please configure the following variables.
|
||||
|
||||
```bash
|
||||
# could user either `email@yourdomain.com` or `BrandName <email@yourdomain.com>`
|
||||
MAILER_SENDER_EMAIL=
|
||||
```
|
||||
|
||||
and based on your SMTP server the following variables
|
||||
|
||||
```bash
|
||||
SMTP_ADDRESS=
|
||||
SMTP_USERNAME=
|
||||
SMTP_PASSWORD=
|
||||
SMTP_TLS=
|
||||
SMTP_SSL=
|
||||
```
|
||||
|
||||
### Postfix
|
||||
|
||||
Follow these steps if you want to use a selfhosted mail server with Chatwoot. This is the default behavior starting from `v2.12.0` and relies on `SMTP_ADDRESS` environment variable not being set.
|
||||
|
||||
```
|
||||
sudo apt install -y postfix
|
||||
```
|
||||
|
||||
Choose internet-site when prompted and enter the domain name you used with Chatwoot setup for `System mail name`.
|
||||
|
||||
<Note>
|
||||
By default, all major cloud provider have blocked port 25 used for sending emails as part of their spam combat effects. Please raise a support ticket with your cloud provider to enable outbound access on port 25 for this to work. Refer [AWS](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle), [GCP](https://cloud.google.com/compute/docs/tutorials/sending-mail), [Azure](https://learn.microsoft.com/en-us/azure/virtual-network/troubleshoot-outbound-smtp-connectivity) and [DigitalOcean](https://www.digitalocean.com/blog/smtp-restricted-by-default) for more details.
|
||||
</Note>
|
||||
|
||||
Also please add MX and PTR records for your domain. If your emails are being flagged by `Gmail` and `Outlook`, setup [SPF and DKIM records](https://www.linuxbabe.com/mail-server/setting-up-dkim-and-spf) for your domain as well. This should improve your email reputation.
|
||||
|
||||
### Amazon SES
|
||||
|
||||
```bash
|
||||
SMTP_ADDRESS=email-smtp.<region>.amazonaws.com
|
||||
SMTP_AUTHENTICATION=plain
|
||||
SMTP_ENABLE_STARTTLS_AUTO=true
|
||||
SMTP_USERNAME=<Your SMTP username>
|
||||
SMTP_PASSWORD=<Your SMTP password>
|
||||
```
|
||||
|
||||
### SendGrid
|
||||
|
||||
<Info>
|
||||
For clarification, the `SMTP_USERNAME` should be set to the literal text apikey—this is not the actual API key. SendGrid uses 'apikey' as the standard username for its services.
|
||||
</Info>
|
||||
|
||||
```bash
|
||||
SMTP_ADDRESS=smtp.sendgrid.net
|
||||
SMTP_AUTHENTICATION=plain
|
||||
SMTP_DOMAIN=<your verified domain>
|
||||
SMTP_ENABLE_STARTTLS_AUTO=true
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=apikey
|
||||
SMTP_PASSWORD=<your Sendgrid API key>
|
||||
```
|
||||
|
||||
### MailGun
|
||||
|
||||
```bash
|
||||
SMTP_ADDRESS=smtp.mailgun.org
|
||||
SMTP_AUTHENTICATION=plain
|
||||
SMTP_DOMAIN=<Your domain, this has to be verified in Mailgun>
|
||||
SMTP_ENABLE_STARTTLS_AUTO=true
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=<Your SMTP username, view under Domains tab>
|
||||
SMTP_PASSWORD=<Your SMTP password, view under Domains tab>
|
||||
```
|
||||
|
||||
### Mandrill
|
||||
|
||||
If you would like to use Mailchimp to send your emails, use the following environment variables:
|
||||
|
||||
<Note>
|
||||
Mandrill is the transactional email service for Mailchimp. You need to enable transactional email and login to mandrillapp.com.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
SMTP_ADDRESS=smtp.mandrillapp.com
|
||||
SMTP_AUTHENTICATION=plain
|
||||
SMTP_DOMAIN=<Your verified domain in Mailchimp>
|
||||
SMTP_ENABLE_STARTTLS_AUTO=true
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=<Your SMTP username displayed under Settings -> SMTP & API info>
|
||||
SMTP_PASSWORD=<Any valid API key, create an API key under Settings -> SMTP & API Info>
|
||||
```
|
||||
|
||||
## Configure default language
|
||||
|
||||
```bash
|
||||
DEFAULT_LOCALE='en'
|
||||
```
|
||||
|
||||
## Configure storage
|
||||
|
||||
Chatwoot uses [active storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) for storing attachments. The default storage option is the local storage on your server.
|
||||
|
||||
But you can change it to use any of the cloud providers like amazon s3, microsoft azure, google gcs etc. Refer [configuring cloud storage](/docs/self-hosted/deployment/storage/supported-providers) for additional environment variables required.
|
||||
|
||||
```bash
|
||||
ACTIVE_STORAGE_SERVICE=local
|
||||
```
|
||||
|
||||
When `local` storage is used the files are stored under `/storage` directory in the chatwoot root folder.
|
||||
|
||||
<Warning>
|
||||
It is recommended to use a cloud provider for your chatwoot storage to ensure proper backup of the stored attachments and prevent data loss.
|
||||
</Warning>
|
||||
|
||||
## Rails Logging Variables
|
||||
|
||||
By default, Chatwoot will capture `info` level logs in production. Ref [rails docs](https://guides.rubyonrails.org/debugging_rails_applications.html#log-levels) for the additional log-level options.
|
||||
We will also retain 1 GB of your recent logs and your last shifted log file.
|
||||
You can fine-tune these settings using the following environment variables
|
||||
|
||||
```bash
|
||||
# possible values: 'debug', 'info', 'warn', 'error', 'fatal' and 'unknown'
|
||||
LOG_LEVEL=
|
||||
# value in megabytes
|
||||
LOG_SIZE= 1024
|
||||
```
|
||||
|
||||
## Configure FB Channel
|
||||
|
||||
To use FB Channel, you have to create a Facebook app in the developer portal. You can find more details about creating FB channels [here](https://developers.facebook.com/docs/apps/#register)
|
||||
|
||||
```bash
|
||||
FB_VERIFY_TOKEN=
|
||||
FB_APP_SECRET=
|
||||
FB_APP_ID=
|
||||
```
|
||||
|
||||
## Using CDN for asset delivery
|
||||
|
||||
With the release v1.8.0, we are enabling CDN support for Chatwoot. If you have a high traffic website, we recommend to setup a CDN for your asset delivery. Read setting up [CloudFront as your CDN](/docs/self-hosted/deployment/performance/cloudfront-cdn) guide.
|
||||
|
||||
## Enable new account signup
|
||||
|
||||
By default, Chatwoot will not allow users to create an account[multi-tenancy] from the login page. However, if you are setting up a public server, you can enable signup using:
|
||||
|
||||
```bash
|
||||
ENABLE_ACCOUNT_SIGNUP=true
|
||||
```
|
||||
|
||||
## Enable direct upload to storage cloud
|
||||
|
||||
By default, Chatwoot will upload the files to the application server and then it will push them to the cloud storage. We have introduced the direct upload functionality so that we can upload the file directly to the cloud storage. This has been built according to rails new direct upload functionality documented [here](https://edgeguides.rubyonrails.org/active_storage_overview.html#direct-uploads). Set below environment variable to true to use the direct upload feature.
|
||||
|
||||
Make sure to follow [this guide](https://edgeguides.rubyonrails.org/active_storage_overview.html#cross-origin-resource-sharing-cors-configuration) and set the appropriate CORS configuration on your cloud storage after setting `DIRECT_UPLOADS_ENABLED` to true.
|
||||
|
||||
```bash
|
||||
DIRECT_UPLOADS_ENABLED=true
|
||||
```
|
||||
|
||||
## Google OAuth
|
||||
|
||||
To enable Google OAuth in Chatwoot, you need to provide the client ID, client secret, and callback URL. You can find the instructions to generate the details [here](https://support.google.com/cloud/answer/6158849).
|
||||
|
||||
Set the `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` environment variables in your Chatwoot installation using the values you copied from the Google API Console. Set the `GOOGLE_OAUTH_CALLBACK_URL` environment variable to the callback URL you used in the Google API Console. Here's an example of the same
|
||||
|
||||
```bash
|
||||
GOOGLE_OAUTH_CLIENT_ID=369777777777-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
|
||||
GOOGLE_OAUTH_CLIENT_SECRET=ABCDEF-GHijklmnoPqrstuvwX-yz1234567
|
||||
GOOGLE_OAUTH_CALLBACK_URL=https://<your-server-domain>/omniauth/google_oauth2/callback
|
||||
```
|
||||
|
||||
<Warning>
|
||||
The callback URL should comply with the format in the example above. This endpoint cannot be changed at the moment.
|
||||
</Warning>
|
||||
|
||||
After setting these environment variables, restart your Chatwoot server to apply the changes. Now, users will be able to sign in using their Google accounts.
|
||||
|
||||
## LogRocket
|
||||
|
||||
To enable LogRocket in Chatwoot, you need to provide the project ID from LogRocket. Here are the steps to follow:
|
||||
|
||||
1. Open the LogRocket [website](https://logrocket.com/) and create an account or sign in to your existing account.
|
||||
2. After signing in, create a new project in LogRocket by clicking on "Create new project".
|
||||
3. Enter a name for your project, and save the project ID.
|
||||
4. Set the `LOG_ROCKET_PROJECT_ID` environment variable in your `.env` file with the project ID you copied from LogRocket.
|
||||
|
||||
```bash
|
||||
LOG_ROCKET_PROJECT_ID=abcd12/pineapple-on-pizza
|
||||
```
|
||||
|
||||
After setting this environment variable, restart your Chatwoot server to apply the changes. Now, LogRocket will start capturing user sessions on your Chatwoot installation.
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Outlook & Microsoft 365 Email
|
||||
description: Configure an OAuth app for Outlook & Microsoft 365 emails
|
||||
sidebarTitle: Azure App Setup
|
||||
---
|
||||
|
||||
Microsoft no longer permits the use of username and password to retrieve emails from Outlook & Microsoft 365 accounts. They have deprecated the basic auth option. To enable the Outlook/Microsoft 365 email channel in your self-hosted instance, you must configure an OAuth app.
|
||||
|
||||
This guide helps you set up an Entra ID App (formerly Azure Active Directory) and use the credentials in Chatwoot. By doing so, you can authenticate your Outlook/Microsoft 365 account as an email channel.
|
||||
|
||||
## Register the app
|
||||
|
||||
<Note>
|
||||
For a more detailed guide on how to set up the Microsoft Identity platform, please refer to the [here](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
|
||||
</Note>
|
||||
|
||||
To access the Microsoft Entra Admin Center, go to [entra.microsoft.com](https://entra.microsoft.com/) and log in with your Microsoft account. Once logged in, navigate to the Identity section on the left-hand sidebar. In the Identity section, locate the "Applications" menu and click on "App Registrations" from the submenu. On the "App Registrations" page, click on the "New Registration" option. You will be able to see a page as shown below.
|
||||
|
||||
|
||||
|
||||
There are three options for supported account types. Ideally, you only need to select "Accounts in any organizational directory" as Chatwoot is generally used for business emails only. However, if you are connecting a personal account, select the second option. If you are using the applications outside your organization, you would need to register your account as a verified publisher.
|
||||
|
||||
To configure a redirect URI with the Web platform, use the following URL: `https://<your-instance-url>/microsoft/callback`. Click on register, and your app will be created. You will see a screen as shown below.
|
||||
|
||||
|
||||
|
||||
Save the Application (Client) ID. We will configure this as `AZURE_APP_ID` in Chatwoot later.
|
||||
|
||||
## Configure the application
|
||||
|
||||
To ensure proper functionality of Chatwoot, we need to configure the permissions and update the token configuration as follows.
|
||||
|
||||
### API permissions
|
||||
|
||||
Click on the "API Permissions" menu under the "Manage" section. By default, this will have [User.Read](http://user.read/) permission.
|
||||
|
||||
Click on the "Add permissions" button and add the following permissions from the Delegated permissions menu on Microsoft Graph APIs.
|
||||
|
||||
- **email**: To view the user's email address.
|
||||
- **profile**: To view the name and picture etc.
|
||||
- **offline_access**: To retrieve the emails even when you are not using the application.
|
||||
- **SMTP.Send, Mail.Send:** Send emails using the SMTP AUTH when you reply to customers from the Chatwoot dashboard.
|
||||
- **IMAP.AccessAsUser.All, Mail.ReadWrite:** Read and write access to mailboxes via IMAP.
|
||||
- **openid:** Sign users in
|
||||
|
||||
|
||||
|
||||
### Token Configuration
|
||||
|
||||
Now, let's proceed to the Token Configuration to set up "optional claims". Optional claims are a feature in Entra ID that enables you to specify additional pieces of information (claims) to include in the security tokens issued to the application.
|
||||
|
||||
In Chatwoot, we use optional claims to minimize duplicate calls and retrieve some information in advance. Click on "Add optional claim" and add the following claims to the application.
|
||||
|
||||
|
||||
|
||||
### Configure Client Secret
|
||||
|
||||
Go to the Certificates & Secrets section to create a Client Secret. Click on the "New Client Secret" button and provide a description. You can also select an expiry time.
|
||||
|
||||
<Warning>
|
||||
Remember that you will need to regenerate the secret and update it in the Chatwoot environment variables once it expires.
|
||||
</Warning>
|
||||
|
||||
|
||||
|
||||
After clicking on the Add button, a client secret will be generated as shown below.
|
||||
|
||||
|
||||
|
||||
Save the value somewhere save as you cannot see it after refreshing the page. This would be used `AZURE_APP_SECRET` in Chatwoot.
|
||||
|
||||
## Configure environment variables in Chatwoot
|
||||
|
||||
After creating the Entra application, you need to configure the application credentials in Chatwoot. There are 2 variables that you need to configure, as shown in the steps above.
|
||||
|
||||
- **AZURE_APP_ID:** As seen in the register the app step, use the Application (Client) ID here.
|
||||
- **AZURE_APP_SECRET:** Use the value obtained in the step configuring the client secret.
|
||||
|
||||
After updating the environment variables, restart the Chatwoot service for the changes to take effect. Now, verify if the channel is enabled in the Inbox creation flow. If everything is configured properly, you will see "Microsoft" listed as an email provider in the flow.
|
||||
|
||||
|
||||
|
||||
Voila! That's it you can now receive the emails in your Chatwoot instance.
|
||||
|
||||
## Thoughts on multi-tenancy and going for production
|
||||
|
||||
Note that the setup will not work for other emails under a different tenant until you have completed the Microsoft publisher verification process. During the authorization prompt, you will see "unverified" until the application is verified for production.
|
||||
|
||||
To test the changes before the app is verified for production, use the Entra ID app registration email address in the Chatwoot channel.
|
||||
|
||||
Publisher verification provides app users and organization admins with information about the authenticity of the developer's organization that publishes an app integrating with the Microsoft identity platform. If an app has a verified publisher, it means that Microsoft has verified the authenticity of the organization that publishes the app.
|
||||
|
||||
Read the publishing guidelines [here](https://learn.microsoft.com/en-us/entra/identity-platform/howto-convert-app-to-be-multi-tenant).
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: SendGrid Guide
|
||||
description: Guide to setting up Conversation Continuity with SendGrid
|
||||
sidebarTitle: SendGrid Guide
|
||||
---
|
||||
|
||||
This doc will help you set up [Conversation continuity](https://www.chatwoot.com/docs/self-hosted/configuration/features/email-channel/conversation-continuity) with SendGrid.
|
||||
|
||||
## Installation
|
||||
|
||||
This example is based on a Heroku installation of Chatwoot, and using SendGrid for outgoing email. For more information about installing Chatwoot, go [here](https://www.chatwoot.com/docs/self-hosted#deployment).
|
||||
|
||||
## Configuring inbound reply emails
|
||||
|
||||
Firstly, we need to tell our Chatwoot instance what mailer we're using to handle incoming emails. We do that with a config var. Go to your Heroku dashboard, click on your Chatwoot instance and click settings.
|
||||
|
||||
|
||||
|
||||
Then scroll until you see two blank fields with an add button. There, enter:
|
||||
|
||||
```javascript
|
||||
RAILS_INBOUND_EMAIL_SERVICE=sendgrid
|
||||
```
|
||||
|
||||
|
||||
|
||||
Next, we're going to set a password. We'll use this later on with SendGrid. For this example, we'll use something simple - like ```potatosalad```, but like all passwords - you should always use a secure mixture of letters, numbers and symbols.
|
||||
|
||||
|
||||
|
||||
## SendGrid
|
||||
|
||||
Now we're going to set up the domain we're using for inbound emails. Because you're most likely going to have an email service like Google Workspace or Microsoft 365 for Business, you should use a subdomain for your inbound emails to Chatwoot.
|
||||
|
||||
For example, let's say we used support.example.com as our domain. In this instance, we'd add an MX record pointing support.example.com to ```mx.sendgrid.net``` with a priority of ```10```.
|
||||
|
||||
You should wait a while (usually an hour will do). You can use [mxtoolbox.com](https://mxtoolbox.com) to check if the MX record has been propogated. If you see something like this, you can move onto the next step:
|
||||
|
||||
|
||||
|
||||
Now, go to the SendGrid dashboard at [app.sendgrid.com](https://app.sendgrid.com). Select Settings, and Inbound Parse.
|
||||
|
||||
|
||||
|
||||
Then click "Add Host & URL".
|
||||
|
||||
|
||||
|
||||
**Receiving Subdomain** should be the domain you set up the MX record for earlier.
|
||||
|
||||
|
||||
|
||||
Then add your **Destination URL**. Your Destination URL should look something like this:
|
||||
|
||||
```https://actionmailbox:potatosalad@chatwoot.example.com/rails/action_mailbox/sendgrid/inbound_emails```
|
||||
|
||||
``potatosalad`` is the password we set earlier, and ``chatwoot.example.com`` is the URL of our Chatwoot instance. Everything else should stay the same.
|
||||
|
||||
|
||||
|
||||
<Warning>
|
||||
Make sure to check "POST the raw, full MIME message". In order to function correctly, Action Mailbox needs the raw MIME message.
|
||||
</Warning>
|
||||
|
||||
|
||||
|
||||
## Setting the inbound domain variable in Heroku
|
||||
|
||||
Finally, we need to tell our Chatwoot installation what domain we're using with SendGrid.
|
||||
|
||||
Your variable should look like this:
|
||||
|
||||
```javascript
|
||||
MAILER_INBOUND_EMAIL_DOMAIN=support.example.com
|
||||
```
|
||||
|
||||
You should change ``support.example.com`` to the domain you used with SendGrid.
|
||||
|
||||
|
||||
|
||||
## Next steps
|
||||
|
||||
You're done! Next, you should [enable the email channel](https://www.chatwoot.com/docs/self-hosted/configuration/features/email-channel/setup).
|
||||
+124
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: Conversation Continuity
|
||||
description: Configure Conversation Continuity with Email
|
||||
sidebarTitle: Conversation Continuity
|
||||
---
|
||||
|
||||
## Conversation continuity
|
||||
|
||||
|
||||
|
||||
## Configuring inbound reply emails
|
||||
|
||||
<Note>
|
||||
Conversation Continuity requires your chatwoot installation to have a [cloud storage configured](/docs/self-hosted/deployment/storage/supported-providers)
|
||||
</Note>
|
||||
|
||||
There are a couple of email infrastructure service providers to handle the incoming emails that we support at the moment. They are
|
||||
Sendgrid, Mandrill, Mailgun, Exim, Postfix, Qmail and Postmark.
|
||||
|
||||
Step 1 : We have to set the inbound email service used as an environment variable.
|
||||
|
||||
```bash
|
||||
# Set this to appropriate ingress service for which the options are :
|
||||
# "relay" for Exim, Postfix, Qmail
|
||||
# "mailgun" for Mailgun
|
||||
# "mandrill" for Mandrill
|
||||
# "postmark" for Postmark
|
||||
# "sendgrid" for Sendgrid
|
||||
RAILS_INBOUND_EMAIL_SERVICE=relay
|
||||
```
|
||||
If you wish to use the same local relaying server (for example postfix) to send outbound mail as you are using to relay inbound messages and you opt not to use an external authentication mechanism like SASL which may be the case if the server is handling it own emails only. The upstream SMTP platform Action Mailer attempts to use a default authentication method if the configuration options `SMTP_AUTHENTICATION`, `SMTP_USERNAME` and `SMTP_PASSWORD` are present in your .env file. To disable this behaviour either comment out or delete these lines from your configuration. This will allow you to send outbound messages from the same server without a premium service. Please note many ISP's do not allow email servers to be run from their networks. It is your responsibility to ensure adequate access control preventing yourself becoming an open relay and ensuring your server is able to get past your recipients spam filters for example SPF, DKIM & DMARC dns records.
|
||||
|
||||
This configures the ingress service for the app. Now we have to set the password for the ingress service that we use.
|
||||
|
||||
```bash
|
||||
# Use one of the following based on the email ingress service
|
||||
|
||||
# Set this if you are using Sendgrid, Exim, Postfix, Qmail or Postmark
|
||||
RAILS_INBOUND_EMAIL_PASSWORD=
|
||||
# Set this if you are Mailgun
|
||||
MAILGUN_INGRESS_SIGNING_KEY=
|
||||
# Set this if you are Mandrill
|
||||
MANDRILL_INGRESS_API_KEY=
|
||||
```
|
||||
|
||||
### Mailgun
|
||||
If you are using Mailgun as your email service, in the Mailgun dashboard configure it to forward your inbound emails to `https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime` if `example.com` is where you have hosted the application.
|
||||
|
||||
#### Getting Mailgun Ingress Key
|
||||
|
||||
|
||||
### Sendgrid
|
||||
|
||||
Ensure to set up the proper MX records for `your-domain.com` pointed towards Sendgrid
|
||||
|
||||
Configure SendGrid Inbound Parse to forward inbound emails to forward your inbound emails to `/rails/action_mailbox/sendgrid/inbound_emails` with the username `actionmailbox` and the password you previously generated. If the deployed application was hosted at `example.com`, you can configure the following URL as the forward route.
|
||||
|
||||
```bash
|
||||
https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails
|
||||
```
|
||||
|
||||
When configuring your SendGrid Inbound Parse webhook, be sure to check the box labeled "Post the raw, full MIME message." Action Mailbox needs the raw MIME message to work.
|
||||
|
||||
### Mandrill
|
||||
If you are configuring Mandrill as your email service, configure Mandrill to route your inbound emails to `https://example.com/rails/action_mailbox/mandrill/inbound_emails` if `example.com` is where you have hosted the application.
|
||||
|
||||
If you want to know more about configuring other services visit [Action Mailbox Basics](https://edgeguides.rubyonrails.org/action_mailbox_basics.html#configuration)
|
||||
|
||||
### IMAP via getmail
|
||||
Chatwoot receives inbound emails through the [Action Mailbox](https://edgeguides.rubyonrails.org/action_mailbox_basics.html) feature of Ruby on Rails. Action Mailbox supports various 'ingresses' by default. They are defined in [here](https://github.com/rails/rails/blob/main/actionmailbox/lib/tasks/ingress.rake) and can be executed through `bin/rails`. For example
|
||||
```bash
|
||||
cat my_incoming_message | ./bin/rails action_mailbox:ingress:postfix \
|
||||
RAILS_ENV=production \
|
||||
URL=http://localhost:3000/rails/action_mailbox/postfix/inbound_emails \
|
||||
INGRESS_PASSWORD=...
|
||||
```
|
||||
would import the contents of the file `my_incoming_message` into a Chatwoot instance running on `localhost` - assuming `my_incoming_message` contains an [RFC 822](https://datatracker.ietf.org/doc/html/rfc822) compliant message.
|
||||
|
||||
The ingress tasks provided by Action Mailbox are a thin layer around an HTTP endpoint exposed by Action Mailbox. An alternative to using those tasks is to talk to the http endpoint directly. The following script achieves the same.
|
||||
```bash
|
||||
INGRESS_PASSWORD=...
|
||||
URL=http://localhost:3000/rails/action_mailbox/relay/inbound_emails
|
||||
|
||||
curl -sS -u "actionmailbox:$INGRESS_PASSWORD" \
|
||||
-A "Action Mailbox curl relayer" \
|
||||
-H "Content-Type: message/rfc822" \
|
||||
--data-binary @- \
|
||||
$URL
|
||||
```
|
||||
|
||||
The popular mail retrieval system [getmail6](https://github.com/getmail6/getmail6) can be used to fetch mails and import them into Chatwoot. If the curl script above is stored in `/home/chatwoot/bin/import_mail_to_chatwoot`, a configuration for doing so from an IMAP inbox is as follows.
|
||||
```
|
||||
[retriever]
|
||||
type = SimpleIMAPSSLRetriever
|
||||
server = ...
|
||||
username = ...
|
||||
password = ...
|
||||
|
||||
[destination]
|
||||
type = MDA_external
|
||||
path = /home/chatwoot/bin/import_mail_to_chatwoot
|
||||
|
||||
[options]
|
||||
verbose = 0
|
||||
read_all = false
|
||||
delete = false
|
||||
delivered_to = false
|
||||
received = false
|
||||
message_log = /home/chatwoot/logs/import_imap.log
|
||||
message_log_syslog = false
|
||||
message_log_verbose = true
|
||||
```
|
||||
|
||||
For mail to be imported you'll need to execute `getmail` regularly, for example using a cron job. For `IMAP` you can also run it constantly using `getmail --idle INBOX`, though that will need some care to deal with interrupted connections, etc.
|
||||
|
||||
## Configure inbound email domain environment variable
|
||||
|
||||
Add the following environment variable with the value `your-domain.com`, where `your-domain.com` is the domain for which you set up MX records in the previous step.
|
||||
|
||||
```bash
|
||||
MAILER_INBOUND_EMAIL_DOMAIN=
|
||||
```
|
||||
|
||||
After finishing the set up, the mail sent from Chatwoot will have a `replyto:` in the following format `reply+<random-hex>@<your-domain.com>` and reply to those would get appended to your conversation.
|
||||
+38
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Email Channel Setup
|
||||
description: Setting up Email Channel in Chatwoot
|
||||
sidebarTitle: Email Channel Setup
|
||||
---
|
||||
|
||||
## Configure Email Channel
|
||||
|
||||
<Note>
|
||||
Email channels require [conversation continuity configured](/docs/self-hosted/configuration/features/email-channel/conversation-continuity)
|
||||
</Note>
|
||||
|
||||
1. Enable `channel_email` (Login to rails console and execute the following)
|
||||
|
||||
```bash
|
||||
account = Account.find(1)
|
||||
account.enabled_features // This would list enabled features.
|
||||
account.enable_features('channel_email')
|
||||
account.save!
|
||||
```
|
||||
|
||||
2. Now head over to inboxes page and create an email inbox with the support email as care@your-domain.com
|
||||
|
||||
3. Now Add Agents who can have access to the email channel box.
|
||||
4. Now you will get the email channel box address in the last step.
|
||||
|
||||
5. Now create a forward rule in your care@your-domain.com inbox to forward emails to the address obtained at inbox creation step.
|
||||
|
||||
6. You should be able to receive emails in your newly created email inbox in chatwoot.
|
||||
|
||||
|
||||
### Sendgrid
|
||||
|
||||
You can send out emails only from a verified email address in SendGrid. For sending emails from wildcard domain, do verification at domain level instead of individual email.
|
||||
|
||||
### Testing On Local
|
||||
|
||||
You can visit `http://localhost:3000/rails/conductor/action_mailbox/inbound_emails/new` to send inbound mails from local to chatwoot inbox.
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Google Workspace
|
||||
description: Configure an OAuth app for Gmail
|
||||
sidebarTitle: Google Workspace
|
||||
---
|
||||
|
||||
At present, Gmail integration operates through [less-secure](https://support.google.com/accounts/answer/6010255?hl=en) apps. However, as of June 15, 2024, Google Workspace will [cease to support](https://workspaceupdates.googleblog.com/2023/09/winding-down-google-sync-and-less-secure-apps-support.html) these less-secure apps. This will affect the Gmail integration in Chatwoot. To ensure that your Gmail integration continues to work, you will need to set up an OAuth app in Google Workspace.
|
||||
|
||||
<Note>
|
||||
Existing setups will continue to work until September 30, 2024. However, we recommend setting up an OAuth app as soon as possible to avoid any disruptions.
|
||||
</Note>
|
||||
|
||||
This guide will walk you through the process of setting up an OAuth app in Google Workspace.
|
||||
|
||||
## Register the app
|
||||
|
||||
To enable Google OAuth in Chatwoot, you need to provide the client ID, client secret, and callback URL. You can find the instructions to generate these details [here](https://support.google.com/cloud/answer/6158849). Once you have followed these steps, you will be able to get a Client ID and Secret.
|
||||
|
||||
|
||||
|
||||
Use the callback URL `https://<your-instance-url>/google/callback` when registering the app. This URL is used to redirect the user back to the Chatwoot instance after authentication.
|
||||
|
||||
Set the `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` environment variables in your Chatwoot installation using the values you copied from the Google API Console.
|
||||
|
||||
```bash
|
||||
GOOGLE_OAUTH_CLIENT_ID=369777777777-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
|
||||
GOOGLE_OAUTH_CLIENT_SECRET=ABCDEF-GHijklmnoPqrstuvwX-yz1234567
|
||||
```
|
||||
|
||||
<Note>
|
||||
If you have already setup [Google OAuth login flow](https://www.chatwoot.com/docs/self-hosted/configuration/environment-variables#google-oauth) You can use the same app, by simply adding the new callback URL. **Do not remove the previous callback URL.**
|
||||
</Note>
|
||||
|
||||
After setting these environment variables, restart your Chatwoot server to apply the changes. Now, users will be able to sign in using their Google accounts.
|
||||
|
||||
You will notice that the app you are using is in testing mode; we will cover that later in the guide. For now, you can ignore it.
|
||||
|
||||
## Configure the application
|
||||
|
||||
To fetch the emails from the client inbox, you need to configure the correct scopes. The following scopes are required:
|
||||
|
||||
- `https://mail.google.com/`: To read, send, delete, and manage your email.
|
||||
- `email`: To view the user's email address.
|
||||
- `profile`: To view the name and picture etc.
|
||||
|
||||
You can configure the scopes in the Google API Console by following the steps below:
|
||||
|
||||
1. Go to the [Google API Console](https://console.developers.google.com/).
|
||||
2. Select the project you created earlier.
|
||||
3. Click on the "OAuth consent screen" tab and click on the "Edit App" button.
|
||||
4. Add the required scopes in the "Scopes for Google APIs" section.
|
||||
5. Click on the "Save" button.
|
||||
|
||||
Here's a demo showing how to add the `https://mail.google.com/` scope:
|
||||
|
||||
|
||||
|
||||
## Publishing the app
|
||||
|
||||
If you're using Chatwoot within an organization with fewer than 100 users, you can continue to use the app in testing mode. However, if you're using Chatwoot in an organization with more than 100 users or using the app to serve multiple clients, you will need to publish the app to make it available to all users.
|
||||
|
||||
To publish the app, you need to go through the verification process since we use a restricted scope. You can find the instructions to verify the app [here](https://support.google.com/cloud/answer/9110914).
|
||||
|
||||
It's important to note that the verification process can take a few days to complete. Once the app is verified, you can publish it and make it available to all users.
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Help Center
|
||||
description: Set up a public-facing help center portal with custom domain and SSL certificate
|
||||
sidebarTitle: Help Center
|
||||
---
|
||||
|
||||
Help center allows you to create a portal and add articles from the chatwoot app dashboard. You can point to these help center portal articles from your main site and display them as your public-facing help center.
|
||||
|
||||
## How to get SSL certificate for your custom domain
|
||||
|
||||
### Create a Portal in Chatwoot's dashboard
|
||||
|
||||
Follow these step to create your Portal. Refer to [this guide.](https://www.chatwoot.com/hc/user-guide/articles/1677861202-how-to-setup-a-help-center)
|
||||
|
||||
### Point your custom domain to your Chatwoot domain
|
||||
|
||||
1. Go to your DNS provider and add a new CNAME record.
|
||||
- For the above example, add docs as a CNAME record and point it to the your selfhosted chatwoot domain(FRONTEND_URL).
|
||||
|
||||
2. This will ensure that your CNAME record points to the selfhosted Chatwoot installation. For your custom domain, we have your portal information. In this case, `docs.example.com`
|
||||
|
||||
### Setting up SSL
|
||||
|
||||
1. Use certbot to generate SSL certificates for your custom domain.
|
||||
|
||||
```bash
|
||||
certbot certonly --agree-tos --nginx -d "docs.example.com"
|
||||
```
|
||||
|
||||
2. Create a new nginx config to route requests to this domain to Chatwoot. Make a copy of `/etc/nginx/sites-available/nginx_chatwoot.conf` and make necessary changes for the new domain.
|
||||
|
||||
3. Restart nginx server.
|
||||
|
||||
```bash
|
||||
sudo systemctl restart nginx
|
||||
```
|
||||
|
||||
Voila!
|
||||
|
||||
`docs.yourdomain.com` is live with a secure connection, and your portal data is visible.
|
||||
|
||||
### How does this work?
|
||||
|
||||
These are the engineering details to understand `How does docs.yourdomain.com` gets the portal data with SSL certificate.
|
||||
|
||||
1. `docs.yourdomain.com` resolves by customers nameserver and redirects to your Chatwoot domain.
|
||||
2. Chatwoot check for the portal record with custom-domain `docs.yourdomain.com`
|
||||
3. Redirects to the portal records for the domain `docs.yourdomain.com`
|
||||
|
||||
Yaay!!
|
||||
|
||||
Now you can have your own help-center, product-documentation related portal saved at Chatwoot dashboard and served at your domain with SSL certificate.
|
||||
@@ -0,0 +1,163 @@
|
||||
---
|
||||
title: Setting Up Facebook
|
||||
description: Configure Facebook Messenger integration for Chatwoot
|
||||
sidebarTitle: Facebook
|
||||
---
|
||||
|
||||
To use Facebook Channel, you have to create a Facebook app in the developer portal. You can find more details about creating Facebook apps [here](https://developers.facebook.com/docs/apps/#register).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. A valid facebook account.
|
||||
2. A valid facebook page.
|
||||
|
||||
## Register A Facebook App
|
||||
|
||||
1. Go to [Facebook developer portal](https://developers.facebook.com/apps/) and click on the "Create App" button
|
||||
|
||||
|
||||
|
||||
2. Select the option "Other".
|
||||
|
||||
|
||||
|
||||
3. For the app type, choose "Business".
|
||||
|
||||
|
||||
|
||||
3. Enter basic details like the app name and email.
|
||||
|
||||
|
||||
|
||||
Once you register your Facebook App, you will have to obtain the `App Id` and `App Secret`. These values will be available in the app settings and will be required while setting up Chatwoot environment variables.
|
||||
|
||||
|
||||
|
||||
## Configuring the Environment Variables in Chatwoot
|
||||
|
||||
Configure the following Chatwoot environment variables with the values you obtained during the Facebook app setup. The `FB_VERIFY_TOKEN` should be a unique and secure string that you provide when configuring the Facebook app. Generate a random string and set it as the `FB_VERIFY_TOKEN`. Facebook will include this string in all verification requests.
|
||||
|
||||
Restart the Chatwoot server after updating the environment variables
|
||||
|
||||
```bash
|
||||
FB_VERIFY_TOKEN=
|
||||
FB_APP_SECRET=
|
||||
FB_APP_ID=
|
||||
```
|
||||
|
||||
## Configure Facebook Login
|
||||
|
||||
1. Add the Facebook Login product via the Facebook app dashboard.
|
||||
|
||||
|
||||
|
||||
2. Enable `Web OAuth Login`, `Login with Javascript SDK` and add your self-hosted domain to the `Allowed Domains for the JavaScript SDK` input.
|
||||
|
||||
|
||||
|
||||
## Configure the Facebook App
|
||||
|
||||
1. In the app settings, add your `Chatwoot installation domain` as your app domain.
|
||||
|
||||
|
||||
|
||||
2. In the products section in your app settings page, Add "Messenger"
|
||||
|
||||
|
||||
|
||||
3. Go to the Messenger settings and configure the call back URL
|
||||
|
||||
|
||||
|
||||
4. Provide the Callback URL as `{your_chatwoot_installation_url}/bot` and the Verify token as `FB_VERIFY_TOKEN` from your environment variable.
|
||||
|
||||
|
||||
|
||||
5. Head over to Chatwoot and create a Messenger inbox. Choose a page for which your Facebook developer account has admin access to. Please refer to this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677778588-how-to-setup-a-facebook-channel) for more details on creating a Messenger inbox in Chatwoot.
|
||||
|
||||
## Testing the Facebook channel
|
||||
|
||||
Until the application is approved for production, Facebook wouldn't send the new messages on your page to Chatwoot.
|
||||
|
||||
To test the changes until the app is approved for production. Follow the steps
|
||||
|
||||
1. Head over to the messenger section in your app settings page, in Facebook developers.
|
||||
|
||||
|
||||
|
||||
2. Click `Add or remove pages` and connect the page which you choose while creating the Chatwoot Messenger inbox.
|
||||
|
||||
|
||||
|
||||
3. After connecting the pages, Click on `Add subscriptions` from the connected page.
|
||||
|
||||
|
||||
|
||||
4. Subscribe to the following fields and save the subscription.
|
||||
|
||||
```
|
||||
messages
|
||||
messaging_postbacks
|
||||
message_deliveries
|
||||
message_reads
|
||||
message_echoes
|
||||
```
|
||||
|
||||
|
||||
|
||||
4. Send a message to the connected page from your Facebook account and it should appear in Chatwoot now.
|
||||
|
||||
## Going into production.
|
||||
|
||||
Before you can start using your Facebook app in production, you will have to get it verified by Facebook. Refer to the [docs](https://developers.facebook.com/docs/apps/review/) on getting your app verified.
|
||||
|
||||
Obtain advanced access to the required permissions mentioned below for your Facebook app
|
||||
|
||||
```
|
||||
pages_messaging
|
||||
pages_show_list
|
||||
pages_manage_metadata
|
||||
business_management
|
||||
pages_read_engagement
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Make sure your facebook app subscription version is 17.0, we have updated the FB subscription with the latest version, so change the permission subscription version under the facebook app webhooks option.
|
||||
</Warning>
|
||||
|
||||
## Developing or Testing Facebook Integration in your machine
|
||||
|
||||
Install [ngrok](https://ngrok.com/docs) on your machine. This will be required since Facebook Messenger API's will only communicate via https.
|
||||
|
||||
```bash
|
||||
brew cask install ngrok
|
||||
```
|
||||
|
||||
Configure ngrok to route to your Rails server port.
|
||||
|
||||
```bash
|
||||
ngrok http 3000
|
||||
```
|
||||
|
||||
Go to the Facebook developers page and navigate into your app settings. In the app settings, add `localhost` as your app domain.
|
||||
In the Messenger settings page, configure the callback url with the following value.
|
||||
|
||||
```bash
|
||||
{your_ngrok_url}/bot
|
||||
```
|
||||
|
||||
Update verify token in your Chatwoot environment variables.
|
||||
|
||||
You will also have to add a Facebook page to your `Access Tokens` section in your Messenger settings page.
|
||||
Restart the Chatwoot local server. Your Chatwoot setup will be ready to receive Facebook messages.
|
||||
|
||||
## Facebook API version
|
||||
|
||||
We support facebook API version v13.0 going forward, which you can update in the facebook app advanced settings.
|
||||
|
||||
|
||||
## Test your local Setup
|
||||
|
||||
1. After finishing the set-up above, [create a Facebook inbox](https://www.chatwoot.com/hc/user-guide/articles/1677778588-how-to-setup-a-facebook-channel) after logging in to your Chatwoot Installation.
|
||||
2. Send a message to your page from Facebook.
|
||||
3. Wait and confirm incoming requests to `/bot` endpoint in your ngrok screen.
|
||||
@@ -0,0 +1,219 @@
|
||||
---
|
||||
title: Instagram via Facebook Login
|
||||
description: Set up Instagram integration using Facebook Login authentication
|
||||
sidebarTitle: Instagram via Facebook Login
|
||||
---
|
||||
|
||||
<Note>
|
||||
We recommend Instagram Business Login as the preferred authentication method, as it provides simpler configuration and a better developer experience. Please refer to this [guide](./instagram-via-instagram-business-login) for more details. We will be stopping the support for Instagram via Facebook Login in the future from v4.1 onwards.
|
||||
</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. A valid facebook account.
|
||||
2. A valid facebook page.
|
||||
3. A valid instagram professional account.
|
||||
|
||||
## Register A Facebook App
|
||||
|
||||
To use Instagram Channel, you have to create a Facebook app in the developer portal. You can find more details about creating Facebook developer app [here](./facebook-channel-setup).
|
||||
|
||||
1. Click on the "Create App" button
|
||||
|
||||
|
||||
|
||||
2. Select the option "Other".
|
||||
|
||||
|
||||
|
||||
3. For the app type, choose "Business"
|
||||
|
||||
|
||||
|
||||
3. Enter basic details like the app name and email.
|
||||
|
||||
|
||||
|
||||
Once you register your Facebook App, you will have to obtain the `App Id` and `App Secret`. These values will be available in the app settings and will be required while setting up Chatwoot environment variables.
|
||||
|
||||
|
||||
|
||||
## Configuring the Environment Variables in Chatwoot
|
||||
|
||||
Configure the following Chatwoot environment variables with the values you obtained during the Facebook app setup. The `IG_VERIFY_TOKEN` should be a unique and secure string that you provide when configuring the Instagram app.
|
||||
|
||||
Restart the Chatwoot server after updating the environment variables
|
||||
|
||||
```bash
|
||||
IG_VERIFY_TOKEN=
|
||||
FB_APP_SECRET=
|
||||
FB_APP_ID=
|
||||
```
|
||||
|
||||
## Configure the Facebook App
|
||||
|
||||
1. In the app settings, add your "Chatwoot installation domain" as your app domain.
|
||||
|
||||
2. Add the "Instagram Graph API" product via the Facebook app dashboard.
|
||||
|
||||
3. Go to the app settings and select "Webhooks". From there, choose Instagram and click on the "Subscribe to this object" button.
|
||||
|
||||
4. Provide the Callback URL as `{your_Chatwoot_installation_url}/webhooks/instagram` and the Verify token as `IG_VERIFY_TOKEN` from your environment variable.
|
||||
|
||||
|
||||
## Connect the facebook page with instagram account
|
||||
|
||||
1. Go to [Facebook pages](https://www.facebook.com/pages/?category=your_pages) and select your page and open the settings
|
||||
|
||||
|
||||
|
||||
2. Go to "Linked accounts" and connect your instagram professional account.
|
||||
|
||||
|
||||
|
||||
3. Select the option "Business"
|
||||
|
||||
|
||||
4. Select the instgram account category
|
||||
|
||||
|
||||
|
||||
5. If everything is okay, you will see the message "Instagram connected."
|
||||
|
||||
|
||||
|
||||
## Create Instagram Inbox in Chatwoot
|
||||
|
||||
1. Head over to Chatwoot and create a Messenger inbox. Please refer to this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677829420-how-to-setup-an-instagram-channel) for more details on creating a Messenger inbox in Chatwoot.
|
||||
|
||||
So whenever you receive any message on Instagram, it will redirect to your Facebook page.
|
||||
|
||||
## Testing the Instagram channel
|
||||
|
||||
Until the application is approved for production, Facebook wouldn't send the new messages on your instagram to Chatwoot.
|
||||
To test the changes until the app is approved for production. Follow the steps
|
||||
|
||||
1. Create a Test app for your app.
|
||||
|
||||
|
||||
|
||||
2. Add the `Instagram Graph API` product via the Facebook app dashboard.
|
||||
|
||||
|
||||
3. Go to the app settings and select "Webhooks". From there, choose Instagram and click on the "Subscribe to this object" button.
|
||||
|
||||
|
||||
4. Provide the Callback URL as `{your_chatwoot_installation_url}/webhooks/instagram` and the Verify token as `IG_VERIFY_TOKEN` from your environment variable.
|
||||
|
||||
|
||||
5. Open the test app and add extra product for the test app: Instagram Basic Display
|
||||
|
||||
|
||||
|
||||
6. In the app settings, add the platform "Website" and give `Site URL` as your installation URL.
|
||||
|
||||
|
||||
|
||||
7. Head over to the Instagram Basic Display section and create a new app.
|
||||
|
||||
|
||||
|
||||
8. Add Instagram Testers by clicking "Add or Remove Instagram Testers" button.
|
||||
|
||||
|
||||
|
||||
9. Make sure that you have selected the role `Instagram Tester` while creating a new tester.
|
||||
|
||||
|
||||
|
||||
10. Click on Edit subscriptions under Webhook > Instagram and subscribe to the following,
|
||||
|
||||
```
|
||||
message_reactions
|
||||
messages
|
||||
messaging_seen
|
||||
```
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
You should do this step for both normal and test apps.
|
||||
</Note>
|
||||
|
||||
1. Head over to Chatwoot and create a Messenger inbox. Please refer to this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677829420-how-to-setup-an-instagram-channel) for more details on creating a Messenger inbox in Chatwoot.
|
||||
2. Send a message to the connected Instagram account from Instagram Testers, and it should appear in Chatwoot now
|
||||
|
||||
## Going into production.
|
||||
|
||||
Before you can start using your Facebook app in production, you will have to get it verified by Facebook. Refer to the [docs](https://developers.facebook.com/docs/messenger-platform/instagram/app-review) on getting your app verified.
|
||||
|
||||
Obtain advanced access to the required permissions mentioned below for your Facebook app
|
||||
```
|
||||
instagram_manage_messages
|
||||
instagram_basic
|
||||
pages_show_list
|
||||
pages_manage_metadata
|
||||
pages_messaging
|
||||
business_management
|
||||
```
|
||||
|
||||
<Note>
|
||||
If your facebook app's version is more than 7.0 then you will need extra permission according to facebook's updated policy. Make sure you get permission for.
|
||||
```
|
||||
pages_read_engagement
|
||||
```
|
||||
</Note>
|
||||
|
||||
## Developing or Testing Facebook Integration in your machine
|
||||
|
||||
Install [ngrok](https://ngrok.com/docs) on your machine. This will be required since Facebook Messenger APIs will only communicate via https.
|
||||
|
||||
```bash
|
||||
brew cask install ngrok
|
||||
```
|
||||
|
||||
Configure ngrok to route to your Rails server port.
|
||||
|
||||
```bash
|
||||
ngrok http 3000
|
||||
```
|
||||
|
||||
Go to the Facebook developers page and navigate into your app settings. Add `localhost` as your app domain and add a privacy policy URL in the app settings.
|
||||
In the Webhook > Instagram settings shown in the above image, configure the callback url with the following value.
|
||||
|
||||
```bash
|
||||
{your_ngrok_url}/webhooks/instagram
|
||||
```
|
||||
|
||||
Update verify token in your Chatwoot environment variables.
|
||||
|
||||
You will also have to add a Facebook page to your `Access Tokens` section in your Messenger settings page.
|
||||
Restart the Chatwoot local server. Then, your Chatwoot setup will be ready to receive Facebook messages.
|
||||
|
||||
## Test your local Setup
|
||||
|
||||
1. After finishing the setup above, [create a Messenger inbox](https://www.chatwoot.com/hc/user-guide/articles/1677778588-how-to-setup-a-facebook-channel) after logging in to your Chatwoot Installation.
|
||||
2. Send a message to your Facebook Page from your Instagram account.
|
||||
3. Wait and confirm incoming requests to `/webhooks/instagram` endpoint in your ngrok screen.
|
||||
4. You can also verify your callback URL by clicking on Test for the subscribed Instagram fields.
|
||||
Go to webhook Instagram and click on Test with `v11.0`
|
||||
|
||||
|
||||
<Note>
|
||||
You can have only one app connected to the Chatwoot for Instagram and Facebook combined as the Messenger platform is common. But suppose you want to have separate channels for Instagram and Facebook. In that case, you can have multiple Facebook pages inside your app that would be connected to Facebook users and Instagram users separately and then connected to the different inbox in the Chatwoot page.
|
||||
</Note>
|
||||
|
||||
## Checklist
|
||||
|
||||
1. Integrate the Facebook test app and Send a message from the Instagram tester to the connected account.
|
||||
2. Make sure your Instagram account is a business account.
|
||||
3. If the Instagram test account can receive the message and forward it to the webhook URL, then submit it for review.
|
||||
4. If the Instagram test account is not able to receive the message and forward it to the webhook URL
|
||||
- Check the logs if you are receiving the message to `{your-app-url}/webhooks/Instagram`
|
||||
- If the logs are present for the above endpoint, if there are any errors, then reach out to us. We will help you out.
|
||||
- If the logs aren't present for the above endpoint, then raise a bug for the Facebook team or follow this bug https://developers.facebook.com/support/bugs/468852858104743/
|
||||
5. If you are not facing the above issue and can get the message, but the review isn't passing, then reach out to the reviewer.
|
||||
- When your app gets rejected, open the rejected submission. You can see the messenger icon in the bottom right corner to support you with your rejected review.
|
||||
- You can talk to the support team and ask your questions about the submission and the reason for the rejection.
|
||||
6. If your test app passed the review, it's good to go into production.
|
||||
7. If you face an issue on production that you cannot receive the messages, then reach out to us with the error logs.
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: Instagram via Instagram Business Login
|
||||
description: Set up Instagram integration using Instagram Business Login authentication (recommended method)
|
||||
sidebarTitle: Instagram via Instagram Business Login
|
||||
---
|
||||
|
||||
<Note>
|
||||
Please ensure you have installed version v4.1 or above. If not, please refer to this [guide](./instagram-channel-setup) for the Facebook Login method.
|
||||
</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. A valid facebook account.
|
||||
2. A valid instagram professional account.
|
||||
|
||||
## Register A Facebook App
|
||||
|
||||
To use Instagram Channel, you have to create a Facebook app in the developer portal. You can find more details about creating Facebook apps [here](./facebook-channel-setup).
|
||||
|
||||
1. Click on the "Create App" button
|
||||
|
||||
|
||||
|
||||
2. Select the option "Other".
|
||||
|
||||
|
||||
|
||||
3. For the app type, choose "Business"
|
||||
|
||||
|
||||
|
||||
4. Add app name and connect business account
|
||||
|
||||
|
||||
|
||||
5. Add Instagram product from the Home page.
|
||||
|
||||
|
||||
|
||||
## Configure Instagram settings for Chatwoot
|
||||
|
||||
1. Copy Instagram app ID and Instagram app secret
|
||||
|
||||
|
||||
|
||||
2. Add the Instagram app ID and Instagram app secret to your app config via `{Chatwoot installation url}/super_admin/app_config?config=instagram`
|
||||
|
||||
|
||||
|
||||
3. Configure Webhooks
|
||||
|
||||
Set the callback URL to `{your_chatwoot_url}/webhooks/instagram`. The verify token should match your `INSTAGRAM_VERIFY_TOKEN`, which can be configured through `app_config`
|
||||
|
||||
|
||||
|
||||
Subscribe to `messages`, `messaging_seen`, and `message_reactions` events.
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
To receive web hooks, app mode should be set to "Live".
|
||||
</Note>
|
||||
|
||||
4. Set up Instagram business login
|
||||
|
||||
Set Redirect URL as `{your_chatwoot_url}/instagram/callback`
|
||||
|
||||
|
||||
|
||||
5. Create a new Instagram tester account
|
||||
|
||||
## Create Instagram Inbox
|
||||
|
||||
Head over to Chatwoot and create a Instagram inbox. Please refer to this [guide](https://chatwoot.help/hc/user-guide/articles/1744361165-how-to-setup-an-instagram-channel-via-instagram-login) for more details on creating a Instagram inbox in Chatwoot.
|
||||
|
||||
## How to test the Instagram before going to live
|
||||
|
||||
1. Add Instagram Testers by clicking "Add People" button.
|
||||
|
||||
|
||||
|
||||
2. Make sure that you have selected the role Instagram Tester while creating a new tester.
|
||||
|
||||
|
||||
|
||||
## Going into production.
|
||||
|
||||
Before you can start using your Facebook app in production, you will have to get it verified by Facebook. Refer to the [docs](https://developers.facebook.com/docs/messenger-platform/instagram/app-review) on getting your app verified.
|
||||
|
||||
## Troubleshooting & Common Errors
|
||||
|
||||
### Insufficient Developer Role Error
|
||||
|
||||
Ensure the Instagram user is added as a developer: `Meta Dashboard → App Roles → Roles → Add People → Enter Instagram ID`
|
||||
|
||||
### API Access Deactivated
|
||||
|
||||
Ensure the **Privacy Policy URL** is valid and correctly set.
|
||||
|
||||
### Invalid request: Request parameters are invalid: Invalid redirect_uri
|
||||
|
||||
Please configure the Frontend URL. The Frontend URL does not match the authorization URL.
|
||||
|
||||
### Instagram Channel creation Error: Failed to exchange token
|
||||
|
||||
Please make sure that tester account has been added to the facebook app settings.
|
||||
|
||||
### 400: Session Invalid when connecting the instagram channel
|
||||
|
||||
This might be issue from facebook side. Please try again after some time.
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Setting Up Linear Integration
|
||||
description: Configure Linear integration to track issues and features from Chatwoot
|
||||
sidebarTitle: Linear
|
||||
---
|
||||
|
||||
Setting up Chatwoot Linear integration involves 5 steps.
|
||||
|
||||
1. Create a Linear app in the [developer portal](https://linear.app/settings/api/applications/new).
|
||||
2. Add necessary details and save the app.
|
||||
3. Configure Chatwoot with the `Client ID` and `Signing Secret` obtained from the Linear app.
|
||||
4. Open Chatwoot UI, navigate to integrations, select Linear, and click connect.
|
||||
5. Voila! You should now be able to use Linear in your Chatwoot account.
|
||||
|
||||
## Register and configure the Linear app
|
||||
|
||||
To use Linear Integration, you need to create a Linear app in the developer portal. You can find more details about creating Linear apps at the [Linear developer portal](https://developers.linear.app/docs/oauth/authentication).
|
||||
|
||||
1. Create a Linear app.
|
||||
2. Obtain the `Client ID` and `Client Secret` for the app and configure it in your app config via `{Chatwoot installation url}/super_admin/app_config?config=linear`
|
||||
3. The callback URL should be `{Chatwoot installation url}/linear/callback`.
|
||||
4. Toggle the `Public` switch to make the app public.
|
||||
|
||||
|
||||
|
||||
## Configure Linear app config
|
||||
|
||||
Obtain the `Client ID` and `Client Secret` for the app and configure it in your app config via `{Chatwoot installation url}/super_admin/app_config?config=linear`. These values will be available when you create the app in the developer portal.
|
||||
|
||||
```bash
|
||||
LINEAR_CLIENT_ID=
|
||||
LINEAR_SIGNING_SECRET=
|
||||
```
|
||||
|
||||
Restart the Chatwoot server.
|
||||
|
||||
<Note>
|
||||
Linear will only show up in the integrations section once you have configured these values and restarted the server.
|
||||
</Note>
|
||||
|
||||
## Connect Chatwoot with your Linear account
|
||||
|
||||
Follow this [guide](https://chatwoot.help/hc/user-guide/articles/1739949089-how-to-track-issues-and-features-with-linear-integration) to complete the Linear integration.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Setting Up Shopify Integration
|
||||
description: Configure Shopify integration to track orders and customer information from Chatwoot
|
||||
sidebarTitle: Shopify
|
||||
---
|
||||
|
||||
Setting up Chatwoot Shopify integration involves 5 steps.
|
||||
|
||||
1. Create a Shopify app in the [shopify partner dashboard](https://partners.shopify.com/).
|
||||
2. Add necessary details and save the app.
|
||||
3. Configure Chatwoot with the `Client ID` and `Client secret` obtained from the Shopify app.
|
||||
4. Open Chatwoot UI, navigate to integrations, select Shopify, and click connect.
|
||||
5. Voila! You should now be able to use Shopify in your Chatwoot account.
|
||||
|
||||
## Register and configure the Shopify app
|
||||
|
||||
To use Shopify Integration, you need to create a Shopify app in the [shopify partner dashboard](https://partners.shopify.com/). You can find more details about creating Shopify apps at the [Shopify developer portal](https://shopify.dev/docs/apps/build).
|
||||
|
||||
1. Create a Shopify app.
|
||||
|
||||
|
||||
|
||||
2. Obtain the `Client ID` and `Client Secret` for the app and configure it in your app config via `{Chatwoot installation url}/super_admin/app_config?config=shopify`
|
||||
|
||||
|
||||
|
||||
3. Configure the redirect URL as `{Chatwoot installation url}/shopify/callback` in app configuration.
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
Shopify will only show up in the integrations section once you have configured these values.
|
||||
</Note>
|
||||
|
||||
## Connect Chatwoot with your Shopify account
|
||||
|
||||
Follow this [guide](https://chatwoot.help/hc/user-guide/articles/1742395545-how-to-track-orders-with-shopify-integration) to complete the Shopify integration.
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: Setting Up Slack Integration
|
||||
description: Configure Slack integration to receive Chatwoot conversations in Slack channels
|
||||
sidebarTitle: Slack
|
||||
---
|
||||
|
||||
Setting up Chatwoot Slack integration involves 5 steps.
|
||||
|
||||
1. Create a slack app in the developer portal.
|
||||
2. Add necessary permissions for the slack app.
|
||||
3. Configure Chatwoot with the `client ID` and `client Secret` obtained from the slack app.
|
||||
4. Open Chatwoot UI, navigate to integrations, Slack and click connect.
|
||||
5. Voila! You should be receiving new conversations in the #customer-conversations channel in Slack.
|
||||
|
||||
## Register a Slack app
|
||||
|
||||
To use Slack Integration, you have to create a Slack app in the developer portal. You can find more details about creating Slack apps at the [Slack developer portal](https://api.slack.com/).
|
||||
|
||||
Once you register your Slack App, you will have to obtain the `Client Id` and `Client Secret`. These values will be available in the app settings and will be required while setting up Chatwoot environment variables.
|
||||
|
||||
## Configure the Slack app
|
||||
|
||||
1. Create a Slack app and add it to your development workspace.
|
||||
2. Obtain the `Client Id` and `Client Secret` for the app and configure it in your Chatwoot [environment variables](/docs/self-hosted/configuration/environment-variables).
|
||||
3. Head over to the `OAuth & permissions` section under `features` tab.
|
||||
4. In the redirect URLs, Add your Chatwoot installation base URL.
|
||||
5. In the scopes section configure the given scopes for bot token scopes:
|
||||
- `channels:history`
|
||||
- `channels:join`
|
||||
- `channels:manage`
|
||||
- `channels:read`
|
||||
- `chat:write`
|
||||
- `chat:write.customize`
|
||||
- `commands`
|
||||
- `files:read`
|
||||
- `files:write`
|
||||
- `groups:history`
|
||||
- `groups:write`
|
||||
- `im:history`
|
||||
- `im:write`
|
||||
- `links:read`
|
||||
- `links:write`
|
||||
- `mpim:history`
|
||||
- `mpim:write`
|
||||
- `users:read`
|
||||
- `users:read.email`
|
||||
7. In the user access token section subscribe to: `files:read`, `files:write`, `remote_files:share`
|
||||
8. Head over to the `Events Subscriptions` section in the `Features` tab.
|
||||
9. Enable events and configure the given request url `{Chatwoot installation url}/api/v1/integrations/webhooks`
|
||||
10. Subscribe to the following bot events: `link_shared`, `message.channels`, `message.groups`, `message.im`, `message.mpim`.
|
||||
11. Add the installation URL as `domain` under the `App unfurl domains section` to display meta information about the conversation when the conversation URL is shared.
|
||||
12. Connect Slack integration on Chatwoot app and get productive.
|
||||
|
||||
## Configure the environment variables in Chatwoot
|
||||
|
||||
Obtain the `Client ID` and `Client Secret` for the app and configure it in your Chatwoot [environment variables](/docs/self-hosted/configuration/environment-variables).These values will be available under `Settings` > `Basic Information`.
|
||||
|
||||
```bash
|
||||
SLACK_CLIENT_ID=
|
||||
SLACK_CLIENT_SECRET=
|
||||
```
|
||||
|
||||
Restart the Chatwoot server.
|
||||
|
||||
<Note>
|
||||
Slack will only show up in the integrations section once you have configured these values and restarted the server.
|
||||
</Note>
|
||||
|
||||
## Connect Chatwoot with your Slack workspace
|
||||
|
||||
Follow this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677774874-how-to-answer-conversations-from-slack) to complete the Slack integration.
|
||||
|
||||
## Testing your setup
|
||||
|
||||
1. Create a new conversation.
|
||||
2. Ensure that you are receiving the Chatwoot messages in the connected slack channel.
|
||||
3. Add a message to that thread and ensure that it is coming back on to Chatwoot.
|
||||
4. Add `note:` or `private:` in front of the Slack message to see if it is coming out as private notes.
|
||||
5. If your Slack member's email matches their email on Chatwoot, the messages will be associated with their Chatwoot user account.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: APM and Tracing
|
||||
description: Configure APM and error monitoring tools for Chatwoot
|
||||
sidebarTitle: APM and Tracing
|
||||
---
|
||||
|
||||
Chatwoot supports various APM and monitoring tools.
|
||||
You can enable them by configuring the given environment variables.
|
||||
|
||||
## [Sentry](https://sentry.io/)
|
||||
|
||||
Provide your `sentry dsn`.
|
||||
|
||||
```bash
|
||||
SENTRY_DSN=
|
||||
```
|
||||
|
||||
## [Scout](https://scoutapm.com)
|
||||
Provide values for the following environment variables. Refer [scout documentation](https://scoutapm.com/docs/ruby/configuration) for additional options.
|
||||
```bash
|
||||
## https://scoutapm.com/docs/ruby/configuration
|
||||
# SCOUT_KEY=YOURKEY
|
||||
# SCOUT_NAME=YOURAPPNAME (Production)
|
||||
# SCOUT_MONITOR=true
|
||||
```
|
||||
|
||||
## [NewRelic](https://newrelic.com/)
|
||||
Enable Newrelic by configuring the license key. Refer [newrelic documentation](https://docs.newrelic.com/docs/agents/ruby-agent/configuration/ruby-agent-configuration/) for additional options.
|
||||
|
||||
```bash
|
||||
# https://docs.newrelic.com/docs/agents/ruby-agent/configuration/ruby-agent-configuration/
|
||||
# NEW_RELIC_LICENSE_KEY=
|
||||
```
|
||||
|
||||
## [DataDog](https://www.datadoghq.com/)
|
||||
|
||||
Datadog requires an agent running on the host machine to which the tracing library can send data. Chatwoot ruby code contains the tracing library, but you need to configure the agent in your host machine/docker environment for the integration to work.
|
||||
|
||||
Enable Datadog in chatwoot by configuring the `trace agent url`.
|
||||
|
||||
```bash
|
||||
## https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#environment-variables
|
||||
# DD_TRACE_AGENT_URL=http://localhost:8126
|
||||
```
|
||||
|
||||
### Running Datadog agent in local via docker
|
||||
```bash
|
||||
# to run in your local machine binding to port 8126
|
||||
# replace <dd API key> and dd_site as required
|
||||
|
||||
docker run -d --name dd-agent -v /var/run/docker.sock:/var/run/docker.sock:ro -v /proc/:/host/proc/:ro -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro -p 8126:8126 -e DD_API_KEY=<dd api key> -e DD_SITE="datadoghq.com" gcr.io/datadoghq/agent:7
|
||||
```
|
||||
|
||||
Refer Datadog documentation to install the agent in specific environments like [Ubuntu](https://docs.datadoghq.com/agent/basic_agent_usage/ubuntu/?tab=agentv6v7), [Docker](https://docs.datadoghq.com/agent/docker/?tab=standard), [kubernetes](https://docs.datadoghq.com/agent/kubernetes/?tab=helm) etc.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Rate Limiting
|
||||
description: Configure rate limiting to protect your Chatwoot installation from abuse
|
||||
sidebarTitle: Rate Limiting
|
||||
---
|
||||
|
||||
To protect the system from abusive requests, Chatwoot makes use of [`rack_attack`](https://github.com/rack/rack-attack) gem.
|
||||
You could customize the configuration to suit your needs by updating, [`config/initializers/rack_attack.rb`](https://github.com/chatwoot/chatwoot/blob/develop/config/initializers/rack_attack.rb)
|
||||
|
||||
## Default Rate Limits
|
||||
|
||||
- Chatwoot will throttles requests by IP at `60rpm`, Unless the request is from an allowed IP `['127.0.0.1', '::1']`
|
||||
- Signup Requests are limited by IP at `5 requests` per `5 minutes`.
|
||||
- SignIn Requests are limited by IP at `5 requests` per `20 seconds`.
|
||||
- SignIn Requests are limited by email address at `20 requests` per `5 minutes` for a specific email.
|
||||
- Reset Password Requests are limited at `5 requests` per `1 hour` for a specific email.
|
||||
|
||||
## Attachment Restrictions
|
||||
|
||||
- `Contact/Inbox Avatar` attachment file types are limited to jpeg, gif and png.
|
||||
- `Contact/Inbox Avatar` attachment file size is limited to 15MB.
|
||||
- `Website Channel` message attachments are limited to types ['image/png', 'image/jpeg', 'image/gif', 'image/bmp', 'image/tiff', 'application/pdf', 'audio/mpeg', 'video/mp4', 'audio/ogg', 'text/csv']
|
||||
- `Website Channel` message attachments are limited to 40MB size limit.
|
||||
|
||||
## Disabling Rack attack on your instance
|
||||
|
||||
You can control the behaviour of rack attack in your instance via the following environment variables.
|
||||
|
||||
```bash
|
||||
## Rack Attack configuration
|
||||
## To prevent and throttle abusive requests.
|
||||
# Disable if you are getting too many request errors for custom use cases
|
||||
# ENABLE_RACK_ATTACK=true
|
||||
# Control the allowed number of requests
|
||||
# RACK_ATTACK_LIMIT=300
|
||||
# Control whether you want to enable rack attack for widget APIs
|
||||
# ENABLE_RACK_ATTACK_WIDGET_API=true
|
||||
```
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Super Admin Console
|
||||
description: Guide to accessing and using the Super Admin Console and Sidekiq monitoring
|
||||
sidebarTitle: Super Admin Console
|
||||
---
|
||||
|
||||
You will need a user account with super admin privileges to access the super admin console and Sidekiq console.
|
||||
|
||||
<Note>
|
||||
The first user created during onboarding is a `super admin`.
|
||||
</Note>
|
||||
|
||||
## Access superadmin console
|
||||
|
||||
- Access `<chatwoot-installation-url>/super_admin`.
|
||||
|
||||
## Creating new super admins
|
||||
|
||||
- Use the super admin console and navigate to the user's section
|
||||
- Click on the new user button, fill in the details, and select the type to be `super admin`
|
||||
|
||||
## Access Sidekiq via the super admin console
|
||||
|
||||
- Access `<chatwoot-installation-url>/super_admin`.
|
||||
- Authenticate using the admin credentials created during the installation.
|
||||
- You can access the Sidekiq option on the sidebar.
|
||||
|
||||
## Access Rails console
|
||||
|
||||
Run the following command in your console from the root folder of your Chatwoot Rails app.
|
||||
|
||||
```bash
|
||||
RAILS_ENV=production bundle exec rails c
|
||||
```
|
||||
If you have `cwctl`, use `cwctl --console`.
|
||||
|
||||
- If you running Chatwoot in a Docker container, you would need to access the shell inside your container first.
|
||||
- If you are running Chatwoot on Caprover, use the following command to access the command line.
|
||||
```bash
|
||||
docker exec -it $(docker ps --filter name=srv-captain--chatwoot-web -q) /bin/sh
|
||||
```
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: Cloudfront CDN
|
||||
description: Configure Cloudfront as a CDN for Chatwoot assets
|
||||
sidebarTitle: Cloudfront CDN
|
||||
---
|
||||
|
||||
This document helps you to configure Cloudfront as the asset host for Chatwoot. If you have a high traffic website, we would recommend setting up a CDN for Chatwoot.
|
||||
|
||||
## Configure a Cloudfront distribution
|
||||
|
||||
**Step 1**: Create a Cloudfront distribution.
|
||||
|
||||
|
||||
|
||||
**Step 2**: Select "Web" as delivery method for your content.
|
||||
|
||||
|
||||
|
||||
**Step 3**: Configure the Origin Settings as the following.
|
||||
|
||||
|
||||
|
||||
- Provide your Chatwoot Installation URL under Origin Domain Name.
|
||||
- Select "Origin Protocol Policy" as Match Viewer.
|
||||
|
||||
**Step 4**: Configure Cache behaviour.
|
||||
|
||||
|
||||
|
||||
- Configure **Allowed HTTP methods** to use *GET, HEAD, OPTIONS*.
|
||||
- Configure **Cache and origin request settings** to use *Use legacy cache settings*.
|
||||
- Select **Whitelist** for *Cache Based on Selected Request Headers*.
|
||||
- Add the following headers to the **Whitelist Headers**.
|
||||
|
||||
- **Access-Control-Request-Headers**
|
||||
- **Access-Control-Request-Method**
|
||||
- **Origin**
|
||||
- Set the **Response headers policy** to **CORS-With-Preflight**
|
||||
|
||||
**Step 5**: Click on **Create Distribution**. You will be able to see the distribution as shown below. Use the **Domain name** listed in the details as the **ASSET_CDN_HOST** in Chatwoot.
|
||||
|
||||
|
||||
|
||||
## Add ASSET_CDN_HOST in Chatwoot
|
||||
|
||||
Your Cloudfront URL will be of the format `<distribution>.cloudfront.net`.
|
||||
|
||||
Set
|
||||
|
||||
```bash
|
||||
ASSET_CDN_HOST=<distribution>.cloudfront.net
|
||||
```
|
||||
|
||||
in the environment variables.
|
||||
|
||||
## Benefits of Using CDN
|
||||
|
||||
<Tip>
|
||||
Using a CDN provides several benefits for your Chatwoot installation:
|
||||
</Tip>
|
||||
|
||||
1. **Faster Asset Loading**: Assets are served from edge locations closer to users
|
||||
2. **Reduced Server Load**: Static assets are served from CDN, reducing load on your application server
|
||||
3. **Better User Experience**: Faster page load times improve user experience
|
||||
4. **Global Availability**: Assets are cached globally for users worldwide
|
||||
5. **Bandwidth Savings**: Reduces bandwidth usage on your origin server
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### CORS Issues
|
||||
|
||||
If you encounter CORS issues after setting up CloudFront:
|
||||
|
||||
1. Ensure the CORS headers are properly configured in CloudFront
|
||||
2. Verify that your `CORS_ORIGINS` environment variable includes your CDN domain:
|
||||
|
||||
```bash
|
||||
CORS_ORIGINS=https://yourdomain.com,https://d1234567890.cloudfront.net
|
||||
```
|
||||
|
||||
### Cache Invalidation
|
||||
|
||||
To invalidate CloudFront cache after updating assets:
|
||||
|
||||
1. Go to CloudFront console
|
||||
2. Select your distribution
|
||||
3. Create an invalidation for `/*` to clear all cached assets
|
||||
|
||||
### SSL Certificate
|
||||
|
||||
For custom domain names with CloudFront:
|
||||
|
||||
1. Request an SSL certificate in AWS Certificate Manager (ACM)
|
||||
2. Configure the certificate in your CloudFront distribution
|
||||
3. Update your DNS to point to the CloudFront distribution
|
||||
|
||||
<Note>
|
||||
SSL certificates for CloudFront must be requested in the US East (N. Virginia) region regardless of where your distribution is located.
|
||||
</Note>
|
||||
@@ -0,0 +1,108 @@
|
||||
---
|
||||
title: Optimizing Configurations
|
||||
description: Performance optimization guide for Chatwoot self-hosted deployments
|
||||
sidebarTitle: Optimizing Configurations
|
||||
---
|
||||
|
||||
This document helps you to fine-tune various configuration values available in Chatwoot to extract the maximum performance out of your Chatwoot Installation.
|
||||
|
||||
## Puma
|
||||
Chatwoot uses [Puma](https://puma.io/) as its Webserver. So let's start with a brief introduction to Puma workers and threads.
|
||||
|
||||
Puma is a popular web server for Ruby on Rails applications, and it uses multiple workers and threads to handle incoming requests. Each Worker runs its own instance of the application, and each thread within a worker can handle a single request at a time.
|
||||
|
||||
Now, let's move on to how you can configure Puma workers and threads using environment variables.
|
||||
|
||||
|
||||
### Workers
|
||||
Each Puma worker is a separate process that runs an instance of the Ruby application. Each Worker has its own event loop that can handle incoming requests concurrently using multiple threads.
|
||||
|
||||
When the Puma server receives a request, it is assigned to a worker process in a round-robin fashion. Once a worker receives a request, it assigns the request to an available thread within its process. Each thread then handles the request, including any required database queries, calculations, and other processing tasks. Using multiple worker processes allows Puma to handle multiple requests concurrently without blocking other requests or causing a bottleneck.
|
||||
|
||||
#### Configuring the number of workers
|
||||
|
||||
The `WEB_CONCURRENCY` environment variable can be used to configure the number of workers in Puma. It's important to consider the number of available CPU cores and aim for a ratio of workers to cores that allows the server to run at maximum capacity without causing performance issues. It's recommended to have a number of workers that matches or is slightly less than the number of available CPU cores to avoid competition for CPU time, which can lead to performance issues.
|
||||
|
||||
|
||||
```
|
||||
WEB_CONCURRENCY=2
|
||||
```
|
||||
|
||||
<Note>
|
||||
The default configuration in Chatwoot for `WEB_CONCURRENCY` is `0`. I.e. it runs one Worker. This is to ensure the application works on machines with a lower configuration. If you run Chatwoot on machines with higher specs, fine-tune this configuration accordingly.
|
||||
</Note>
|
||||
|
||||
|
||||
### Threads
|
||||
|
||||
Each Puma thread is a lightweight execution context that can handle a single request at a time. When a worker process receives a request, it is assigned to an available thread within that process. Each thread then handles the request, including any required database queries, calculations, and other processing tasks.
|
||||
|
||||
Using multiple threads can increase concurrency and performance, but balancing the number of threads with the available CPU resources is essential to avoid competition for CPU time. The number of threads can be configured using the following environment variables.
|
||||
|
||||
```
|
||||
# Only required to configure if absolutely necessary
|
||||
# Defaults to Max threads value by default
|
||||
# RAILS_MIN_THREADS=5
|
||||
RAILS_MAX_THREADS=5
|
||||
```
|
||||
|
||||
<Note>
|
||||
The default configuration in Chatwoot for `RAILS_MAX_THREADS` values is `5`. You can fine-tune it based on your requirements. The value of `RAILS_MIN_THREADS` defaults to `RAILS_MAX_THREADS` unless a specific value is provided.
|
||||
</Note>
|
||||
|
||||
### Fine-tuning
|
||||
|
||||
TLDR: You can configure `WEB_CONCURRENCY` to the number of CPU cores and then fine-tune the number of `RAILS_MAX_THREADS` based on the available `memory` and `CPU` resources. While running the sidekiq and rails server on a single machine, consider the sidekiq configuration while determining these numbers.
|
||||
|
||||
|
||||
References:
|
||||
|
||||
- https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server
|
||||
- https://www.speedshop.co/2017/10/12/appserver.html
|
||||
- https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts#puma
|
||||
|
||||
|
||||
## Sidekiq
|
||||
|
||||
Sidekiq is a popular job processing library for Ruby on Rails applications. Chatwoot uses it as a simple and efficient way to execute background jobs asynchronously in the Rails application.
|
||||
|
||||
Sidekiq uses Redis to manage a job queue, allowing you to run multiple workers in parallel, each processing jobs from the queue. This makes it easy to distribute workloads and handle large volumes of jobs without bogging down your Rails application's main thread.
|
||||
|
||||
You can configure the number of sidekiq workers using the following environment variables.
|
||||
|
||||
```
|
||||
# the default value in Chatwoot is 10
|
||||
SIDEKIQ_CONCURRENCY=10
|
||||
```
|
||||
|
||||
<Note>
|
||||
If you are running sidekiq on dedicated pods, you can fine-tune the `SIDEKIQ_CONCURRENCY` number to extract the maximum performance of the available CPU resources.
|
||||
</Note>
|
||||
|
||||
|
||||
## Database Connections
|
||||
|
||||
When a Ruby on Rails application is launched, it creates a pool of database connections that are stored in memory. These connections are established with the database server at the beginning of the application and are kept open throughout the life of the application. When a request is made to the application that requires access to the database, the application server will retrieve a connection from the pool and use it to process the request. Once the request is complete, the connection is returned to the pool to be used for future requests.
|
||||
|
||||
The size of the database pool in Chatwoot is configured automatically based on the values of `RAILS_MAX_THREADS` and `SIDEKIQ_CONCURRENCY`
|
||||
```
|
||||
https://github.com/chatwoot/chatwoot/blob/4d719a8fe33bed72ec57812e174dab1874315340/config/database.yml#L7
|
||||
```
|
||||
|
||||
Ref:
|
||||
- https://stackoverflow.com/questions/40412611/in-puma-how-do-i-calculate-db-connections
|
||||
|
||||
<Note>
|
||||
If you have a database server with higher resources available, you can leverage it by bumping up the number of rails and sidekiq pods so that more of the connection limit is being used.
|
||||
</Note>
|
||||
|
||||
|
||||
### FAQ
|
||||
|
||||
## Getting `ActiveRecord::ConnectionTimeoutError` errors.
|
||||
|
||||
There is a potential bug with Chatwoot's implementation of `rack-timeout`, in specific installations, which results in connections not being released properly. For the time being, you can set the following environment variable to disable `rack-timeout` if you are experiencing this.
|
||||
|
||||
```
|
||||
RACK_TIMEOUT_SERVICE_TIMEOUT=0
|
||||
```
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: GCS Bucket
|
||||
description: Configure Google Cloud Storage bucket as storage in Chatwoot
|
||||
sidebarTitle: GCS Bucket
|
||||
---
|
||||
|
||||
Chatwoot supports Google Cloud storage as the storage provider. To enable GCS in Chatwoot, follow the below mentioned steps.
|
||||
|
||||
Set google as the active storage service in the environment variables
|
||||
|
||||
```bash
|
||||
ACTIVE_STORAGE_SERVICE='google'
|
||||
```
|
||||
|
||||
## Get project ID variable
|
||||
|
||||
Login to your Google Cloud console. On your home page of your project you will be able to see the project id and project name as follows.
|
||||
|
||||
|
||||
|
||||
```bash
|
||||
GCS_PROJECT=your-project-id
|
||||
```
|
||||
|
||||
## Setup GCS Bucket
|
||||
|
||||
Go to Storage -> Browser. Click on "Create Bucket". You will be presented with a screen as shown below. Select the default values and continue.
|
||||
|
||||
|
||||
|
||||
Once this is done you will get the bucket name. Set this as GCS_BUCKET.
|
||||
|
||||
```bash
|
||||
GCS_BUCKET=your-bucket-name
|
||||
```
|
||||
|
||||
## Setup a service account
|
||||
|
||||
Go to `Identity & Services -> Identity -> Service Accounts`. Click on "Create Service Account".
|
||||
|
||||
Provice a name and an ID for the service account, click on create. You will be asked to "Grant this service account access to the project" Select Cloud Storage -> Storage Admin as shown below.
|
||||
|
||||
|
||||
|
||||
## Add service account to the bucket
|
||||
|
||||
Go to Storage -> Browser -> Your bucket -> Permissions. Click on add. On "New members" field select the service account you just created.
|
||||
|
||||
Select role as `Cloud Storage -> Storage Admin` and save.
|
||||
|
||||
|
||||
|
||||
## Generate a key for the service account
|
||||
|
||||
Go to `Identity & Services -> Identity -> Service Accounts -> Your service account`. There is a section called **Keys**. Click on **Add Key**. You will be presented with an option like the one below. Select JSON from the option.
|
||||
|
||||
|
||||
|
||||
Copy the json file content and set it as GCS_CREDENTIALS
|
||||
|
||||
A sample credential file is of the following format.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "service_account",
|
||||
"project_id": "",
|
||||
"private_key_id": "",
|
||||
"private_key": "",
|
||||
"client_email": "",
|
||||
"client_id": "",
|
||||
"auth_uri": "",
|
||||
"token_uri": "",
|
||||
"auth_provider_x509_cert_url": "",
|
||||
"client_x509_cert_url": ""
|
||||
}
|
||||
```
|
||||
|
||||
When pasting the credentials to the ENV file, make sure to remove the new lines and paste it into a single line.
|
||||
```bash
|
||||
GCS_CREDENTIALS={"type": "service_account","project_id": "","private_key_id": "","private_key": "","client_email": "","client_id": "","auth_uri": "","token_uri": "","auth_provider_x509_cert_url": "","client_x509_cert_url": ""}
|
||||
```
|
||||
|
||||
<Note>
|
||||
If you are running Chatwoot v2.17+, make sure to wrap `GCS_CREDENTIALS` in single quotes.
|
||||
</Note>
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
title: S3 Bucket
|
||||
description: Configure Amazon S3 bucket as storage in Chatwoot
|
||||
sidebarTitle: S3 Bucket
|
||||
---
|
||||
|
||||
## Using Amazon S3
|
||||
|
||||
You can get started with [Creating an S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [Create an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) to configure the following details.
|
||||
|
||||
Configure the following env variables.
|
||||
|
||||
```bash
|
||||
ACTIVE_STORAGE_SERVICE='amazon'
|
||||
S3_BUCKET_NAME=
|
||||
AWS_ACCESS_KEY_ID=
|
||||
AWS_SECRET_ACCESS_KEY=
|
||||
AWS_REGION=
|
||||
```
|
||||
|
||||
## S3 Bucket policy
|
||||
|
||||
Inorder to use S3 bucket in Chatwoot, a policy has to be set with the correct credentials. A sample policy is given below, as the listed actions are required for the storage to work.
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Id": "Policyxxx",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "Stmtxxx",
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"AWS": "your-user-arn"
|
||||
},
|
||||
"Action": [
|
||||
"s3:DeleteObject",
|
||||
"s3:GetObject",
|
||||
"s3:ListBucket",
|
||||
"s3:PutObject"
|
||||
],
|
||||
"Resource": [
|
||||
"arn:aws:s3:::your-bucket-name",
|
||||
"arn:aws:s3:::your-bucket-name/*"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Replace your *bucket name* in the appropriate places.
|
||||
|
||||
**User ARN** can be found using the following steps:
|
||||
|
||||
1. Login to AWS Console. Go to IAM, and click on Users from the left sidebar. You will be to see the list of users as follows.
|
||||
|
||||
|
||||
|
||||
2. Click on the user, you will be to see a screen as shown below. Copy the User ARN and paste it in the above policy.
|
||||
|
||||
|
||||
|
||||
**Add CORS Configuration on your S3 buckets**
|
||||
|
||||
You need to configure CORS settings to the respective storage cloud to support Direct file uploads from the widget and the Chatwoot dashboard.
|
||||
|
||||
Refer to this link for more information: https://edgeguides.rubyonrails.org/active_storage_overview.html#cross-origin-resource-sharing-cors-configuration
|
||||
|
||||
To make CORS configuration changes on S3:
|
||||
|
||||
1. Go to your S3 bucket
|
||||
2. Click on the permissions tab.
|
||||
3. Scroll to Cross-origin resource sharing (CORS) and click on `Edit` and add the respective changes shown below.
|
||||
|
||||
|
||||
|
||||
Add your Chatwoot URL to the `AllowedOrigin` as shown below.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"AllowedHeaders": [
|
||||
"*"
|
||||
],
|
||||
"AllowedMethods": [
|
||||
"PUT",
|
||||
"POST",
|
||||
"DELETE",
|
||||
"GET"
|
||||
],
|
||||
"AllowedOrigins": [
|
||||
"<add-your-domain-here eg: https://app.chatwoot.com>"
|
||||
],
|
||||
"ExposeHeaders": [
|
||||
"Origin",
|
||||
"Content-Type",
|
||||
"Content-MD5",
|
||||
"Content-Disposition"
|
||||
],
|
||||
"MaxAgeSeconds": 3600
|
||||
}
|
||||
]
|
||||
```
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
title: Supported Providers
|
||||
description: Configure cloud storage providers for Chatwoot file storage
|
||||
sidebarTitle: Supported Providers
|
||||
---
|
||||
|
||||
# Configure Cloud Storage
|
||||
|
||||
Chatwoot uses [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) for storing attachments. The default storage option is local storage on your server, but you can configure cloud providers for better scalability and backup.
|
||||
|
||||
<Tip>
|
||||
It is recommended to use a cloud provider for your Chatwoot storage to ensure proper backup of stored attachments and prevent data loss.
|
||||
</Tip>
|
||||
|
||||
## Using Amazon S3
|
||||
|
||||
You can get started with [Creating an S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [Create an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) to configure the following details.
|
||||
|
||||
Configure the following env variables.
|
||||
|
||||
```bash
|
||||
ACTIVE_STORAGE_SERVICE=amazon
|
||||
S3_BUCKET_NAME=
|
||||
AWS_ACCESS_KEY_ID=
|
||||
AWS_SECRET_ACCESS_KEY=
|
||||
AWS_REGION=
|
||||
```
|
||||
|
||||
## Using Google GCS
|
||||
|
||||
<Note>
|
||||
Starting with version 2.17+, wrap the `GCS_CREDENTIALS` environment variable in single quotes.
|
||||
</Note>
|
||||
|
||||
Configure the following env variables.
|
||||
|
||||
```bash
|
||||
ACTIVE_STORAGE_SERVICE=google
|
||||
GCS_PROJECT=
|
||||
GCS_CREDENTIALS=
|
||||
GCS_BUCKET=
|
||||
```
|
||||
|
||||
The value of the `GCS_CREDENTIALS` should be a json formatted string containing the following keys.
|
||||
|
||||
```bash
|
||||
{
|
||||
"type": "service_account",
|
||||
"project_id" : "",
|
||||
"private_key_id" : "",
|
||||
"private_key" : "",
|
||||
"client_email" : "",
|
||||
"client_id" : "",
|
||||
"auth_uri" : "",
|
||||
"token_uri" : "",
|
||||
"auth_provider_x509_cert_url" : "",
|
||||
"client_x509_cert_url" : ""
|
||||
}
|
||||
```
|
||||
When pasting the credentials to the ENV file, make sure to remove the new lines and paste it into a single line.
|
||||
|
||||
```bash
|
||||
GCS_CREDENTIALS={"type": "service_account","project_id": "","private_key_id": "","private_key": "","client_email": "","client_id": "","auth_uri": "","token_uri": "","auth_provider_x509_cert_url": "","client_x509_cert_url": ""}
|
||||
```
|
||||
|
||||
## Using Microsoft Azure
|
||||
|
||||
Configure the following env variables.
|
||||
|
||||
```bash
|
||||
ACTIVE_STORAGE_SERVICE=microsoft
|
||||
AZURE_STORAGE_ACCOUNT_NAME=
|
||||
AZURE_STORAGE_ACCESS_KEY=
|
||||
AZURE_STORAGE_CONTAINER=
|
||||
```
|
||||
|
||||
## Using Amazon S3 Compatible Service
|
||||
|
||||
To use an s3 compatible service such as [DigitalOcean Spaces](https://www.digitalocean.com/docs/spaces/resources/s3-sdk-examples/#configure-a-client), Minio etc..
|
||||
|
||||
Configure the following env variables.
|
||||
|
||||
```bash
|
||||
ACTIVE_STORAGE_SERVICE=s3_compatible
|
||||
STORAGE_BUCKET_NAME=
|
||||
STORAGE_ACCESS_KEY_ID=
|
||||
STORAGE_SECRET_ACCESS_KEY=
|
||||
STORAGE_REGION=nyc3
|
||||
STORAGE_ENDPOINT=https://nyc3.digitaloceanspaces.com
|
||||
#set force_path_style to true if using minio
|
||||
#STORAGE_FORCE_PATH_STYLE=true
|
||||
```
|
||||
Reference in New Issue
Block a user