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.
The Link header will be set to include a number of URLs that support sending commands back to the session in an asynchronous fashion (the rel=command Link header value), reading the session history (the rel=history Link header value) and retrieving information about the session (the rel=info Link 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: the array can contain any number of commands as described in the Commands section below. Any commands sent back will be applied 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 be one of the event types discussed below.
  • 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.
  • properties (Optional): the event properties.
  • stopped (Optional): the timestamp (in ISO8601 format) for when the session ended (if the session has been ended).
  • userdata:* (Optional): a number of user data properties are present if they are available to the chat session. These include name, location, email, latitude, longitude, and custom (for any custom data provided by the session).
  • state (Optional): custom data provided by the webhook configuration when it was created in the Hipmob administrative console.

user.created

The user.created event is fired when a chat session is initiated by a visitor or user who has never been seen before. The event parameter will be set to user.created. The body parameter is not present in this request. The chat session is not yet completely setup: the response to this event MUST NOT include any commands to be applied to the chat session.

chat.ident

The chat.ident event is fired when a chat session is initiated with a custom identifier (as opposed to an automatically Hipmob-assigned identifier). The event parameter will be set to chat.ident. The body parameter will be the customer-supplied identifier. The chat session is not yet completely setup: the response to this event MUST NOT include any commands to be applied to the chat session.

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. The chat session is now completely setup: the response to this (and any subsequence events) can include commands to be applied to the chat session.

chat.accept

The chat.accept event is fired when the chat session is accepted by a specific operator. The event parameter will be set to chat.accept. The body parameter is set to the Hipmob username of the operator that accepted the chat. The properties parameter is set to a JSON object that includes a single member, from, the display name of the operator.

chat.message

The chat.message event is fired when a text message is sent by the visitor/app user. The event parameter will be set to chat.message. The body parameter is set to the text of the message. The properties parameter is set to a JSON object that includes a single member, as, which is set to the value text.

chat.contextupdate

The chat.context event is fired when the chat session context changes: this could be in response to a user navigation event (such as a web page traversal) or an explicit API call by the app or website to set the context. The event parameter will be set to chat.contextupdate. The body parameter is set to the new context (such as the new URL that the user navigated to). If additional context properties were specified when the context was changed, the properties parameter is set to a JSON object that includes all the additional context properties.

chat.reconnected

The chat.reconnected event is fired when a new connection is established from the visitor's browser or app: this may be beacuse of mobile device movement, or a page transition in a browser tab. The event parameter will be set to chat.reconnected. The body parameter is not present.

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

The chat.returned event is fired when the user on the other end of the chat returns (after going away): this event will only be seen if a previous chat.away event was received. The event parameter will be set to chat.returned. The body parameter will be the string "client is active".

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.

Commands

The response to a web hook can include commands to be applied the chat session. These commands can alter the session, send messages to the user or adjust the user availability. Each command is a JSON object: when responding to a request (or using the rel=command Link url to send one or more commands asynchronously) the body will be a JSON array containing zero or more command objects. If the array is empty, no commands will be executed. Supported commands are listed below: an example response that sends one message, waits 3 seconds and then sends another message would look like this.
		    [{ command: "say", message: "Wait for it..." }, { command: "pause", value: 3 }, { command: "say", message: "Thank you!" }]
		  

Disconnect

Closes the chat session completely. The message format is:
		    { command: "disconnect" }
		  

Pause

Pauses processing of webhook commands for the specified duration (in seconds). This can be used to insert delays.
		    { command: "pause", value: 10 }
		  

Filter

Instructs the web hook processing system to only send events that match this filter's specified selection. This can be used to restrict traffic to only events that are of interest: for example, if the web hook only wants to know when a session ends, then it can provide a filter spec of chat.ended and it will only be called when the chat is over. The filter value is an array of event types.
		    { command: "filter", value: ["chat.ended"] }
		  

Redirect

Instructs the web hook processing system to send events for this webhook to a different URL: this allows for transfers of control by a webhook. The provided URL must be a valid HTTP or HTTPS url, and a method can optionally be provided (which must be either GET or POST). If no method is provided, then the POST method will be used for the new webhook URL. Please note that the current request will NOT be retried with the new URL: the new URL will only receive subsequent events.
		    { command: "redirect", url: "", method: "POST" }
		  

Say

Sends a text message to the chat visitor or app user.
		    { command: "say", message: "Hi there, how are you doing?" }
		  

Open URL

Sends a request to open a specified URL on the app user's device or in the chat visitor's browser. This can be used to trigger actions or to move the user to a desired screen.
		    { command: "open", url: "" }