Building webhook apps

Introduction

This tutorial will help you build a LiveChat webhook integration. Follow this tutorial if you're developing a LiveChat integration that reacts to internal LiveChat events, such as a new incoming chat or queued visitor.

Use cases

A typical use case for webhook integration is connecting LiveChat to an external CRM, marketing automation tools, or data analytics platforms. For instance, if you're integrating a marketing automation tool, you could add a new contact every time a LiveChat visitor starts a chat.

Important notes

You'll need a basic knowledge about webhooks and LiveChat authorization protocol (OAuth2.0).

This tutorial won't be helpful for building integrations that pull data on demand (not in reaction to some LiveChat event). If you just want to pull LiveChat reports on user request, you'd rather just use Data & Reporting APIs.

Basic tutorial

1. Sign in to Developer Console

You'll need a Developer Account. Sign up to Developer Console and get access to all Platform Developer Tools.

2. Create new app

3. Add Settings Page

Go to Building Blocks and create a new Agent App Widget with App Settings placement. This widget will be displayed as a settings page for your app.

4. Add Authorization Block

Go back to Building Blocks section and create a new Server-side app Authorization Block. Save the highlighted Client ID – you'll need it later!

5. Create a settings page

Settings page is the place where you can:

• ask users to connect their accounts with your OAuth2.0 provider,
• display configuration options,
• inform users about additional installation steps (if there are any).

If you need to access LiveChat user data, we recommend using Sign in with LiveChat SDK.

Sample settings page scenario

For instance if you're building an integration that binds LiveChat data with an external service, you should create a settings page that:

1. Imports Sign in with LiveChat SDK.
2. Imports your sign in form or other authorization flow (e.g. "Connect with..." button).
3. Binds both informations and stores new user in your database.
4. Displays a confirmation screen when the integration is up and running.

The settings page will appear right after LiveChat user installs your app in the Marketplace.

6. Register the webhooks

Once you have LiveChat credentials, you can register your webhooks with Platform APIs. There are two APIs you can use to manage webhooks:

• Configuration API v3
• Configuration API v2 (deprecated)

Seting up webhooks for development

For development purposes we recommend setting your webhooks from within LiveChat Agent App.

Go to Settings > Integrations > Webhooks and set up your webhook URLs

Each webhook consists of the following properties:

• Event – determines when the webhook is sent to your web server.
• Data type – includes additional information in the webhook.
• Target URL – address of your web server the webhook will be sent to.

Webhooks reference

Please see the following documents for reference on how to manage webhooks:

• To set up webhooks
• To learn the webhooks format

Webhooks v2 Reference (deprecated)

LiveChat can send notifications when some particular action is performed. Such a notification is called a webhook – it’s just a simple HTTP request that LiveChat sends to your server when a particular event occurs. Check the basic auth example below.

HTTP Basic Auth

For security reasons it's recommended to use HTTP basic authentication. Credentials should be passed in this format: https://user:password@www.my-website.com. We recommend using https:// in webhook url.

AuthType Basic
AuthName "My Protected Area"
AuthUserFile /path/to/.htpasswd
Require valid-user

livechat:$apr1$G9iXatUK$gPJLrKQsoWWkFCY/SXO/H.

Example webhook url

https://livechat:password@www.my-website.com

Webhook format

Each webhook is a HTTP POST request made to the URL that you provide in the web app. The request's POST body contains webhook information in JSON format.

{
  "event_type": "chat_started",
  "token": "27f41c8da685c81a890f9e5f8ce48387",
  "license_id": "1025707"
}

Each webhook contains the following properties:

• event_type – tells you the event that triggered the webhook. Possible values: chat_started, chat_ended, visitor_queued.
• token and license_id – your authentication credentials that let you call LiveChat’s Configuration API v2 methods. You won’t need to use them unless you want to make a call to LiveChat’s API right when you receive a webhook. In that case, you just need to pass these token and license_id credentials in your API call.
• additional information – please read the Webhook data types section.

If your endpoint is responsible for both receiving data from our webhook and making further actions, like creating a record in a database, then the whole process may take longer than 10 seconds. In such a case, we believe, the best solution would be to split your mechanism into 2 separate actions:

1) Retrieving data from the LiveChat webhook (sending HTTP 200 back to us immediately).

2) Further processing of the data and passing it to other services.

That would prevent situations in which the process takes longer than our webhook timeout and data isn't pushed from our side again.

Note: LiveChat webhooks are sent with Content-Type: application/json header, so please make sure that your service can handle such requests.

