Skip to main content

​
Quick Start Guide

Get your Chatwoot instance up and running in minutes. This guide will walk you through the essential steps to start managing customer conversations.
This guide assumes you already have a Chatwoot instance running. If you need to deploy Chatwoot first, visit chatwoot.com/deploy for deployment options.

​
Prerequisites

Before you begin, ensure you have:
  • A running Chatwoot instance (self-hosted or cloud)
  • Admin access to your Chatwoot installation
  • Email address for account creation
  • (Optional) A website domain if you plan to add live chat

​
Step 1: Create Your Account

1

Navigate to Chatwoot

Open your Chatwoot instance URL in your web browser (e.g., https://your-domain.com).
2

Sign Up

Click on Sign Up and fill in your details:
  • Full Name
  • Email Address
  • Password (secure password recommended)
If account signups are disabled (ENABLE_ACCOUNT_SIGNUP=false), contact your system administrator to create an account for you.
3

Create Your Account

After signing up, you’ll be prompted to create your first account:
  • Account Name: Your company or team name
  • Account Domain: Optional subdomain for your help center
This creates an Account object that serves as the container for all your data.
4

Verify Email

Check your email inbox for a verification link and confirm your email address.
In Chatwoot’s architecture, an Account represents your organization, while Users are team members who can access and manage conversations.

​
Step 2: Create Your First Inbox

Inboxes are channels through which customers can reach you. Let’s create your first inbox.
1

Navigate to Inbox Settings

From the sidebar, click Settings → Inboxes → Add Inbox
2

Choose a Channel Type

Select the channel you want to connect:

Website

Add live chat widget to your website

Email

Connect your support email address

Facebook

Connect Facebook Page for Messenger

WhatsApp

Connect WhatsApp Business API

Twitter

Connect Twitter profile for DMs

Telegram

Connect Telegram bot

SMS

Connect Twilio for SMS support

API Channel

Build custom integrations
3

Configure Channel Settings

Depending on your channel choice, provide the required details. For example:For Website Widget:
  • Website Name
  • Website Domain
  • Widget Color (optional)
  • Welcome Heading (optional)
For Email:
  • Email Address (e.g., [email protected])
  • IMAP/SMTP Settings
  • Forward incoming emails to Chatwoot
4

Configure Inbox Settings

Set up inbox-specific settings:
  • Inbox Name: Internal name for your team
  • Enable Auto Assignment: Automatically assign conversations to available agents
  • Enable CSAT: Ask customers for satisfaction ratings
  • Greeting Message: Welcome message for new conversations
  • Business Hours: Set your working hours
5

Add Team Members

Select which agents should have access to this inbox. You can add more agents later.

​
Example: Website Widget Setup

For a website widget, you’ll receive an installation script: 
<!-- Chatwoot Widget Script -->
<script>
  (function(d,t) {
    var BASE_URL="https://your-domain.com";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.chatwootSDK.run({
        websiteToken: 'your_website_token',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>
Add this script just before the closing </body> tag on every page where you want the chat widget to appear.

​
Step 3: Invite Team Members

Collaborate with your team by inviting agents to your account.
1

Go to Agents Settings

Navigate to Settings → Agents → Add Agent
2

Enter Agent Details

Fill in the agent information:
  • Name: Full name of the team member
  • Email: Their email address
  • Role: Choose from:
    • Agent: Can manage conversations
    • Administrator: Full access to settings and configuration
3

Assign to Inboxes

Select which inboxes this agent should have access to. Agents can only see conversations from their assigned inboxes.
4

Send Invitation

Click Add Agent. The team member will receive an email invitation to join your Chatwoot account.
Team members can also be organized into Teams for better workflow management. Navigate to Settings → Teams to create teams.

​
Step 4: Start Managing Conversations

Now you’re ready to handle customer conversations!
1

Access Your Inbox

Click Conversations in the sidebar to view your unified inbox with all customer messages.
2

View Conversations

Conversations are organized by status:
  • Open: Active conversations requiring attention
  • Pending: Awaiting customer response
  • Resolved: Closed conversations
  • Snoozed: Temporarily hidden conversations
Use filters to view:
  • Mine: Conversations assigned to you
  • Unassigned: Conversations without an assigned agent
  • All: Every conversation in the inbox
3

Respond to Customers

Click on a conversation to open it. You can:
  • Type and send messages
  • Add attachments (images, files)
  • Use Canned Responses for common replies
  • Add Private Notes for internal communication (use @mentions)
  • Apply Labels to categorize conversations
  • Change conversation Status (Open, Pending, Resolved)
  • Assign to team members
4

Use Keyboard Shortcuts

Speed up your workflow with keyboard shortcuts:
  • Press / to open the command bar
  • Cmd/Ctrl + K for quick navigation
  • R to resolve a conversation
  • E to send a reply
View all shortcuts by pressing ?

​
Step 5: Set Up Canned Responses

Save time by creating pre-written responses for common questions.
1

Navigate to Canned Responses

Go to Settings → Canned Responses → Add Canned Response
2

Create Response

  • Short Code: A quick shortcut (e.g., greeting, refund-policy)
  • Content: Your pre-written message
Example:
Short Code: welcome
Content: Hi there! Thanks for reaching out. How can I help you today?
3

Use in Conversations

In any conversation, type / followed by your short code (e.g., /welcome) to insert the canned response.

​
Step 6: Configure Auto-Assignment

Ensure conversations are automatically distributed to available agents.
1

Enable Auto-Assignment

Go to your Inbox Settings and toggle Enable Auto Assignment
2

Configure Assignment Rules

You can configure:
  • Round Robin: Distribute conversations evenly among agents
  • Agent Capacity: Set maximum conversations per agent
  • Online Status: Only assign to agents who are online
The auto-assignment service uses AutoAssignment::AgentAssignmentService (app/services/auto_assignment/agent_assignment_service.rb) to intelligently distribute conversations.

​
Step 7: Enable Customer Satisfaction (CSAT)

Measure customer satisfaction after conversations are resolved.
1

Enable CSAT in Inbox

Navigate to Inbox Settings → Enable CSAT Survey
2

Configure CSAT

Customize:
  • Survey message
  • Rating scale (1-5 stars)
  • Follow-up questions
3

View CSAT Reports

Access CSAT reports from Reports → CSAT to see customer satisfaction trends.

​
Next Steps

Explore Features

Discover advanced features like automation, labels, and teams

Set Up Automation

Create automation rules to handle repetitive tasks

Build Help Center

Create a self-service portal with articles and FAQs

Configure Integrations

Connect Slack, Dialogflow, and other tools

​
Common Configuration

​
Environment Variables

Key environment variables to configure (in .env file): 
# Application URL
FRONTEND_URL=https://your-domain.com

# Secret key for session security
SECRET_KEY_BASE=your_secure_key_here

# Redis connection
REDIS_URL=redis://localhost:6379

# Database connection
DATABASE_URL=postgresql://user:password@localhost/chatwoot

# Email configuration (for notifications)
SMTP_ADDRESS=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-app-password

# Enable/disable account signups
ENABLE_ACCOUNT_SIGNUP=true
Always use strong, unique values for SECRET_KEY_BASE. Generate one using: rails secret

​
Troubleshooting

  • Verify the script is added before </body> tag
  • Check browser console for JavaScript errors
  • Ensure FRONTEND_URL is correctly configured
  • Verify website domain matches inbox configuration
  • Verify IMAP/SMTP settings are correct
  • Check email forwarding rules
  • Ensure firewall allows connections
  • Check Chatwoot logs for email processing errors
  • Verify auto-assignment is enabled in inbox settings
  • Check that agents are added to the inbox
  • Ensure agents have availability status set to online
  • Review agent capacity limits

​
Need Help?

Documentation

Browse comprehensive guides and tutorials

Community Support

Join our Discord community for help

GitHub Issues

Report bugs or request features

API Documentation

Explore API endpoints for custom integrations
Congratulations! You’ve successfully set up Chatwoot and are ready to provide exceptional customer support. 🎉

Build docs developers (and LLMs) love

Get started for freeTalk to us