@open-wa/integration-chatwoot

Source: integrations/chatwoot/README.md

@open-wa/integration-chatwoot bridges WhatsApp messages with a Chatwoot API inbox. The current plugin package is 5.1.0. It initializes the Chatwoot client at core.started, syncs supported WhatsApp messages into Chatwoot, and exposes createChatwootRouter for Chatwoot webhooks.

Quick startCopy Anchor Link

Install the plugin in the open-wa application that owns the WhatsApp session, then configure it under pluginConfig.chatwoot:

export default {
  port: 8080,
  host: '0.0.0.0',
  apiKey: 'your-secure-key',
  plugins: ['@open-wa/integration-chatwoot'],
  pluginConfig: {
    chatwoot: {
      chatwootUrl: 'https://app.chatwoot.com/api/v1/accounts/123',
      chatwootApiAccessToken: 'your-chatwoot-user-access-token',
      apiHost: 'https://wa.example.com',
      apiKey: 'your-secure-key',
      forceUpdateCwWebhook: true,
    },
  },
};

chatwootUrl may include an existing inbox, for example .../accounts/123/inboxes/456. Otherwise the client finds or creates an API inbox. apiHost is the public origin Chatwoot can reach; the plugin adds /plugins/chatwoot/webhook and, when apiKey is present, appends it as a query value.

The callback router currently parses the webhook body but does not validate that api_key query value itself. Put a reverse proxy or gateway in front of the callback when it must be authenticated, and have that boundary validate the query or an equivalent header before forwarding to open-wa.

ConfigurationCopy Anchor Link

Message behavior and limitsCopy Anchor Link

• Direct WhatsApp messages create or reopen contacts and conversations. Group, broadcast, and echo messages are ignored.
• Text replies from Chatwoot use sendText. Replies containing a URL use link preview support.
• A reply beginning with a token such as @51.5072,-0.1276 Meeting point becomes a WhatsApp location.
• Chatwoot attachments are sent with sendImage, using the Chatwoot message content as the first caption.
• Inbound image, audio, voice note, video, and document messages become Chatwoot attachments when open-wa can decrypt the media and the required media fields are present. When only cloudUrl is available, Chatwoot receives a file link in text.
• Contact and conversation registries are in memory. Restarting the process rebuilds them from later messages and the configured inbox state.

The integration marks outbound message IDs as ignored so a reply does not loop back as a new inbound message. It does not provide a durable message archive or guarantee attachment delivery when media decryption is unavailable.

Callback checksCopy Anchor Link

After startup, confirm the log contains Chatwoot integration initialized, then check the inbox webhook URL. It should be https://wa.example.com/plugins/chatwoot/webhook?api_key=your-secure-key when both apiHost and apiKey are set.

Use Chatwoot's profile endpoint to check the token and account before diagnosing open-wa:

curl -i \
  -H "api_access_token: $CHATWOOT_API_ACCESS_TOKEN" \
  "$CHATWOOT_ORIGIN/api/v1/profile"

A 200 response with an account ID confirms the token reaches Chatwoot. A 401 means the token or Chatwoot origin needs correction. Then send a direct WhatsApp message and a plain Chatwoot reply, checking the open-wa log and the callback response at each boundary.

DevelopmentCopy Anchor Link

pnpm --filter @open-wa/integration-chatwoot dev

The plugin exports chatwootPlugin, ChatwootClient, createChatwootRouter, ChatwootPluginConfig, and ChatwootConfig.

DocumentationCopy Anchor Link

See the Chatwoot guide for the setup journey, media mapping, and recovery table.

LicenseCopy Anchor Link

H-DNH 1.1 - Hippocratic + Do Not Harm