The EkoClient class also provides a variety of accounts and error handling methods. Please make sure to first instantiate an instance of EkoClient before using any of these methods.

Display Name

The displayName is an optional property that helps users identify the user. It is used mainly for push notifications in order to identify the sender of the message, but you may also use this property for displaying user data in the UI.

However, please keep in mind that the SDK does not handle user management. If your UI requires you to display more complex user data (e.g. age, title, avatar ..etc), we recommend you to build this functionality directly into your application.

Display names are usually set on registerSession(), however, you may also set it after device registration with the following method:

client.setDisplayName('Bob Newton').catch(error => {


Roles are an array of string tags that you can assign to a user in order to help you identify the user and assign additional moderation permissions to the user. By default, a new user starts with no roles and no moderation permissions.

Roles can be created explicitly in the admin panel, or automatically via setRoles. Any roles you pass into setRoles that is not created in the system will be automatically created, and you can assign the necessary permission to it in the SDK admin panel.

client.setRoles(['moderator']).catch(error => {

User Metadata

User payload contains an optional property called metadata that allows you to store specific data on each user. It is used mainly to store user avatar urls (which we do not provide on our side).

position: "Customer Support"

Flag & Unflag Users

Users can flag and unflag other users using the UserRepository class.

To flag a user, call the following method:

import { UserRepository } from 'eko-sdk';
const userRepo = new UserRepository();
userId: 'userId'

To unflag a user, call the following method:

userId: 'userId'

Error Handling

Error Codes

Error objects can be returned to you via LiveObjects, callbacks, or from the error event emitted by the EkoClient instance. The possible error codes are listed in a public ErrorCode object: each case is named after its error and they're pretty self explanatory.

The SDK automatically handles all recoverable errors such as connection state errors without notifying you. For example, if you try to perform an action while the client is offline, the SDK will automatically retry until the action is successful. As a result, any errors returned by the SDK are returned due to unrecoverable business errors.

The error codes are always six digits, with the first three identifying the type of error, and the latter three digits identifying the specific error. Errors that are originated from the server start with 400 (therefore the server error codes will be 400xxx) and 500 (500xxx), while client errors start with 800 (800xxx).

Server Errors

  • UnauthorizedError: 400100

  • ItemNotFound: 400400

  • BadRequestError: 400000

  • Conflict: 400900

  • ForbiddenError: 400300

  • PermissionDenied: 400301

  • UserIsMuted: 400302

  • ChannelIsMuted: 400303

  • UserIsBanned: 400304

  • NumberOfMemberExceed: 400305

  • ExemptFromBan: 400306

  • MaxRepetitionExceed: 400307

  • BanWordFound: 400308

  • LinkNotAllowed: 400309

  • BusinessError: 500000

Client Errors

  • Unknown: 800000

  • InvalidParameter: 800110

  • MalformedData: 800130

  • ErrorQueryInProgress: 800170

  • ConnectionError: 800210

When an error is returned as a result of an action from your side (e.g. trying to join a channel), the action is considered completed and the SDK will not execute any additional logic.

Asynchronous Errors

The EkoClient emits an dataError event that can be observed by your application. This error event gives you a chance to be notified of errors that can potentially break the functionality of the SDK. The SDK logic is usually robust enough to automatically handle most errors, as such, only unrecoverable errors are exposed through this delegate (for example, if the login session was invalidated).

We recommend you to always handle these errors in a production app by gracefully disabling messaging functionality in the event of an error.