Service: Chatwoot - EyevinnOSC/community GitHub Wiki

Chatwoot

Chatwoot (serviceId 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. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance with up to 10 GiB of storage per instance.

What it can do

  • Handle customer conversations from several channels in one shared inbox.
  • Work with multiple agents and teams, labels, canned responses and automation rules.
  • Send notification and reply emails through an SMTP server you configure.
  • Expose a REST API for integrating conversations into your own applications.
  • Provide a live-chat widget that can be wired into an app hosted on OSC (see below).

Creating an instance

Chatwoot depends on two other OSC services. Create them first and confirm they are running before creating Chatwoot:

  • PostgreSQL: pgvector-pgvector (Postgres Vector, compatible with Chatwoot's schema). Connection URL format: postgres://user:password@host:5432/db.
  • Valkey (Redis-compatible): valkey-io-valkey. Redis URL format: redis://:password@host:6379.

Use describe-service-instance on each dependency to get its address, port and credentials. Store passwords and the secret key as service secrets with create-service-secret and reference them as {{secrets.NAME}} (the reference must be the entire field value, so a URL that embeds a secret has to be given as a complete value, for example a secret that holds the whole URL).

Generate a long random string for SecretKeyBase, for example with openssl rand -hex 64, or let OSC generate it (the option is marked as system-generatable).

Create the instance with create-service-instance, serviceId: "chatwoot-chatwoot":

{
  "name": "mychatwoot",
  "DatabaseUrl": "{{secrets.chatwootdb}}",
  "RedisUrl": "{{secrets.chatwootredis}}",
  "SecretKeyBase": "{{secrets.chatwootkey}}"
}

Then call wait-for-service-ready (or get-instance-status) and describe-service-instance to find the instance URL. On first launch Chatwoot shows a setup wizard where you create the admin account and your first inbox. There are no pre-set default credentials.

Existing OSC CLI equivalent from the previous page:

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}}"

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore only (^\w+$); OSC limits instance names to 20 characters.
DatabaseUrl Yes string, sensitive PostgreSQL connection URL for the database that stores all Chatwoot data: conversations, contacts, agents and configuration. Format postgres://user:password@host:5432/db. Associated with pgvector-pgvector.
RedisUrl Yes string, sensitive Redis connection URL used for caching, sessions, background jobs and real-time features such as live chat. Format redis://:password@host:6379. Associated with valkey-io-valkey.
SecretKeyBase Yes string, sensitive Rails application secret key used to encrypt sessions and cookies. Use a long random string and keep it the same across restarts. OSC can generate it.
SmtpAddress No string SMTP server hostname or IP address for outbound email (notifications, password resets, conversation replies).
SmtpPort No string SMTP server port, typically 587 (STARTTLS), 465 (SSL/TLS) or 25 (unencrypted). Must match your provider.
SmtpUsername No string Username for SMTP authentication, often an email address.
SmtpPassword No string, sensitive Password (or app-specific password) for SMTP authentication.
MailerSenderEmail No string Email address shown as the sender of all outbound mail from Chatwoot. Should be an address on your own domain.

Sensitive options (DatabaseUrl, RedisUrl, SecretKeyBase, SmtpPassword) should be supplied as {{secrets.NAME}}. To enable email, set all the SMTP options together:

{
  "name": "mychatwoot",
  "DatabaseUrl": "{{secrets.chatwootdb}}",
  "RedisUrl": "{{secrets.chatwootredis}}",
  "SecretKeyBase": "{{secrets.chatwootkey}}",
  "SmtpAddress": "smtp.example.com",
  "SmtpPort": "587",
  "SmtpUsername": "[email protected]",
  "SmtpPassword": "{{secrets.smtppassword}}",
  "MailerSenderEmail": "[email protected]"
}

Using the instance

Call the Chatwoot REST API with an access token (obtain it in the Chatwoot UI under Profile Settings, Access Token):

curl https://mychatwoot.auto.prod-se.osaas.io/api/v1/accounts/1/conversations \
  -H "api_access_token: <your-api-token>"

Live chat on an app hosted on OSC

The OSC AI assistant (MCP) can wire a Chatwoot live-chat widget into a custom app deployed via My Apps. It authenticates with your Chatwoot instance using credentials stored in the live-chat parameter store, creates or reuses a website widget inbox scoped to the app URL, and returns an embed snippet for the app's HTML. Example request to the assistant: "Set up live chat on my app called myapp using my Chatwoot instance called mychatwoot". It uses the setup-live-chat tool chain; the Chatwoot instance must already be running and the parameter store must contain the admin password.

Resources