Conversations

Channelize.io server supports two types of conversation i.e private 1-to-1 and Group conversations. This section contains what all conversations related actions can be performed using Channelize.io JavaScript SDK functions.

List Conversations

Retrieve the list of conversations of a user.

let conversationListQuery = channelize.Conversation.createConversationListQuery();

// string - Represents the userID of a conversation member/participant. This param is used if you want to get the conversation between logged in user and targeted user. (Default: null)
conversationListQuery.memberId = '20141';
// boolean - Set to true, if you want to retrieve only group conversations. (Default: null)
conversationListQuery.isGroup = true;
// boolean - Represent if deleted conversations (Soft deleted) should be included in the response. (Default: false)
conversationListQuery.includeDeleted = true;
// boolean - Retrieves the conversations in which the user is active. (Default: true)
conversationListQuery.includeOnlyActive = true;
// string - Represents extra fields, if you want to include extra fields with the conversation model objects. Allowed value is 'messages' for now. (Default: null)
conversationListQuery.include = 'messages';
// string - Represents sorting criteria. Allowed values are updatedAt ASC && updatedAt DESC. (Default: updatedAt ASC)
conversationListQuery.sort = 'updatedAt ASC';
// number - Represents the number of conversations. (Default: 25)
conversationListQuery.limit = 25;
// number - Represents the number of items to be skipped from the beginning. (Default: 0)
conversationListQuery.skip = 0;

conversationListQuery.list(function (err, conversations) {

});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
conversations Indicates the response which will be an array of conversation's object. If memberId is set, the response is conversation's object instead of an array.

Get Conversations Count

Retrieves the count of conversations of a user.

let conversationListQuery = channelize.Conversation.createUserListQuery();

// boolean - Represents if the conversation is a group conversation or 1-to-1 conversation.
conversationListQuery.isGroup = true;
// boolean - Represents if deleted conversations should be counted.
conversationListQuery.includeDeleted = true;
// boolean - Represents if only active conversations should be counted.
conversationListQuery.includeOnlyActive = true;

conversationListQuery.count(function (err, res) {

});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates response object having count as property. { "count": 15 }

Get a Conversation

Retrieves information about a conversation.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

});

Function Params

This table lists all possible parameters this function supports.

Name	Type	Description
conversationId	string	The unique ID of the conversation to retrieve.
include	string	Specifies extra fields if you want extra information to be appended with the conversation objects. Allowed value is messages.

Callback Params

err Indicates if there is an error. It will be null if there is no error.
conversation Indicates conversation's object.

Create a Conversation

Creates a new conversation.

channelize.Conversation.createConversation(data, function (err, conversation) {

});

Function Params

data is a JavaScript object having below properties. It will be different for 1-to-1 and Group conversations.

Data Properties for Group Conversations

Name	Type	Required	Description
id	string	no	The unique ID of the conversation.
title	array	yes	The name of the conversation.
isGroup	boolean	no	Determines whether to create a group conversation or private 1-to-1 conversation. If set to true, group conversation will create. If set to false, a private 1-to-1 conversation will create.
profileImageUrl	string	no	The URL of the conversation's profile image.
createdAt	date object	no	The timestamp when the conversation was created.
members	array	yes	Specifies an array of user IDs to add to the conversation. E.g. ["20236", "20697", "19116"]

Data Properties for 1-to-1 Conversations

Name	Type	Required	Description
id	string	no	The unique ID of the conversation.
isGroup	boolean	no	Determines whether to create a group conversation or private 1-to-1 conversation. If set to true, group conversation will create. If set to false, a private 1-to-1 conversation will create.
createdAt	date object	no	The timestamp when the conversation was created.
members	array	yes	Specifies an array of user IDs to add to the conversation. E.g. ["20236", "20697", "19116"]

Callback Params

err Indicates if there is an error. It will be null if there is no error.
conversation Indicates conversation's object.

Conversation Model Object

A conversation's object can be retrieved either using get conversation method or through various services methods.

