Docs / Integrations

Chatwoot

Connect a number to Chatwoot and your agents answer its WhatsApp chats from a Chatwoot inbox. Each number gets an API inbox, and messages go both ways: what the number receives shows up in Chatwoot, and what an agent writes there goes out on WhatsApp. Media, delivery and read statuses, and messages sent from the phone are synced too. wuapi hosts the bridge, so there is nothing to install in Chatwoot.

Requirements

1. A paid wuapi plan, and the owner or admin role in the organization.
2. A Chatwoot user who is an administrator of the Chatwoot account: creating an inbox needs it.
3. A Chatwoot that wuapi can reach from the internet over https: Chatwoot Cloud or self-hosted on a public address. A localhost or private network address will not work.

Connect

Open Integrations > Chatwoot in the dashboard and click Connect a number. Nothing is created in Chatwoot until the last step.

1. Paste the address of any page of your Chatwoot, as your browser shows it. wuapi checks it is a Chatwoot and shows its version. An address inside your account (it has /app/accounts/...) lets the next step open your profile directly.
2. Click Open my Chatwoot profile. In Chatwoot, that is your avatar at the bottom left, then Profile settings.
3. Scroll down to Access Token, click Copy and paste the token in the wizard. Chatwoot has no sign-in for apps, so the token is how wuapi acts in it. wuapi stores it encrypted.
4. When the token administers several Chatwoot accounts, pick one. The one in the address you pasted is preselected.
5. Pick one or more linked numbers. Each gets its own API inbox, named WhatsApp +<number>, whose webhook points back to wuapi. The last step links to each inbox.

What syncs

1. Messages the number receives land in the contact's conversation as incoming messages, with images, audio, video and documents attached. The contact is created on the first message, keyed by the contact id (+584241112233 or lid:...), and joined to an existing Chatwoot contact with the same number.
2. Messages sent from the phone, and sends through the API, show as outgoing messages in the same conversation.
3. A reply an agent writes in the inbox goes out on WhatsApp through the same queue as POST /v1/messages: pacing applies, and a reply sent while the number reconnects waits for it. Attachments go as media. Private notes stay in Chatwoot.
4. Each reply shows sent, delivered and read in Chatwoot as WhatsApp reports them. It shows failed only when the send failed for good, with the reason; a reconnect never marks it failed.

Options

Each connected number has its own options on its Chatwoot page in the dashboard.

Limits

1. Group chats are left out by default. Turn off Leave group chats out to bring them in.
2. History imported when the number was linked is not copied to Chatwoot: the inbox starts with the next message.
3. Media over 25 MB arrives in Chatwoot as a link to the file, not as an attachment.

While Chatwoot is unreachable, wuapi keeps the updates in order and retries for about two hours; the number's page shows the last error. Disconnecting leaves the inbox and its conversations in Chatwoot.

Troubleshooting