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

Basic Operations

Initialize Web SDK

Create Connection

var conn = new WebIM.connection({
    isMultiLoginSessions: WebIM.config.isMultiLoginSessions,
    https: typeof WebIM.config.https === 'boolean' ? WebIM.config.https : location.protocol === 'https:',
    url: WebIM.config.xmppURL,
    heartBeatWait: WebIM.config.heartBeatWait,
    autoReconnectNumMax: WebIM.config.autoReconnectNumMax,
    autoReconnectInterval: WebIM.config.autoReconnectInterval,
    apiUrl: WebIM.config.apiURL,
    isAutoLogin: true

Add Callback Functions

    onOpened: function ( message ) {          // callback for successful login
        // if isAutoLogin is false, users need to manually update online status by setting, conn.setPresence(); 
                // Skip the following line if isAutoLogin is true 
    onClosed: function ( message ) {},         // callback for connection closed

    onOnline: function () {},                  // the local host has connected to the Internet
    onOffline: function () {},                 // the local host has disconnected from the Internet
    onError: function ( message ) {}           // callback failure

    onPresence: function ( message ) {},       // receive a user subscription request, dismissed by a group or chat room, group or chat room is deleted.

    onTextMessage: function ( message ) {},    // receive a text message
    onEmojiMessage: function ( message ) {},   // receive a emoji message
    onPictureMessage: function ( message ) {}, // receive an image message
    onCmdMessage: function ( message ) {},     // receive a command message
    onAudioMessage: function ( message ) {},   // receive an audio message
    onLocationMessage: function ( message ) {},// receive a location message
    onFileMessage: function ( message ) {},    // receive a file message
    onVideoMessage: function ( message ) {},   // receive a video message

    onRoster: function ( message ) {},         // handle a friend request
    onInviteMessage: function ( message ) {},  // handle a group invitation

Register Hyphenate IM User Account

Register Hyphenate IM account with username, password, and nickname.

var register = function () {
    var option = {
        username: 'apple',
        password: 'password',
        nickname: 'clock',
        appKey: WebIM.config.appkey,
        success: function () {
            console.log('registration succeed!');
        error: function () {
            console.log('registration error');
        apiUrl: WebIM.config.apiURL


Log in to Hyphenate Web IM with the username and password:

var options = { 
    apiUrl: WebIM.config.apiURL,
    user: "username",
    pwd: "password",
    appKey: WebIM.config.appkey



conn.close()   // log out and close the connection

Send Ajax Request

var options = {
    dataType: 'text', //default
    success: function () { //handle request success },
    error: function () { //handle request error },
    type: 'post',//default 'post',
    url: 'http://a1.hyphenate.io/weiquan2/a2/chatfiles/0c0f5f3a-e66b-11e3-8863-f1c202c2b3ae',
    headers: '', //default {}
    data: ''; //default null


Connection Troubleshooting

Q: Does the SDK support reconnection after an interruption in Internet connection?
A: No, please use the token to re-establish the connection.

Q: Unable to receive messages after logging in?
A: Make sure the user is online to receive messages. Check if the method conn.setPresence() is called after a successful login.

Q: Timeout disconnection?
A: The connection will timeout and get disconnected after certain time period.

Basic Operations

Suggested Edits are limited on API Reference Pages

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