{  
    "id":"1021",
    "title":"Testing New Messenger",
    "memberCount":2,
    "isGroup":false,
    "ownerId":"18859",
    "createdAt":"2019-05-23T16:14:15.737Z",
    "membersList":[  
        {  
            "id":"74157F21-15AF-451A-AFA7-01CF91269016",
            "userId":"18859",
            "chatId":"1021",
            "lastSeenMessageId":"4492e828-7123-429d-ac6b-e64ce1830927",
            "newMessageCount":3,
            "mute":false,
            "isActive":true,
            "isAdmin":true,
            "isDeleted":false,
            "lastMessageId":"2DC0DB04-494B-4AFA-8EAD-AC4CC8EEEE51",
            "updatedAt":"2019-05-23T12:04:38.545Z",
            "user":{  
                "id":"18859",
                "displayName":"Channelize Demo User 1",
                "profileImageUrl":"http://mobiledemodevelopment.s3.amazonaws.com/public/user/17/0a/02/fbef1bb47eb85fb2979b135ed04e0eb3.png",
                "isOnline":false,
                "lastSeen":"2019-05-23T11:02:48.937Z"
            },
            "lastMessage":{  
                "id":"2DC0DB04-494B-4AFA-8EAD-AC4CC8EEEE51",
                "attachmentType":"text",
                "contentType":0,
                "body":"test",
                "ownerId":"20697",
                "recipients":[  
                    {  
                        "id":"f064f810-7d52-11e9-8d96-9d04e22fe990",
                        "recipientId":"18859",
                        "status":1,
                        "createdAt":"2019-05-23T12:04:38.545Z"
                    },
                    {  
                        "id":"f064f811-7d52-11e9-8d96-9d04e22fe990",
                        "recipientId":"20697",
                        "status":1,
                        "createdAt":"2019-05-23T12:04:38.545Z"
                    }
                ],
                "owner":{  
                    "id":"20697",
                    "displayName":"Channelize Demo User",
                    "profileImageUrl":"http://mobiledemodevelopment.s3.amazonaws.com/public/user/33/19/02/b5ceb45b2d6c74e4fc89673a5675c09c.jpg"
                },
                "tags":[  

                ]
            }
        },
        {  
            "id":"6A229C5F-9379-4CC6-8098-A24D9B90330E",
            "userId":"20697",
            "chatId":"1021",
            "lastSeenMessageId":"2DC0DB04-494B-4AFA-8EAD-AC4CC8EEEE51",
            "newMessageCount":1,
            "mute":false,
            "isActive":true,
            "isAdmin":false,
            "isDeleted":false,
            "lastMessageId":"2DC0DB04-494B-4AFA-8EAD-AC4CC8EEEE51",
            "updatedAt":"2019-05-23T12:04:38.545Z",
            "user":{  
                "id":"20697",
                "displayName":"Channelize Demo User",
                "profileImageUrl":"http://mobiledemodevelopment.s3.amazonaws.com/public/user/33/19/02/b5ceb45b2d6c74e4fc89673a5675c09c.jpg",
                "isOnline":false,
                "lastSeen":"2019-05-23T12:24:20.299Z"
            },
            "lastMessage":{  
                "id":"2DC0DB04-494B-4AFA-8EAD-AC4CC8EEEE51",
                "attachmentType":"text",
                "contentType":0,
                "body":"test",
                "ownerId":"20697",
                "recipients":[  
                    {  
                        "id":"f064f810-7d52-11e9-8d96-9d04e22fe990",
                        "recipientId":"18859",
                        "status":1,
                        "createdAt":"2019-05-23T12:04:38.545Z"
                    },
                    {  
                        "id":"f064f811-7d52-11e9-8d96-9d04e22fe990",
                        "recipientId":"20697",
                        "status":1,
                        "createdAt":"2019-05-23T12:04:38.545Z"
                    }
                ],
                "owner":{  
                    "id":"20697",
                    "displayName":"Channelize Demo User",
                    "profileImageUrl":"http://mobiledemodevelopment.s3.amazonaws.com/public/user/33/19/02/b5ceb45b2d6c74e4fc89673a5675c09c.jpg"
                },
                "tags":[  

                ]
            }
        }
    ]
}

You can call various functions through this conversation model object directly. These functions are mentioned below:

Add Members

Adds a member to the conversation.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.addMembers(memberIds, function (err, res) {

    });
});

Function Params

This table lists all possible parameters this function supports.

Name	Type	Description
memberIds	array	Specifies an array of user IDs to add to the conversation. E.g. ["20236", "20697", "19116"]

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates the response. It will be a null value for this case.

Remove Members

Removes a member from the conversation.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.removeMembers(memberIds, function (err, res) {

    });
});

Function Params

This table lists all possible parameters this function supports.

Name	Type	Description
memberIds	array	Specifies an array of user IDs to add to the conversation. E.g. ["20236", "20697", "19116"]

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates the response. It will be a null value for this case.

Add Admin

