Chatwoot Extension

The Chatwoot extension is a small Flask app in extensions/chatwoot. Chatwoot sends a signed webhook to its POST /docsgpt endpoint for every new message. The extension asks your DocsGPT agent through /api/answer and posts the answer back into the Chatwoot conversation.

The extension must be reachable from Chatwoot, and it must be able to reach both the DocsGPT API and Chatwoot.

Step 1: Prepare DocsGPT and get an agent API key

Launch DocsGPT: Follow the Quickstart to start DocsGPT, and add your documentation as knowledge.
Create an agent: Create an agent that uses that knowledge, publish it, and copy its API key from the agent’s Access Details. See Agent API keys. The extension sends this key as api_key to /api/answer, so it must be an agent key, not an OpenAI or other LLM provider key.

Step 2: Get an access token from Chatwoot

Go to Chatwoot.
In your profile settings (bottom left), scroll down and copy the Access Token. The extension uses it to post replies.

Step 3: Add a webhook in Chatwoot

In Chatwoot, go to Settings → Integrations → Webhooks, click Configure, then Add new webhook.
Set the URL to the extension’s endpoint, for example http://<extension-host>:5000/docsgpt.
Subscribe to the Message created event (message_created) and save.
Copy the webhook’s secret. Chatwoot shows it after the webhook is created, and you can view it again in the webhook’s edit form.

The extension verifies Chatwoot’s X-Chatwoot-Signature and X-Chatwoot-Timestamp headers with this secret. Requests with a missing or wrong signature, or signed more than five minutes ago, get 401. Use a Chatwoot version that signs webhook deliveries, and keep the extension host’s clock in sync.

⚠️

Older Chatwoot versions that do not sign webhooks. Every request from them gets 401. As a last resort, add chatwoot_allow_unsigned=true to the extension’s .env: it then accepts requests that carry neither signature header (a request that carries them is still verified), and logs a warning at startup. This is insecure: anyone who can reach /docsgpt can make the extension query your agent and post into your Chatwoot conversations. Upgrade Chatwoot if you can; otherwise make the extension reachable only from Chatwoot, for example on a private network or behind an IP allowlist.

Step 4: Configure the extension

Go to extensions/chatwoot and install its dependencies:


cd extensions/chatwoot
pip install flask requests python-dotenv

Copy .env_sample to .env in the same folder and fill in the values:


docsgpt_url=<DocsGPT API URL, e.g. http://localhost:7091>
docsgpt_key=<Agent API key from Step 1>
chatwoot_url=<Chatwoot URL, e.g. https://app.chatwoot.com>
chatwoot_token=<Access Token from Step 2>
chatwoot_webhook_secret=<Webhook secret from Step 3>

Step 5: Start the extension

Run the extension so Chatwoot can reach it. Plain flask run listens only on 127.0.0.1, so bind to all interfaces:


flask --app app run --host 0.0.0.0 --port 5000

The webhook URL from Step 3 is then http://<extension-host>:5000/docsgpt. For production, put the extension behind HTTPS.

If DocsGPT or Chatwoot returns an error, the extension logs it and answers the webhook with 502 instead of posting a reply.

Step 6 (optional): Limit which conversations get answers

Add these lines to .env to answer only in one Chatwoot account, or only conversations assigned to one Chatwoot agent. Leave them out to answer every incoming message.


account_id=1
assignee_id=1

Stopping Bot Responses for Specific User or Session

If you want the bot to stop responding to questions for a specific user or session, add a label human-requested in your conversation.