Chatwoot

Chatwoot is an open-source customer support platform that consolidates conversations from email, live chat, Twitter, Facebook, WhatsApp, and more into a single inbox. It supports multiple agents, teams, labels, canned responses, and automation rules.

Getting Started

Go to Chatwoot on OSC to create your instance.

Prerequisites

  • An OSC account (sign up at app.osaas.io)
  • A PostgreSQL database instance
  • A Valkey (Redis-compatible) instance for real-time features and background jobs

Step-by-Step Setup

Step 1: Create a PostgreSQL Database

Chatwoot stores all conversations, contacts, and configuration in PostgreSQL. Create a Postgres Vector instance (compatible with Chatwoot's schema):

osc create pgvector-pgvector mypostgres

Note the connection URL — it looks like postgres://user:password@host:5432/db.

Step 2: Create a Valkey Instance

Valkey (Redis-compatible) is required for real-time chat, background jobs, and session caching:

osc create valkey-io-valkey myvalkey

Store the Valkey password as a service secret so you can reference it safely:

osc secret set valkey-password <your-valkey-password>

The Redis URL format is: redis://:password@host:6379

Step 3: Generate a Secret Key

Chatwoot requires a long random string for encrypting sessions and cookies. Generate one:

openssl rand -hex 64

Store it as a service secret:

osc secret set chatwoot-secret <generated-secret>

Step 4: Create the Chatwoot Instance

osc create chatwoot-chatwoot mychatwoot \
  -o DatabaseUrl="postgres://user:password@host:5432/db" \
  -o RedisUrl="redis://:{{secrets.valkey-password}}@host:6379" \
  -o SecretKeyBase="{{secrets.chatwoot-secret}}"

Step 5: Access Chatwoot and Create Admin Account

Once the instance is running, navigate to your Chatwoot URL. On first launch you will be prompted to create an admin account and your first team inbox.

Default credentials: Chatwoot has no pre-set defaults. You create your admin account on first launch via the setup wizard.

Optional Email Configuration

To enable email notifications and replies, configure SMTP settings when creating the instance:

osc create chatwoot-chatwoot mychatwoot \
  -o DatabaseUrl="..." \
  -o RedisUrl="..." \
  -o SecretKeyBase="..." \
  -o SmtpAddress="smtp.example.com" \
  -o SmtpPort="587" \
  -o SmtpUsername="you@example.com" \
  -o SmtpPassword="{{secrets.smtp-password}}" \
  -o MailerSenderEmail="support@example.com"

Usage Example

Connect to Chatwoot from your application using its REST API:

# List all conversations (replace with your instance URL and API token)
curl https://mychatwoot.auto.prod.osaas.io/api/v1/accounts/1/conversations \
  -H "api_access_token: <your-api-token>"

Obtain your API token from Profile Settings → Access Token in the Chatwoot UI.

Resources