Home Features explained How to use Agent bots?

How to use Agent bots?

Last updated on May 15, 2023

AgentBot can seamlessly integrate with your Chatwoot inbox as a customer query handling bot. With Chatwoot, you can easily connect your custom bot logic to conversation handling via AgentBot's API.

By connecting AgentBot to your inbox, all new conversations will automatically be assigned a 'bot' status. Chatwoot will send conversation events to your bot URL as webhook events, allowing AgentBot to respond through the Chatwoot API in real-time.

How does the AgentBot work?

Explained below in a typical workflow of an AgentBot.

  1. The AgentBot receives events such as widget_triggered, message_created, and message_updated based on customer interactions.

  2. The AgentBot processes the received information to generate an appropriate response.

  3. The AgentBot can also utilize external system APIs to gather additional customer information, such as order status or booking triggers.

  4. The AgentBot can utilize services such as Rasa, Dialogflow, or Lex for intent detection.

  5. The AgentBot can post the generated response back into the widget by utilizing Chatwoot APIs such as message_create.

  6. The AgentBot can toggle a conversation status to open to hand off the conversation to a human agent.

  7. It continues to monitor open conversations to provide contextual information to the support agent.

How does the Human-Agent handoff work?

When an agent bot is connected to an inbox, conversations are created with a "pending" status, allowing it to triage the conversation before passing it on to a human agent. If the bot determines that a human agent's assistance is needed, it can use the conversation update API to change the status to "open."

Sometimes the agents would want to push back a conversation which was handed off, back again into the bot queue. Agents can return a handed-off conversation to the bot queue by changing the status back to "pending”.

How can I use the AgentBot?

Listed below are a few examples.

  1. Businesses with high volume customer support queries can utilize an AgentBot to authenticate and filter queries, reducing the workload on human agents and improving the efficiency of customer support.

  2. E-commerce websites can integrate the AgentBot with their existing databases, providing customers with real-time updates on order and shipping status, as well as answering other related queries.

  3. News and content websites can use the AgentBot to send recommendations to users via card messages.

  4. Hotel and movie booking websites can use the AgentBot to handle bookings, reservations and answering related queries, providing customers with a seamless and convenient booking experience.


  1. Hotel booking implementation using Dialogflow.

  2. Example implementation using Rasa.

Also, look into interesting ways to leverage bot-message types on Chatwoot.

How to add AgentBots to Chatwoot?

There are two types of AgentBots in Chatwoot.

  1. Global Bots: Global Bots have a permission scope for all the accounts in a Chatwoot installation. They can interact with bot accessible endpoints in respect to any account in that installation.

  2. Account Bots: Account Bots have a permission scope limited to the account for which the bot was created.

You can provision Agent Bots in Chatwoot either through our API or using Rails Console.

Creating agent bots via API

  1. Global Bots can be created by interacting the agent bot APIs.

  2. Account Bots can be created by interacting with the account bot APIs.

Creating agent bots via Rails console

Open your Chatwoot directory and ensure your local server is running. Start a rails console in your directory.

bundle exec rails c

Inside the Rails console, type the following commands to create an agent bot and get its access token. Save the retrieved token, as you would need to use in when calling the chatwoot APIs.

# specify a url when your bot logic resides
# pass account_id attribute to create an account bot instead of global bot
bot = AgentBot.create!(name: "Your Bot", outgoing_url: "http://localhost:8000")

Add an avatar to your bot (optional).

avatar_file = Down.download("image url")
bot.avatar.attach(io: avatar_file, filename: avatar_file.original_filename, content_type: avatar_file.content_type)

Connect Agent Bot to your inbox by running the following command.

# Replace Inbox.first with Inbox.find(inbox_id) for specific inboxes
AgentBotInbox.create!(inbox: Inbox.first, agent_bot: bot)