Skip to content

Chatwoot Integration


Cognigy has integrated "Chatwoot" as an additional handover provider that can be used by our customers to connect their users with real agents (in third-party sources). Chatwoot is an open-source solution and free to use. You can read more about Agent Handover here.


To start using Chatwoot as a handover provider with Cognigy.AI, you first have to sign in to Chatwoot here:

Running Chatwoot On-Premise

You can also setup Chatwoot to run on an On-Premise environment. You can read more about that here

In Chatwoot we first need to add a webhook that will be called when an agent replies to a message.

You can add the webhook in two ways:

  • while creating the inbox

  • add the webhook using "Settings" - "Integrations", which sets the webhook for all the inboxes

Running Chatwoot On-Premise

Choose only one of the following described procedures to add a webhook!

Add webhook while creating the inbox

You need to configure the webhook Inbox for incoming messages.

  • Click on "Inboxes" in the main menu on the Chatwoot homepage

  • Click on "Add Inbox" to start the Inbox creation and configuration procedure

Create API Channel

  • Choose the API channel and enter a channel name

  • Enter the Endpoint Base URL in the "Webhook URL" line and append /handover/chatwoot/ to the end of the URL (e.g. for example

  • Click on "Create API Channel"

  • Select the Agent who will be assigned to the Inbox messages, then confirm with a click on the "Add agents" button.

The new channel will be added to the Chatwoot Inbox.


You need two numbers that are listed in the Chatwoot address line:

  • Account ID (is unique for you as the user)
  • Inbox ID (is not unique and will be created newly with every new channel)

Both IDs are required to use the new Inbox channel.

Chatwood Account ID

Chatwoot Account ID (red marked in the Chatwoot address line)

Chatwood Inbox ID

Chatwoot Inbox ID (red marked in the Chatwoot address line)

Add a new webhook using "Settings" - "Integrations"

  • In the Chatwoot menu bar go to "Settings" - "Integrations" and select "Add a new Webhook"
Add new webhook
  • Find the Endpoint Base URL (the Endpoint URL without the Token) in the Endpoint Editor in Cognigy.AI
  • Enter the Endpoint Base URL in the "Webhook URL" line and append /handover/chatwoot/ to the end of the URL (for example

  • Click on "Create Webhook"

Connect Chatwoot to Cognigy.AI

In the Handover Node in Cognigy.AI, you can specify to which Inbox you want the handover to start in.

You need to configure this by opening the Handover Node, opening the Chatwoot Settings menu, and filling in the Inbox ID.

Dynamically setting the Inbox ID

You can use CognigyScript to dynamically decide which Inbox should be used for the handover request

Enter the Chatwoot Inbox ID

Now we need to connect the Endpoint to Chatwoot. To do this, open the Endpoint Editor and open the Handover Settings section.

Handover settings
  • Enter following data -- Select "Chatwoot" as Handover Platform -- Select BaseUrl as shown (e.g. or your on-premise Chatwoot API URL) -- Enter Chatwoot "Account ID" -- Enter the API Key (use copy and paste - you will find the key in Chatwoot in your "Profile Settings" in "AccessToken" - use the "Copy" button)

  • Click on "Save" to confirm the entries

  • Click on "Open Webchat" and start a conversation

Webchat conversation

When you start a conversation with the Endpoint and trigger the Handover Node, then an Agent Handover will be started with Chatwoot (you will find a handover message in the Chatwoot Inbox)

Inbox handover message
Chatwoot conversation example

On the left-hand side the user messages are displayed - on the right-hand side the connected real agent replies are displayed in Chatwoot.


When a User request is answered and solved by the agent, the agent can "Resolve" the connection and if a further request will come in from the user side the agent can "Reopen" the connection in Chatwoot to be able to reply to the request.

Supported message content

Using the Chatwoot integration the user can receive

  • text messages
  • files
  • videos (mp4, ...)
  • images ( jpg,png,... see example below)
  • animated gifs
Webchat conversation with text and image

Agents in Chatwoot

In case you want to add a new Agent to Chatwoot go to the Chatwoot homepage and click on the "Agents" menu item.

Chatwoot "Settings" menu
Chatwoot info about Agents

Chatwoot API updated

With Cognigy.AI 4.10.0 the Chatwoot API has been updated due to the implementation with Cognigy Live Agent (new color, chat history).


  • Chatwoot API updated to version 1.19.0.

  • Support of custom agent bot name (config-map: AGENT_BOT_NAME).

  • Suppport of custom agent bot description (config-map: AGENT_BOT_DESCRIPTION).

  • Message history of a conversation is available.

  • Messages in the Chatwoot dashboard appear in a new theming / styling.

Back to top