This document explains how to configure the Chat Webhooks building block in Developer Console. It was written for everyone aiming to configure webhooks in their integrations via user interface instead of calling the LiveChat Configuration API directly. The document assumes you're already familiar with the general idea of webhooks.
The document applies to the so called new chat webhooks (v3.3 or later). It's impossible to configure the old chat webhooks (v3.2 or below) via Developer Console – you can only delete the already configured ones or migrate them to the current stable version. If you're curious about the differences between the old and new chat webhooks, read this article.
Keep in mind that the Chat Webhooks building block allows you to configure the
license webhooks, and that is what this document focuses on. The document doesn't apply to the
This tutorial presents how to build a simple application with the Chat Webhooks building block. It also explains the configuration of all other parts that are required for the Chat Webhooks block to be functional. The tutorial applies to the new chat webhooks (v3.3 or later).
In short, you need to take the following steps:
The end result of this tutorial will be an application that receives webhooks whenever a pre-determined event occurs.
Before you start
Log in to Developer Console or create an account for free.
Step 1: Create an app in Developer Console
To create a new app, all you need to do is click Create new app+, come up with a name, choose the product you want to build for, and click Continue.
Then, if your app has the frontend side, add and configure the Agent App Widget building block. Skip this step if you're building a 100% backend app with no UI.
Step 2: Configure authorization
Why is it necessary? You're building an application that, once installed, will call the Configuration API to enable webhooks for a user's license. To perform this operation, the user needs to authorize your application first.
Configure the App Authorization building block
- Add the
webhooks.state:rwscope, which will be later on used by LiveChat to enable webhooks for a license that installs your app.
- Provide a Direct installation URL and add it to the Redirect URI whitelist.
💡 Watch our live coding session to learn more about the Direct installation flow or keep on reading.
Handle direct installation and authorization in your app
Usually, the authorization process starts in the LiveChat Agent Application when a user runs the app for the first time. With the direct installation flow enabled, authorization begins on the Marketplace. When a user installs your app, a pop-up with the LiveChat authorization flow appears, and the application asks for access to certain resources. Upon successful authorization, the user is redirected to the Direct installation URL, where they can, for example, do the initial app configuration. (It all depends on what you implemented.)
As a developer, you need to handle the authorization flow in your app. For a backend app, we recommend Authorization code grant, where your app exchanges
Step 3: Configure chat webhooks
Configuring chat webhooks in Developer Console is equivalent to calling the Register Webhooks method from the Configuration API. However, making use of the Chat Webhooks building block is much more convenient because you don't need to support enabling webhooks – LiveChat will do that for you when someone installs your app.
The configuration of the Chat Webhooks building block is a three-step process and involves the following aspects:
All the webhooks will be sent to the URL you provide in the Webhook URL field. That's likely the address of your backend service, but you can use https://webhook.site for testing.
We'll include your secret key in the payload of each webhook. This way, your application can verify the webhooks came from us. Make sure you save the generated secret key as it will disappear after you refresh the page. If needed, you can always regenerate a new key or paste your old one in the Secret key field.
Then, choose webhook triggers, the actions that will cause sending a webhook to the Webhook URL every time a specific event occurs. For the majority of events, you can also select a filter.
Thanks to such a setup, webhook will be automatically enabled for users who install your app from the Marketplace once it is published.
Testing chat webhooks
To test your webhooks, go to the Private installation tab and click Install app. If you used Direct installation URL, you'll see a popup window displaying the contents from your app (This is the stage of receiving
code that you need to exchange it for
token. In production-ready apps, your app should automatically close the window when authorizing a user. Then, perform the action that's your webhook trigger, for example, start a chat if you selected the
It's no longer possible to register chat webhooks v3.2 or below (the old chat webhooks) in Developer Console. If you had configured them in the past, they are still fully functional, but we encourage you to migrate them to the current stable version of the Configuration API. You can do that by calling the API directly or by running the migration process in Developer Console.
Here's a list of useful resources related to webhooks:
- Webhook tutorial: What are webhooks & how to use them with the LiveChat API?
- LiveChat Configuration API
- Available webhooks
If you have any questions or suggestions, feel free to email us at email@example.com or ask on our Discord for Developers.