Linking Chatwoot as a source
This source is currently in alpha. The interface and available tables may change.
The Chatwoot connector syncs your customer support data – conversations, messages, contacts, inboxes, agents, teams, and more – into PostHog, whether you use Chatwoot Cloud or a self-hosted instance.
Prerequisites
You need a Chatwoot account and a user API access token. Use an administrator's token: agent tokens only see conversations in their assigned inboxes, and only administrators can manage webhooks (needed for real-time syncing).
Adding a data source
- In PostHog, go to the Sources tab of the data pipeline section.
- Click + New source and click Link next to this source.
- Enter your credentials (see Configuration below) and click Next.
- Select the tables you want to sync, choose a sync method and frequency, then click Import.
Once the syncs are complete, you can start querying this data in PostHog.
You need three things to connect Chatwoot:
- API access token: in Chatwoot, click your avatar, open Profile settings, and copy the token under Access token.
- Account ID: the number in your Chatwoot URL, e.g.
app.chatwoot.com/app/accounts/<account ID>. - Instance URL (self-hosted only): your Chatwoot instance URL, for example
https://chatwoot.example.com. It must use HTTPS. Leave this empty for Chatwoot Cloud.
Sync modes
Each table can be synced in one of several modes, depending on what the source supports:
- Webhook (when available) – the source pushes changes to PostHog in real time. Fastest freshness, lowest ongoing cost, and the only mode that reliably captures updates and deletes.
- Incremental – only new or updated rows are synced on each run, using a cursor field (such as an
updated_attimestamp). Cheaper than a full refresh, but deletes aren't captured. - Append only – new rows are appended using a cursor field; existing rows are never updated. Ideal for immutable, append-only tables like event logs.
- Full refresh – the whole table is reloaded on every sync. Use it when a table has no reliable cursor or when you need deletions reflected.
See sync methods for a full explanation of how each mode works and how to choose between them.
Chatwoot's API has no "updated since" filter, so scheduled syncs are always full refreshes. For the conversations and messages tables we recommend webhook sync: after an initial backfill, Chatwoot pushes changes to PostHog in real time, which is both fresher and much cheaper than re-walking the API on every sync. This matters most for messages, which is fetched one conversation at a time, so full refreshes on large accounts issue at least one request per conversation.
Webhooks for real-time syncing
When you select the webhook sync method for conversations or messages, PostHog creates the webhook in your Chatwoot account automatically (this requires an administrator token). Recent Chatwoot versions sign webhook deliveries with a per-webhook secret, which PostHog verifies; the secret is captured automatically when the webhook is created.
To set the webhook up manually instead: in Chatwoot, go to Settings → Integrations → Webhooks, add the webhook URL shown in PostHog, and subscribe to the conversation and message events. Older self-hosted Chatwoot versions don't sign deliveries – in that case, enable the signature bypass toggle on the webhook function in PostHog.
Configuration
| Option | Type | Required |
|---|---|---|
Chatwoot instance URL | text | No |
Account ID | text | Yes |
API access token | password | Yes |
Supported tables
| Table | Description | Sync method | Incremental field | Primary key |
|---|---|---|---|---|
conversations | One row per conversation. The id column is Chatwoot's per-account display id. | Webhook, Full refresh | — | — |
messages | Conversation messages, fetched per conversation — a full sync issues at least one request per conversation, so large accounts can take a while. Webhook sync avoids the re-walk after the initial backfill. | Webhook, Full refresh | — | — |
contacts | Contacts with an email, phone number, or identifier. Chatwoot's contact list excludes anonymous web-widget visitors. | Full refresh | — | — |
inboxes | A channel through which conversations arrive, such as a website widget, email address, or WhatsApp number. | Full refresh | — | — |
agents | A user who is a member of the account, including their role and availability. | Full refresh | — | — |
teams | A group of agents used to organize and assign conversations. | Full refresh | — | — |
labels | A label that can be attached to conversations and contacts for categorization. | Full refresh | — | — |
custom_attribute_definitions | Custom attribute definitions for conversations, contacts, and companies. | Full refresh | — | — |
Troubleshooting
- Chatwoot rejected your API access token: check the token is copied correctly from Profile settings → Access token and that its user is a member of the configured account.
- Account not found: the account ID doesn't exist on the configured instance. Check the number in your Chatwoot URL and, for self-hosted instances, the instance URL.
- Missing conversations: agent tokens only see conversations in their assigned inboxes. Reconnect with an administrator's token.
- Contacts look incomplete: Chatwoot's contact list only returns contacts with an email, phone number, or identifier, so anonymous web-widget visitors are not included.
If your sync is failing or data looks wrong, see the Data warehouse troubleshooting guide. If that doesn't help, contact support – we're happy to help.