Note: chat_changed event type is sent only when the tag list for a particular chat was changed, no matter if the chat is pending or not.

Webhook data types

{
  "event_type": "chat_started",
  "token": "27f41c8da685c81a890f9e5f8ce48387",
  "license_id": "1025707",
  "visitor": {
    "id": "S1354547427.0c151b0e1b",
    "name": "John",
    "email": "john.smith@gmail.com"
  }
}

In some cases, you may want to get some additional information when the particular event occurs.

For example, when the chat starts, you may want to know the exact chat start time along with the visitor's name and e-mail provided in the pre-chat survey. To get this information, you can add some data types that will be sent to your webserver along with each webhook.

chat

{
  "chat": {
    "id": "MH022RD0K5",
    "started_timestamp": 1358937653,
    "ended_timestamp": 1358939109,
    "messages": [
      {
        "user_type": "agent",
        "author_name": "John Doe",
        "agent_id": "john.doe@mycompany.com",
        "text": "Hello",
        "timestamp": 1358937653
      },
      {
        "user_type": "supervisor",
        "author_name": "James Doe",
        "agent_id": "james@mycompany.com",
        "text": "This is whispered message.",
        "timestamp": 1358937658
      },
      {
        "user_type": "visitor",
        "author_name": "Mary Brown",
        "text": "How are you?",
        "timestamp": 1358937661
      }
    ],
    "tags": ["sales", "support", "feedback"]
  }
}

Include this data type if you need to know chat start and end time or the full chat transcript.

visitor

"visitor": {
	"id": "S126126161.O136OJPO1",
	"name": "Mary Brown",
	"email": "mary.brown@email.com",
	"custom_variables": [
		{
			"key": "Customer ID",
			"value": "POQ51023XZA"
		}
	]
}

This data type includes visitor’s name and e-mail address.

pre_chat_survey

"pre_chat_survey": [
{
  "id": "135963440121804757",
  "type": "name",
  "label": "Your name",
  "answer": "Mary Brown"
},
{
  "id": "135963440121802531",
  "type": "email",
  "label": "Your e-mail",
  "answer": "mary.brown@email.com"
},
{
  "id": "135963613764705707",
  "type": "checkbox",
  "label": "What are your favourite music bands?",
  "answers": [{
    "label": "Deep Purple",
    "chosen": true
  },
  {
    "label": "Iron Maiden",
    "chosen": false
  },
  {
    "label": "Guns N' Roses",
    "chosen": true
  }]
}
]

Include this data type if you need to know the exact results of the pre-chat survey that was filled in by the visitor.

ticket

"ticket":{
  "assignee":{
    "id":"agent.gregory@email.com",
    "name":"Gregory"
  },
  "events":[
    {
      "author":{
        "id":"mary.brown@email.com",
        "name":"agent4",
        "type":"agent"
      },
      "date":"2014-08-18T10:05:05Z",
      "is_private":false,
      "message":"How are you?",
      "source":{
        "type":"agent-app-manual",
        "url":null
      },
      "type":"message"
    }
  ],
  "groups":[
    {
      "id":0,
      "name":"All operators"
    }
  ],
  "id":"CCWWM",
  "requester":{
    "mail":"mary.brown@email.com",
    "name":"Mary Brown"
  },
  "status":"open",
  "subject":"Welcome",
  "tags":['support'],
  "source":{
    "type":"lc2",
    "url":null,
    "id":"NO4Y5FAERW"
  }
}

This data type includes ticket details.

canned_response_changed

"canned_response":{
    "group": 0,
    "id": 1,
    "modification_date": 1494230856,
    "tags": [
        "shortcut1",
        "shortcut2"
    ],
    "text": "Can I help you with anything else?"
}

This data type includes canned response details.

Example apps

Here are some ideas for using LiveChat webhooks:

• display a warning message on your internal statusboard when your website visitors start queueing before the chat,
• save each chat transcript in the external system,
• read additional information about your visitors from your database and send it back to the LiveChat app.

Queued visitors notifier

Let’s say you want to be notified with a sound on your internal company statusboard every time a visitor is queued before the chat.

Upload an example script (displayed in the right column) to your web server and set up a webhook to send visitor_queued event to this script.

<?php

// read the webhook sent by LiveChat
$data = file_get_contents('php://input');
$data = json_decode($data);

// make sure the "visitor_queued" event occured
if ($data->event_type === 'visitor_queued')
{
    // BAM! Play a sound on your internal statusboard
    // $Statusboard->play();
}