Grants group admin permission to a user. Only an existing member/participant of the group can be admin of the group conversation.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.addAdmin(userId, function (err, res) {

    });
});

Function Params

This table lists all possible parameters this function supports.

Name	Type	Description
userId	string	The unique ID of the user who is going to be the new group conversation admin.

Callback Parameters

err Indicates if there is an error. It will be null if there is no error.
res Indicates the response. It will be a null value for this case.

Clear Conversation

Clears a targeted conversation.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.clear(function (err, res) {

    });
});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates the response. It will be a null value for this case.

Leave a Conversation

Leaves the targeted conversation for a user.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.leave(function (err, res) {

    });
});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates the response. It will be a null value for this case.

Delete Conversation

Deletes a targeted conversation. The conversation is deleted at logged-in user’s end but appears at other member’s end.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.delete(function (err, res) {

    });
});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates the response. It will be a null value for this case.

Mark Messages Read

Mark all messages 'Read' in a targeted conversation for a user.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.markAllMessageRead(function (err, res) {

    });
});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates the response. It will be a null value for this case.

Update Title

Updates the title of a group conversation and send a meta-message in the conversation.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.updateTitle(title, function (err, res) {

    });
});

Function Params

This table lists all possible parameters this function supports.

Name	Type	Description
title	string	Specifies the title for the conversation.

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates the response. It will be a null value for this case.

Update Profile Photo

Updates the profile image of a group conversation and send a meta-message in the conversation.

<input type="file" id="profile">

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err);

    let file  = document.getElementById('profile').files[0];

    conversation.updateprofilePhoto(file, function (err, updatedConversation) {


    });
});

Function Params

This table lists all possible parameters this function supports.

Name	Type	Description
file	fileobject	Specifies the file object.

Callback Params

err Indicates if there is any error. It will be null if there is no error.
updatedConversation Indicates updated conversation's object.

Mute a Conversation

Mutes a coversation for a user.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.mute(function (err, res) {

    });
});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates the response. It will be a null value for this case.

Unmute Conversation

Unmute a coversation for a user.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.unmute(function (err, res) {

    });
});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates the response. It will be a null value for this case.

Start Typing

Triggers typingStatusUpdated event callback for all active members of the conversation when a group member starts typing.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err);

    conversation.startTyping(function (err, res) {


    });
});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res res is a JavaScript object having userId, conversationId and typing status properties.

Stop Typing

Triggers typingStatusUpdated event callback for all active members of the conversation when a group member stops typing.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err);

    conversation.stopTyping(function (err, res) {


    });
});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res res is a javascript object having userId, conversationId and typing status properties.

Get Messages

Retrieves the list of messages from a conversation.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    let messageListQuery = conversation.createMessageListQuery();
    
    // number - Represent the type of a message. Allowed Values are 0, 1, 2 and 3.
    // 0: For text, image, audio and video message.
    // 1: For meta messages.
    // 2: For sticker/gif type message.
    // 3. For location type message.
    messageListQuery.contentType = 0;
    // string - represent the attachment type of a message. It can be text, image, audio or video. Use comma separated for multiple values.
    messageListQuery.attachmentType = 'text';
    // string - represent user id of message owner.
    messageListQuery.ownerId = '20141';

    // string - represent sorting criteria in user's display names. Allowed values are updatedAt ASC && updatedAt DESC
    messageListQuery.sort = 'updatedAt ASC';
    // number - represent number of items.
    messageListQuery.limit = 50;
    // number - represent number of items to be skipped from begining.
    messageListQuery.skip = 0;

    messageListQuery.list(function (err, messages) {

    });

});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
messages Indicates the response which will be an array of message's object.

Get Messages Count

Retrieves the total number of messages in a conversation.

let messageListQuery = channelize.Conversation.createMessageListQuery();

// number - Represents the type of a message count to retrieved. Allowed Values are 0,1,2 and 3 for text/media, meta message, sticker/gif and location messages respectively.
messageListQuery.contentType = 0;
// string - Represents the attachment type of a message whose count to include. It can be text, image, audio or video. Multiple values can also be passed in attachmentType as comma separated values.
messageListQuery.attachmentType = 'text';
// string - Represents the userID of the message owner.
messageListQuery.ownerId = '20141';

messageListQuery.count(function (err, res) {

});

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates response object having count as property. { "count": 15 }

Send a text Message

Sends a text message in a conversation using conversation model object.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.sendTextMessage(body, tags, function (err, message) {

    });
});

