Service: Chatwoot - EyevinnOSC/community GitHub Wiki

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="[email protected]" \
  -o SmtpPassword="{{secrets.smtp-password}}" \
  -o MailerSenderEmail="[email protected]"

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.

Connecting Chatwoot to a My App via the AI Assistant

The OSC AI assistant (MCP) can automatically wire a Chatwoot live-chat widget into a custom app deployed via My Apps. When you run the Connect flow, the assistant:

  1. Authenticates with your Chatwoot instance using credentials stored in the live-chat parameter store
  2. Creates (or reuses) a website widget inbox scoped to your app's URL
  3. Returns an embed snippet you can paste into your app's HTML

This replaces the manual inbox setup described in Step 5 above for apps hosted on OSC.

Via MCP (AI Agent):

"Set up live chat on my app called myapp using my Chatwoot instance called mychatwoot"

The assistant uses the setup-live-chat tool chain. The Chatwoot instance must already be running and the live-chat parameter store must contain the admin password (set up during setup-live-chat initialization).

Resources