Thousands of businesses rely on Hipmob to keep their customers happy. See some here.

Hipmob Chat Events


Overview

Hipmob provides hosted live chat for mobile applications. You sign up with us, we give you a code, you download our library, you integrate it into your app, and you can then talk to your users, figure out what they want and what problems they are having, and make them happy. No servers, no extra steps or code to write, wherever the users are, you get to focus on what you do well. This document discusses the use of Hipmob's chat events to integrate external systems with the Hipmob platform.
When a user connects to the Hipmob communication network the chat connection goes through a number of states: there's the initial connection, individual messages received from the user, changes in context as the user navigates, and then the connection end. In more advanced deployment scenarios external systems may want to be kept informed of these state changes. Hipmob provides a set of events that can be monitored using webhooks: for each Hipmob application ID you can configure one or more webhook URLs, and for each connection that is created subsequent to the webhook URL being configured the Hipmob communication network will make a GET or a POST to the webhook URL with a variety of event data. This is ideal for companies that want to integrate Hipmob chats with internal systems (for example, internal CRM platforms).

Configuring Webhooks

Log into the Hipmob management console at https://manage.hipmob.com/#apps using your Hipmob account, select the My Apps tab and then click on the Settings button for the app you're configuring to get the application settings screen as shown in Figure 1 below. Click on the Webhooks button in the left menu.

Figure 1: application settings

Once on the Webhooks settings panel enter the URL for your webhook. You can also choose whether you'd like the webhook delivered with an HTTP POST or an HTTP GET. Finally, you can choose to send additional data with the request: this could be used to transmit information such as API keys required by your webhook. Click the Update button to save the changes.

Figure 2: adding a webhook

A confirmation will be shown as seen in Figure 3 below once the webhook has been saved. You can use the buttons next to the webhook to edit it or delete it, and you can add as many webhook URLs as you'd like.

Figure 3: saved webhook

Receiving a Webhook

You'll need to configure your server to receive the URL requests from the webhook: how you do this will depend on how your website is setup. For example, if you are using PHP, you can create a new PHP file on your server; for languages and frameworks like Python and Django or Flask that use routing you'd add a new route that would receive requests for the webhook URL. The implementation is entirely up to you.
It is recommended that all webhooks URLs be SSL-encrypted: your live chat sessions will often contain privileged user information and this will often be sent as part of the webhooks. For maximum protection this data should always be encrypted.
The webhook request is done with an HTTP POST by default; when configuring the webhook you can choose to receive an HTTP GET. POST is recommended for maximum compatibility.

Requests

Requests are made with a connection timeout duration of 15 seconds: once the webhook connection is initiated it must successfully connect to the webhook server within 15 seconds, or the connection is aborted. If the connection is aborted the request will NOT be retried.
Requests are made with the HipmobProxy user agent: the User-Agent header will be set to HipmobProxy/{version}. The current version is 0.2 but the version number may change in the future: webhooks should be able to function with any version number.
The Content-Type header will be set to application/x-www-form-urlencoded; charset=utf-8 if the request is a POST: if it is a GET the Content-Type header will not be present.
The X-Hipmob-Session-Id header will be set to a unique identifier for the chat session: all requests sent from the same chat session will have the same X-Hipmob-Session-Id header value.

Responses

Responses must complete within 15 seconds of the request connection being made: if they do not then the connection is closed and no response is processed. If the connection is closed due to a timeout the webhook request will NOT be retried.
The HipmobProxy user agent handles cookies: you can use Set-Cookie response headers to add one or more cookies and those cookie(s) will be available in all subsequent requests. You can also remove cookies and they will be removed from subsequent requests.
All responses MUST have the Content-Type response header set to application/vnd.com.hipmob.ChatCommand+json; version=1.0. The response body MUST be a JSON array: currently the array must be empty. Future updates will support sending commands back to the chat session.

Events

Each event is sent as a separate request, and at most one request will be sent a time. The supported events are outlined below: future updates may add new events, but none of the existing events will be removed. All requests include a number of common request parameters or form parameters:
  • app: the Hipmob application ID of the chat session.
  • appname: the name of the Hipmob application ID of the chat session.
  • event: the name of the event. This will currently be either chat.started, chat.away, and chat.ended.
  • started: the UTC time (in ISO8601 format) that the chat session was created.
  • ip: the IP address that the chat session comes from.
  • platform: the platform that the chat was initiated from. This can be ios, android or a platform/browser such as Windows/Firefox.
  • version: the application version that initiated the chat.
  • timestamp: the UTC time (in ISO8601 format) at which the event occured.
  • id: the user identifier for the end-user in the chat. This is either a Hipmob-generated unique identifier or an identifier supplied by the host application (such as an iOS or Android application).
  • email (Optional): the Hipmob email endpoint for this user in this chat. The contents of any email sent to this email address will be routed to the user. See the email integration documentation for more information.
  • visits: the total number of times that this user has been seen in the past.
  • locale: the locale code supplied by the user's device or browser: for example, us.
  • userdata:context (Optional): the user context (such as the web page currently being viewed or context information supplied by the host application).
  • body (Optional): the event content.

chat.started

The chat.started event is fired when the chat session begins. The event parameter will be set to chat.started. The body parameter is not present in this request.

chat.away

The chat.away event is fired when the user on the other end of the chat goes away. The event parameter will be set to chat.away. The body parameter will be a string that will be one of the following 3 values:
  • no connections: sent when all chat connections are closed by the user (for example, every browser window is closed).
  • connection idled: sent when the chat connection is idle for a specific duration. Typically this occurs with mobile clients when the user has no activity for a specific period of time and the connection is closed to optimize battery life on the mobile device.
  • server shutdown: sent when the chat server shuts down.

chat.ended

The chat.ended event is fired when the chat session is closed. This can occur either becaues the operator forced the session to end using a #done or #boot command, or if all connections to the chat session end and the session timeout fires. The event parameter will be set to chat.ended. The body parameter will be the session transcript as a JSON string: if this string is parsed, the value will be a JSON array. Each member in the array will be a JSON string: parsing each entry will return a JSON object with a number of properties that are discussed below. The entries will be in chronological order.
  • type: will be one of start (the start of the transcript), available (an operator was available), accept (an operator accepted the chat), cmd (an operator sent a command), tag (a tag was applied to the chat session), msg (a message was sent to the user by an operator or sent by the user to an operator), update (the user's name, email or context was updated), disconnect (a connection to the chat session was ended, such as a browser window closing).
  • timestamp: the UTC timestamp in milliseconds when the event was added to the transcript.
  • operator: appears on all transcript entries where the type is set to msg. Will be true if the message is to the chat user, false if the message is from the chat user.
  • msg: is an optional property that appears on certain transcript entries. For transcript entries where the type is set to msg and operator is set to false the msg value will be the text of the message sent by the user.
  • detail: is an optional property that appears on certain transcript entries. For transcript entries where the type is set to msg and the operator is set to true the detail value will contain a JSON object with a body property equal to the message the operator sent.