Hyphenate Docs

Start Chatting with Hyphenate!

Welcome to the Hyphenate docs portal. Here you'll find comprehensive guides and technical documentation to help you integrate Hyphenate In-App Chat.

Get Started

Install the Web SDK

Web SDK and Demo App

You can leverage the demo app to integrate chat features with the Hyphenate Mobile Instant Messaging (MIM) platform for mobile or web apps.

Run the demo app

  • Run live demo app demo.hyphenate.io

  • Run from the sources
    Option 1: Download Web SDK and Demo or Run $ git clone https://github.com/HyphenateInc/Hyphenate-SDK-Web.git in the destinate folder
    Option 2: Install via NPM by running command npm install hyphenate-web
    hyphenate web demo and SDK on NPM

  • Replace the API key created from the Hyphenate console
    Update API key value in file webim.config.js: Go to folder /demo/javascript/dist/webim.config.js.

  • Double click to open index.html from the browser directly or deploy on your web server


  • Demo is based on React
  • Sign in on multiple devices / have multiple sessions running simultaneously isMultiLoginSessions:true
  • Perform an extra layer of security check for HTTP / IP to prevent DNS hijacking isHttpDNS:true
  • Real time one-to-one and group chat
  • File, photo/video, and location sharing
  • Video/Voice calling for browsers support https+Webkit

Getting Started

Install hyphenate-web SDK

Install via NPM with command npm install hyphenate-web. Hyphenate-web package on NPM

Option 1 (Recommended) - configure package.json

  1. Add library dependency to package.json file,

    "dependencies": {
     "hyphenate-web": "^1.4.5",
  2. Run the command $ npm install in the app Terminal.

Option 2
or install the SDK manually by hitting command in the app Terminal on Mac

npm install hyphenate-web

Configure local files

  1. Copy the following files to proper directory /sdk/dist/strophe-1.2.8.min.js, /sdk/dist/websdk-1.4.11.js, /demo/javascript/dist/webim.config.js

  2. Import the script files in the following order into newly created html file

<script type='text/javascript' src='webim.config.js'></script>
<script type='text/javascript' src='strophe-1.2.8.min.js'></script>
<script type='text/javascript' src='websdk-1.4.11.js'></script>

Configure webpack.config.js

The paths are related to demo web project

var webpack = require('webpack');
path = require('path');

module.exports = {
    entry: {
        './sdk/dist/websdk-1.4.5': ['./sdk/index'],                             // Hyphenate web SDK
        './demo/javascript/dist/demo-1.4.5': ['./demo/javascript/src/entry'],   // demo entry point
        './webrtc/dist/webrtc-1.4.5': ['./webrtc/src/entry']                    // webrtc

Install the dependencies

$ npm i

Run the app

Dev environment

$ npm run dev

Create production package and place it under web-im/publish

$ npm run prod

Run in the browser


Configure index.html

Add the Following lines to index.html file

<!-- config-->
<script src="./demo/javascript/dist/webim.config.js"></script>
    if (WebIM.config.isDebug) {
        document.write("<script src='./sdk/dist/strophe-1.2.8.js'><\/script>");
        document.write("<script src='./demo/javascript/dist/debug.js'><\/script>");
    } else {
        <!--A JavaScript library for XMPP over Websocket-->
        document.write("<script src='./sdk/dist/strophe-1.2.8.min.js'><\/script>");

<!-- Hyphenate web SDK -->
<script src='./sdk/dist/websdk-1.4.5.js'></script>

<!-- webrtc -->
    if (WebIM.config.isWebRTC) {
        document.write("<script src='./webrtc/dist/adapter.js'><\/script>");
        document.write("<script src='./webrtc/dist/webrtc-1.4.5.js'><\/script>");

Configure webim.config.js

API key

Obtain application API key (appKey) via Hyphenate developer console.

 * webim.config.js is web app configurations and urls to connect to Hyphenate server
var WebIM = {};
WebIM.config = {
     * XMPP server
    xmppURL: 'im-api.hyphenate.io',
     * Hyphenate server REST API URL
    apiURL: (location.protocol === 'https:' ? 'https:' : 'http:') + '//api.hyphenate.io',
     * Application API Key
    appkey: 'hyphenatedemo#hyphenatedemo',
     * Whether to use wss
     * @parameter {Boolean} true or false
    https: false,
     * isMultiLoginSessions
     * true: A visitor can sign in to multiple webpages and receive messages at all the webpages.
     * false: A visitor can sign in to only one webpage and receive messages at the webpage.
    isMultiLoginSessions: false,
     * Set to auto sign-in
    isAutoLogin: true,
     * Whether to use window.doQuery()
     * @parameter {Boolean} true or false
    isWindowSDK: false,
     * isSandBox=true:  xmppURL: 'api.sandbox.hyphenate.io',  apiURL: '//api.sdb.hyphenate.io',
     * isSandBox=false: xmppURL: 'api.hyphenate.io',          apiURL: '//api.hyphenate.io',
     * @parameter {Boolean} true or false
    isSandBox: false,
     * Whether to console.log in strophe.log()
     * @parameter {Boolean} true or false
    isDebug: false,
     * will auto connect the xmpp server autoReconnectNumMax times in background when client is offline.
     * won't auto connect if autoReconnectNumMax=0.
    autoReconnectNumMax: 2,
     * the interval secons between each atuo reconnectting.
     * works only if autoReconnectMaxNum >= 2.
    autoReconnectInterval: 2,
     * webrtc supports WebKit and https only
    isWebRTC: /WebKit/.test(navigator.userAgent) && /^https\:$/.test(window.location.protocol),
     * while http access,use ip directly,instead of ServerName,avoiding DNS problem.
    isHttpDNS: false

Import Third-Party Emoji Package

WebIM.Emoji = {
    path: 'demo/images/faces/',
    map: {
        '[):]': 'ee_1.png',
        '[:D]': 'ee_2.png',
        '[;)]': 'ee_3.png',
        '[:-o]': 'ee_4.png',
        '[:p]': 'ee_5.png'

Browser Version

  • Support browser Chrome 54+, Firefox 10+, Safari 6+, IE 9+.

Demo app - File Types Support

  • Image formats supported: PNG, JPG, BMP, and GIF
  • Audio formats supported: MP3, AMR, and WMV
  • File formats supported: ZIP, txt, doc, and PDF

Updated 2 years ago

Install the Web SDK

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.