Function Params

This table lists all possible parameters this function supports.

Name	Type	Description
body	string	The content of the message.
tags	array	Specifies an array of members that are tagged/@mentioned in a message. If no member is tagged, then pass an empty array.

Using the tags parameter, you can tag or @mention members in the group conversation as used below:

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    // For Message: "Hey @Alen Joe and @Sydney Millers, How are you ?'
    let body = 'Hey %s and %s, How are you ?'
    let tags = [{
        userId: '18859',
        order: 1,
        wordCount: 2
    }, {
        userId: '20697',
        order: 2,
        wordCount: 2
    }];
    conversation.sendTextMessage(body, tags, function (err, message) {

    });
});

If a message object has tags in it, then %s in the body should be replaced with the @mentioned users in their respective order.

Tags Params

Name	Type	Description
userId	string	The unique ID of the user you want to tag/@mention.
order	array	Specifies the order in which tagged/mentioned users need to be displayed.
wordCount	array	Specifies the number of words you want to display for a tagged/mentioned users. This is useful when a user wants to show only first name "Alen" for a user "Alen Joe" when tagged/mentioned.

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates response which will be message model's object.

Send Location Message

Sends a location message in a conversation using conversation model object.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.sendLocationMessage(location, function (err, message) {

    });

});

Function Params

This table lists all possible parameters this function supports.

location is a JavaScript object having below properties.

Name	Type	Description
latitude	number	Specifies the latitude of location.
longitude	number	Specifies the longitude of location.
title	string	Specifies the name for the location.
address	string	Specifies the address of the location.

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates response which will be message model's object.

Send File Message

Sends a file message in a conversation using the conversation model object.

<input type="file" id="file">

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    let file  = document.getElementById('file').files[0];
    
    conversation.sendFileMessage(file, createThumbnail, function(err, message) {
        
    });
});

Function Params

This table lists all possible parameters this function supports.

Name	Type	Description
file	FileObject	Specifies the file object. Allowed file types are image, video and audio files.
createThumbnail	boolean	Specifies if you want to create thumbnail for this file.

The file provided will be stored on the Channelize server. If you want to store the file separately on your server, you have to send the file as a javascript object with the below properties.

File Object Params

Name	Type	Required	Description
name	string	yes	Name of the file.
mimeType	string	yes	Specifies the MIME type of file.
attachmentType	string	yes	Specifies the type of file. Allowed values are an image, audio, and video.
extension	string	yes	Specifies the extension of the file.
fileUrl	string	yes	The file URL where a file is stored. This URL should be publicly accessible.
thumbnailUrl	string	no	The thumbnail URL where thumbnail has been stored. This URL should be publicly accessible.

Callback Params

err Indicates if there is an error. It will be null if there is no error.
res Indicates response which will be message model's object.

Quote/Reply Message

Quotes/Replies a message in a conversation.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    conversation.quoteMessage(parentMessageData, body, function(err, message) {
        
    });

});

Function Params

body represents the content of new message and should be of string type.

parentMessageData will be a JavaScript object representing the data of parent message. It should have the below properties. All of them are mandatory.

Name	Type	Description
id	string	The unique ID of the parent message.
body	string	Content of the parent message.
attachmentType	string	Specify the attachment type of the parent message. Allowed values are an image, audio, and video.

Callback Params

err Indicates if there is any error. It will be null if there is no error.
res Indicates response which will be message model's object.

Miscellaneous methods

Get Last Message

Get the last message of the conversation by conversation.getLastMessage() method.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    let lastMessage = conversation.getLastMessage();
});

Get Active Members

Get the last message of the conversation by conversation.getActiveMembers() method.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    let members = conversation.getActiveMembers();
});

To Object

Get the json representation of your conversation model object.

channelize.Conversation.getConversation(conversationId, include, function (err, conversation) {

    if (err) return console.error(err); 

    let conversationData = conversation.toObject();
});

Channelize.io | Docs

v1

List Conversations

Get Conversations Count

Get a Conversation

Create a Conversation

Conversation Model Object

Add Members

Remove Members

Add Admin

Clear Conversation

Leave a Conversation

Delete Conversation

Mark Messages Read

Update Title

Update Profile Photo

Mute a Conversation

Unmute Conversation

Start Typing

Stop Typing

Get Messages

Get Messages Count

Send a text Message

Send Location Message

Send File Message

Quote/Reply Message

Miscellaneous methods

Get Last Message

Get Active Members

To Object