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

Send Messages

Format for different chat type: single chat, group chat, and chat rooms

var id = conn.getUniqueId();                                   // create message ID
var message = new WebIM.message(/* message type */, id);     // create a message
var options = {

    /* message attributes */

    chatType: 'singleChat',                     // singleChat, groupChat, chatRoom
    if ( /* single chat */ ) { 
        chatType: 'singleChat',
    }

    if ( /* single chat */ ) { 
        roomType: false,
    } 
    else if ( /* group chat*/ ) { 
        roomType: false,
    } 
    else if ( /* chat room */ ) {
        roomType: true,
    }  

    /* success and failure blocks */
};
message.set(options);

if ( /* group chat */ ) { 
    message.setGroup("groupchat");
} 
else if ( /* chat room */ ) {
    message.body.roomType = true;
    message.setGroup("groupchat");
}  

conn.send(message.body);

Send a Text Message

var sendPrivateText = function () {
    var id = conn.getUniqueId();                    // generate a local message id
    var message = new WebIM.message('txt', id);     // create a text message
    var options = {
        msg: 'message content',                     // message content
        to: 'username',                             // receiver's Hyphenate ID or group id
        chatType: 'singleChat',                     // singleChat, groupChat, chatRoom
        roomType: false,                            // False for single and group chat. True for chat room.
        success: function (id, serverMsgId) {
            console.log("send text successfully");  
        }
        fail: function () {
            console.log('send text failed');
        }
    };
    message.set(options);
    message.setGroup('groupchat')                   // Add this line for group chat and chat room,
    conn.send(message.body);
};

Send Image Message

document.addEventListener('paste', function (e) {
    if (e.clipboardData && e.clipboardData.types) {
        if (e.clipboardData.items.length > 0) {
            if (/^image\/\w+$/.test(e.clipboardData.items[0].type)) {

                var blob = e.clipboardData.items[0].getAsFile();
                var url = window.URL.createObjectURL(blob);
                var id = conn.getUniqueId();                 // create local message id

                var message = new WebIM.message('img', id);  // create image message
                message.set({
                    apiUrl: WebIM.config.apiURL,
                    file: {data: blob, url: url},
                    to: 'username',                          // message receiver's user ID
                    roomType: false,
                    chatType: 'singleChat',
                    onFileUploadError: function (error) {
                        console.log("Error");
                    },
                    onFileUploadComplete: function (data) {
                        console.log("Complete");
                    },
                    success: function (id) {
                        console.log("Success");
                    }
                });

                conn.send(message.body);
            }
        }
    }
});

Send File Message

Web SDK sends an image/audio/file with the following steps:

  1. Upload the image/audio/file to the server and get information on the image/audio/file from the server.
  2. Send the message including the basic information, server URL, secret etc.
var sendPrivateImg = function () {
    var id = conn.getUniqueId();                   // create local message id
    var message = new WebIM.message('img', id);    // create image message
    var input = document.getElementById('image');  // select input of image
    var file = WebIM.utils.getFileUrl(input);      // convert image to binary file
    var allowType = {
        'jpg': true,
        'gif': true,
        'png': true,
        'bmp': true
    };
    if (file.filetype.toLowerCase() in allowType) {
        console.log('send');
        var option = {
            apiUrl: WebIM.config.apiURL,
            file: file,
            to: 'username',                        // receiver's id
            roomType: false,
            chatType: 'singleChat',
            onFileUploadError: function () {       // message upload failure
                console.log('onFileUploadError');
            },
            onFileUploadComplete: function () {    // message upload completion
                console.log('onFileUploadComplete');
            },
            success: function () {                 // message delivered successfully
                console.log('Success');
            },
            flashUpload: WebIM.flashUpload
        };
        message.set(option);
        conn.send(message.body);
    }
};

Send Command Message

var id = conn.getUniqueId();                   // generate a local message id
var message = new WebIM.message('cmd', id);    // create a command message

message.set({
    message: "message to be sent",
    to: "username",
    action : 'action',                         // user-defined, compulsory
    ext :{"extmsg":"extends messages"},        // extended message content (same can be used in group chat)
    success: function ( id, serverMsgId ) {}  
}); 

if ( /*send a command message to a group*/ ) { 
    message.setGroup("groupchat");
} else if ( /*send a command message to a chat room*/ ) {
    message.body.roomType = true;
    message.setGroup("groupchat");
}   

conn.send(message.body);

Receive Messages

See Add Callback Functions

Handle Messages

After registering different message receiving handlers, the handlers can parse the message body, locate the chatting contact, and add the message to the chat window. Visit webim.hyphenate.io to see how it works.

Note that an image/audio/file must be downloaded before it is displayed or played.

Emoji Message

If the property emoji is added to web IM, then it will automatically concatenate the stream of characters into a text string that matches WebIM.emoji {type: 'emoji (or txt)', data:''} that represents the corresponding emoji symbol.
If type='emoji', data represents the emoji file path. If type='txt', data represents text messages

conn.listen({
    onEmojiMessage: function (message) {

        var data = message.data;
        for(var i = 0 , l = data.length ; i < l ; i++){
            console.log(data[i]);
        }
    },
});

Image Message

conn.listen({
    onPictureMessage: function (message) {

        var options = {url: message.url};
        options.onFileDownloadComplete = function () {
            console.log('Image download complete!');
        };
        options.onFileDownloadError = function () {
            console.log('Image download failed!');
        };
        WebIM.utils.download.call(conn, options); 
     }, 
});

Audio Message

conn.listen({
    onAudioMessage: function (message) {

        var options = { url: message.url };
        options.onFileDownloadComplete = function ( response ) { 
            console.log('audio file download complete!');
        };   
        options.onFileDownloadError = function () {
            console.log('audio file download failed!');
        };  
        options.headers = { 
            'Accept': 'audio/mp3'    // audio format in mp3
        };
        WebIM.utils.download.call(conn, options);
    }
})

Message History

The Hyphenate Web SDK doesn't provide storage for message history. If you need message history, you'll need to obtain messages using REST API directly and setup webhooks to push messages to your application server for long-term storage and retrieval.

Message Delivery and Read Status

var bodyId = message.id;         // ID of message delivered
var msg = new WebIM.message('read', msgId);
msg.set({
    id: bodyId,
    to: message.from
});
Demo.conn.send(msg.body);

Expect read message to be received on callback function onReadMessage.

Messages


Suggested Edits are limited on API Reference Pages

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