Introduction

Hello, developer!

This tutorial will help you build LiveChat webhook integration and get it listed in LiveChat Marketplace.

Use cases

Typical use case for webhook integration is connecting LiveChat to external CRM, marketing automation tools or data analytics platforms.

Follow this tutorial if you’re developing an LiveChat integration that reacts to internal LiveChat events, such as new incoming chat or queued visitor.

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

To use this tool you need to have basic knowledge about webhooks and LiveChat authorization protocol (OAuth2.0).

This tutorial is will not be helpful for integration that pulls 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 REST API.

Getting started

Prerequisites

You’ll need a LiveChat Developers Account. Sign up to your Developers Console.

I. Create and configure app

Go to Developers Console > Apps and create new app.

Create LiveChat App

  1. Sign in to Developers Console
  2. Create new app.

  3. In Building Blocks section:

    1. Create new Agent App Widget with App Settings placement. This widget will be displayed as a settings page for your app.
    2. Create new Server-side app Authorization Block. Save the highlighted Client ID – you’ll need it later!

II. Create a simple settings page

Settings page is the place where you can:

  • ask user to connect their account 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.

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

  • imports Sign in with LiveChat SDK and inits authorization with data from Authorization Block created in step I.3.2
  • imports your sign in form or other authorization flow (e.g. “Connect with…” button)
  • binds both informations and stores new user in your database
  • displays a confirmation screen when the integration is up and running

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

III. Create the webhook listener

Once you have LiveChat credentials from II. you can register your LiveChat webhooks with Webhook REST API. For development purposes we recommend setting your webhooks from within LiveChat Agent App.

Webhooks reference

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 on the right.

Set up the webhooks for development

Go to Settings > Integrations > Webhooks and set up your webhook URLs Finalizing web hook creation

You can enable your webhooks in the web application: https://my.livechatinc.com/settings/webhooks.

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.

HTTP Basic Auth

File contents: .htaccess

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

File contents: .htpasswd

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

Example webhook url

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

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.

Example integrations

Here are some ideas for using LiveChat webhooks:

  • read additional information about your visitors from your database and send it back to the LiveChat app,
  • 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.

Displaying visitor details in LiveChat apps

Example script – additional visitor details

<?php

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

// make sure the "chat_started" event occured
if ($data->event_type === 'chat_started')
{
    // read additional information about your visitor
    // from your internal database
	$email = $data->visitor->email;
	$visitorDetails = $MyDatabase->query($email);

	// send this information to LiveChat apps
	$fields = array();
	$fields[] = (object)array(
		'name' => 'Age',
		'value' => $visitorDetails['age']
	);
	$fields[] = (object)array(
		'name' => 'Position',
		'value' => $visitorDetails['position']
	);

	$curlFields = http_build_query(array(
		'license_id' => $data->license_id,
		'token' => $data->token,
		'id' => 'my-integration',

		// Do not enter "http" prefix in the icon URL.
		// Your server must be able to serve the icon
		// using both https:// and http:// protocols.
		'icon' => 'example.com/ico-64.png',

		'fields' => $fields
	));

	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, 'https://api.livechatinc.com/visitors/'.$data->visitor->id.'/details');
	curl_setopt($ch, CURLOPT_POST, 1);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $curlFields);
	curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-API-Version: 2'));
	$result = curl_exec($ch);
	curl_close($ch);
}

You may want to query your database based on your visitor’s e-mail address and display additional visitor information to your agents. You can do this by activating a webhook with chat_started event.

Every time a chat is started, your script will receive a webhook including visitor’s e-mail address. You can then look up your own database and send additional information to LiveChat apps.

Upload the example script (displayed in the right column) to your web server and set up a webhook to send chat_started event to this script. As a result, your agents will see additional information during a chat:

Visitor details in LiveChat

You can read a more detailed documentation in Visitors API.

Notifying internal statusboard about a queued visitor

Example script – notifications

<?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();
}

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.

Webhook format

Example webhook

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

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.

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 REST API 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. Here’s an example.
  • additional information – please read the Webhook data types section.

When your server receives a webhook from LiveChat, it should respond with HTTP 200 response. Otherwise, LiveChat will retry sending the webhook to your service for a number of times unless it receives the correct HTTP 200 response.

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

Example webhook including visitor information

{
  "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.

Event type Supported data types
visitor_queued visitor
chat_started chat, visitor, pre_chat_survey
chat_ended chat, visitor, pre_chat_survey
chat_changed chat, visitor
ticket_created ticket
canned_response_changed canned_response

Data type: 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.

Data type: 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.

Data type: 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.

Data type: 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.

Data type: 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.

Publish your integration

Once your integration is finished, tell us about it! We’d love to guide you to the Apps Marketplace page. Reach us via chat or submit your app in the Developers Console.

If you run into any trouble, please let us know at developers@livechatinc.com or via chat.