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:

1. 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 ownerclientid 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.

    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.

2. 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.

3. 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 the agent_id parameter in the request.

    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.