Messages are simply JSON content containers, you can store up to 100KB of JSON data in the message itself, and it will be synchronized with all the users in its channel in real-time. If a message requires larger binary data (sending files, for example), we recomment you to upload the data to another cloud storage service, such as AWS S3, and store the URL to the content in the message data.

In addition to supporting the raw JSON message type, the SDK also provides support for common text and image message types. These additional types are built on top of the standard JSON message layer. In case of image messages, the SDK freely provides a cloud storage service that will process and store all uploaded images, so you don't need to setup and manage a seperate cloud storage service for this common case.

All messaging methods are contained in a MessageRepository class. Before calling any messaging methods, you must ensure to first instantiate a repository instance.

import { MessageRepository } from 'eko-sdk';
const messageRepo = new MessageRepository();

Sending Messages

All message sending methods are designed to be robust enough to work under any network conditions. When you send any message, that message will automatically be put into a queue in case of unstable network conditions. Once the SDK reconnects to the server, it will automatically resend all queued messages.

Additionally, sent messages are always returned in message queries, even before they have been delivered to the server. This is to provide the user with a fluid messaging behavior: when a user send a message, that sent message would appear in the message stream right away, instead of waiting until it has been confirmed by the server. To check or display the current status of message delivery, use the syncState property in the message model.

Text Message

Sending a standard text message is a simple method call with channelId and the message text:

const messageLiveObject = messageRepo.createTextMessage({
channelId: 'channel1',
text: 'Hello World!',

Message Query

To query for a list of all messags in a channel:

import { MessageRepository } from 'eko-sdk';
const messageRepo = new MessageRepository();
const messages = messageRepo.messagesForChannel({ channelId: 'channel1' });
messages.on('dataUpdated', data => {
// reload messages table
messages.on('dataError', error => {
console.log('Message LiveCollections can not query/get/sync data from server');
// unobserve data changes once you are finished

This method will return a LiveCollection of all messages in the specified channel. You can observe the LiveCollection in order to update your view whenever you receive new messages.

Since v1.3.0, messages can be organized in threads thanks to the parentId property.

Threaded Messages

A message can be a root for a thread. To query the children of a message thread, you can add the parentId parameter in a message query, along with the filterByParentId flag.

import { MessageRepository } from 'eko-sdk';
const messageRepo = new MessageRepository();
const messages = messageRepo.messagesForChannel({
channelId: 'channel1',
parentId: 'exampleParentMessageId',
filterByParentId: true,

When creating a message, we can also pass the parentId to make it appear under a parent.

const messageLiveObject = messageRepo.createTextMessage({
channelId: 'channel1',
text: 'Hello World!',
parentId: 'exampleParentMessageId,

Flag & Unflag Messages

Users can flag messages and unflag messages that they have flagged using the MessageFlagRepository class.

import { MessageFlagRepository } from 'eko-sdk';
const flagRepo = new MessageFlagRepository('message1');

To flag a message, call the following method:


To unflag a message, call the following method:


The User can also check if they have previously flagged the message before by calling the following asynchronous method:

const result = await flagRepo.isFlaggedByMe()

If this method has been called before in the current session, the user can also check the cached result on the message payload itself.

// Note. If the value is undefined, it means the data has not been cached

Editing Messages

A special MessageEditorRepository class is also provided for you to perform actions on messages you've sent or received. These actions include editing and deleting an existing message, as well as marking a message as being read by you.

To start, first instantiate a MessageEditor instance with the EkoClient instance you created on setup, as well as a valid messageId.

import { MessageEditorRepository } from 'eko-sdk';
const editor = new MessageEditorRepository('message1');

Edit and Delete

You can only perform edit and delete operations on your own messages. Once the operation is complete, the message's editedAtDate will be set to the current time. This allows you to provide UI to the user to inform the user of specific messages that has been edited, if needed. An optional completion block can be provided to notify you of operation success.

// edit current message with new text
editor.editText('New edited text').catch(error => {
// delete current message
editor.delete().catch(error => {

Mark Message as Read

To mark a message as being read by you, simply call the following method with an optional completion block:

editor.markRead().catch(error => {

Marking a message as read will also retroactively mark all previous messages as read by you as well. You only need to call this method once on the latest message.