Recently, we explained how to configure webhooks using the LiveChat API. Today, we’ll dive into this topic even more and explain another aspect of LiveChat webhooks — bot webhooks.
What are bot webhooks?
As a quick recap, regular LiveChat webhooks are registered for a developer’s application in the Developer Console and then enabled per LiveChat license. Bot webhooks are registered in the same way but are closely associated with the status of the bot (or bots) assigned to the application. The bot is recognized by the Client ID of the app.
The bot webhooks mechanism is an incredibly powerful tool that gives you the possibility to automate messaging with customers and make the bots in your app react to specific events.
Bot and license webhooks: similarities & differences
Webhook receiver
From the technical point of view, both license webhooks and bot webhooks are the
same type of requests. Just as with license webhooks, bot webhooks are always
sent to a specific URL endpoint associated with a specific Client ID. This
endpoint can be your backend service in the case of license webhooks, or in the
case of bot webhooks, an endpoint where your bot behavior is configured. This is
something you determine with the webhook type
parameter when registering a
webhook.
Status dependency
The purpose of bot webhooks is to allow your bots to react to incoming events
your app receives. Under your endpoint, the bots can wait for incoming events
and take action based on your application’s code. One of the factors that
affects whether a bot takes action is the bots’ current status. If the bot’s
status is set to accepting_chats
, it will be able to react to the webhook
based on your code. If the bot has its status set to not_accepting_chats
, it
won’t react to incoming webhooks. Note that if the bot is online but
not_accepting_chats,
the app will still get the webhook. If the bot’s status
is set to offline
, the app won’t be able to receive your bot webhooks. This is
different for license webhooks, which you receive at all times when a specific
event is triggered.
Ease of modification
Thanks to the status dependencies, bot webhooks are more dynamic than regular license webhooks. It’s much easier to dictate whether your bots react to an event just by adjusting their chat status. This gives you room for modification: for example, simply by setting up the bot’s working hours through the LiveChat Agent Application. However, note that you can also implement a similar reaction behavior for license webhooks by configuring your app’s code to ignore received webhooks during a specific timeframe.
💡 What if my application owns more than one bot?
One Client ID (application) can have more than just one bot assigned to it. You
can manipulate the bots’ statuses by enabling and disabling them via their
routing status (accepting_chats
or not_accepting_chats
).
If a Client ID has more than one bot online at the time when a webhook is sent, that Client ID will still receive only one webhook of a specific kind. The number of online bots will not affect the number of triggered events and received webhooks.
Configuring bot webhooks
Note: This tutorial explains how to configure bot webhooks in **API version 3.5. If you’ll be following the steps with higher API versions, make sure that the request parameters are the same as in the examples.
Configuring bot webhooks in the LiveChat API is a three-step process. Before you start, remember to create an application in the Developer Console to which you’ll later register the bot and the bot webhooks. Add the Authorization block to your app so you can get its Client ID. As soon as you have that, you can move to the next steps:
- Register
Webhook
- In order to create a bot webhook, you need to pass a request
with the type: bot parameter. When registering the webhook, remember that
the owner_client_id parameter refers to the C lient ID of your app, and
not to the bot ID. If you want to test if the webhook you register works
correctly and arrives at your endpoint, you can input a test URL from the
https://webhook.site/in the
url
parameter.
- In order to create a bot webhook, you need to pass a request
with the type: bot parameter. When registering the webhook, remember that
the owner_client_id parameter refers to the C lient ID of your app, and
not to the bot ID. If you want to test if the webhook you register works
correctly and arrives at your endpoint, you can input a test URL from the
https://webhook.site/in the
curl -X POST \
https://api.livechatinc.com/v3.5/configuration/action/register_webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"url": "http://myservice.com/webhooks",
"description": "my test bot webhook",
"action": "incoming_chat",
"secret_key": "yourcustomsecretkey",
"owner_client_id": "da9e0ff68a6dcec125b7f748ac770695",
"type": "bot"
}'
The response to this request will be the ID of your webhook.
Instead of a Bearer token, we recommend using a Personal Access Token (PAT) authorization to register the webhook. Because webhook registration is a one-time action, thanks to PATs you won’t need to request a token from the user in order to register a webhook for them in your app.
💡 Normally, each online bot receives webhooks from all chats, not only from
those they’re assigned to. As a result, the bots take action in every chat, even
though the chats in question aren’t assigned to them. However, you can avoid
this behavior by using the filters.chat_presence.my_bots
filter when
registering your webhook. Due to this, the webhooks will be triggered only when
one of the bots registered under the specific Client ID is present in chat.
- Create
Bot
- Next, you need to create a bot under the Client ID of your app. You should create a separate bot for each license that’s supposed to have this specific Client ID installed, and this Client ID has to be the owner of the bots you create.
curl -X POST \
https://api.livechatinc.com/v3.5/configuration/action/create_bot \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "My Webhook Bot"
}'
If you authorize this request with a Bearer token, the bot will be automatically
associated with the Client ID of the app you got the access token for. If you
use a PAT, you need to pass the Client ID of your application in the
owner_client_id
parameter.
In response to this request, you’ll get the ID of your bot.
- Set
Routing Status
- Before the bot can react to webhooks, you need to set
its routing status to online. Let’s assume the bot is the only online
agent on the license. We’ll set its status to
accepting chats
. To specify which bot you enable, pass the bot’s ID in theagent_id
parameter in the request.
- Before the bot can react to webhooks, you need to set
its routing status to online. Let’s assume the bot is the only online
agent on the license. We’ll set its status to
curl -X POST \
https://api.livechatinc.com/v3.5/agent/action/set_routing_status \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"status": "accepting_chats",
"agent_id": "173c6ab5135518a4179d1e21b6007594"
}'
And that’s it! If you set the webhook URL endpoint from
https://webhook.site/,
you can test your webhook by triggering the webhook event and checking if it’s
correctly received by webhook.site. In the steps above, you registered the
incoming_chat
webhook, so to test it you can simply start a new chat in your
chat widget.
Sample app ideas
If you can’t wait to start building your bot apps, here are some suggestions as to what use cases you can cover. Below, you’ll find a brief description of the application logic and the webhooks you can use to build these solutions. If you have any questions, you can always drop us a message on Discord.
💬 Bot sends messages if an agent doesn’t reply for a long time
Event: There’s an ongoing chat, but the agent doesn’t reply for a certain
number of minutes.
Webhook: incoming_chat
, incoming_event
Behavior: The bot would detect the time from the last message sent by the
customer without a reply from the agent and react by sending a message to them
if the response time is too long.
🏷️ Bot suggests canned responses when a chat is tagged
Event: A new chat starts and at some point, the chat is tagged.
Webhook: thread_tagged
Behavior: The bot would send canned
response suggestions for the agent based on the tag added to the chat. Before we
send the suggestions, we want to make sure the chat is still active. To do so,
you can use the
get_chat
method.
As an extension to this app, the bot could also listen for incoming_event
messages and suggest canned responses based on the content of the messages.
👍 Bot reacts to chat rating
Event: A new chat is started and messages are sent. The customer rates the
chat.
Webhook: incoming_event
(filtering system messages for chat
rating)
Behavior: The bot sends a suggestion to the agent on what they
could do next. For example, if the rating is good, ask the customer to review
the product; and if the rating is bad, ask the customer to elaborate on what
they’re dissatisfied with.
Further reads
- Read this article on configuring webhooks in the LiveChat API if you want to refresh your knowledge about webhooks and recap how to register license webhooks in LiveChat.
- Check our app ideas to see if you can find some inspiration to start coding your app.
- Join the LiveChat for Developers Discord community to ask questions if you get stuck during the development of your application.