Docs

Chatwoot

Add a bot to Chatwoot using the official integration.

The official Chatwoot integration allows users to chat with your bot through Telegram, WhatsApp, Email, or any Chatwoot-supported channel. It also allows your bot to hand off conversations to human agents when needed.

Setup

Step 1: Install the integration in Botpress

In Botpress Studio, select Explore Hub in the upper-right corner.

Search for the Chatwoot integration, then select Install Integration.

In the Configuration menu, you should see three fields:

  • API Access Token
  • Account ID
  • Inbox ID

Step 2: Get your credentials from Chatwoot

Log in to Chatwoot. Then, in Botpress, fill in the integration’s configuration fields using information from your Chatwoot account:

API Access Token

In Chatwoot, select your profile icon (bottom-left corner).

Go to Profile Settings.

Scroll to the Access Token section.

Copy the token, then paste it into the API Access Token field in Botpress.

Account ID

In the Chatwoot page’s URL, find and copy your account ID—it should be after /accounts/.

For example, if your page URL is:

https://app.chatwoot.com/app/accounts/145294/...

the account ID is:

145294.

Paste the account ID into the Account ID field in Botpress.

Inbox ID

In Chatwoot, go to Settings > Inboxes.

Select Add Inbox.

Select API as the channel type.

Choose a name for the channel.

After creation, select the inbox to open its settings.

In the Chatwoot page’s URL, find and copy your inbox ID—it should be after /inboxes/.

For example, if your page URL is:

https://app.chatwoot.com/app/accounts/1/settings/inboxes/88275

the inbox ID is 88275.

Paste the inbox ID into the Inbox ID field in Botpress.

Step 3: Configure your webhook in Chatwoot.

Finally, configure your Botpress webhook in Chatwoot:

In Botpress, copy the integration’s webhook URL (starting with https://webhook.botpress.cloud).

In Chatwoot, go to Settings > Integrations > Webhooks.

Select Add New Webhook.

Paste the Botpress webhook URL.

Select the following events:

  • message_created
  • conversation_status_changed

Select Create Webhook.

Cards

Create external user

Create an end user in the external service and in Botpress

inputobject
outputobject

Start new HITL session

Create a new HITL session in the external service and in Botpress

inputobject
outputobject

Stop HITL session

Stop an existing HITL session in the external service

inputobject

Triggers

hitlAssigned

payloadobject

HITL Started

Triggered when a HITL session started

payloadobject

hitlStopped

payloadobject