Send your first message

This tutorial walks you through the basic integration flow for the Nexconn Chat SDK: importing, initializing, setting up listeners, connecting, and sending messages.

Prerequisites

1. Go to the Console and register a developer account. After registration, the console automatically creates an app in the development environment.
2. On the Key Management page, get the App Key for the development environment. The same page also shows the App Secret and data center.

tip

• Each app has two separate App Keys, one for development and one for production. Data is isolated between the two environments. Before you go live, switch to the production App Key and complete end-to-end testing.
• The App Secret is used to generate data signatures and is only required when calling Server APIs. Keep your App Key and App Secret confidential.

Import the SDK

tip

The Nexconn Chat SDK provides full TypeScript support. We recommend using TypeScript for better code safety and maintainability.

NPM (recommended)

1. Install the packages:

   bash

   npm install @nexconn/engine@latest @nexconn/chat@latest -S

2. Import the modules:

TypeScript

import {
  NCEngine,
  DirectChannel,
  SendTextMessageParams,
  ConnectionStatusHandler,
  MessageHandler,
} from '@nexconn/chat';

Initialize

Before using any Chat SDK features, you must call the initialization method exactly once during the entire app lifecycle.

The App Key is the unique identifier for your app. You need a valid App Key to initialize the SDK. Find your App Key in the Console.

TypeScript

import { NCEngine } from '@nexconn/chat';

// Initialize — call this only once
NCEngine.initialize({ appKey: '<Your-App-Key>' });

Set up listeners

After initialization, add event listeners to receive real-time notifications from the SDK.

TypeScript

import { NCEngine, ConnectionStatusHandler, MessageHandler } from '@nexconn/chat';

// Connection status listener
NCEngine.addConnectionStatusHandler('my-handler', new ConnectionStatusHandler({
  onConnectionStatusChanged({ status, code }) {
    console.log('Connection status:', status, 'code:', code);
  },
}));

// Message listener
NCEngine.addMessageHandler('my-handler', new MessageHandler({
  onMessageReceived({ messages }) {
    console.log('Messages received:', messages);
  },
}));

Connect to the chat server

1. To send and receive messages, you first need a registered user. In production, your app server should call the Server API to obtain an access token. See User registration. For quick testing, use the Get Token API in the Console's API debugging page to get an access token for a user with user ID 1. The response looks like this:

HTTP

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "code":200,
  "userId":"1",
  "token":"gxld6GHx3t1eDxof1qtxxYrQcjkbhl1V@sgyu.cn.example.com;sgyu.cn.example.com"
}

2. Call connect to connect the user to the chat service. The Chat SDK has a built-in reconnection mechanism, so you only need to call connect once per app lifecycle. See Connect for details.

TypeScript

import { NCEngine } from '@nexconn/chat';

NCEngine.connect({ token: '<Your-Token>' }).then(res => {
  if (res.code === 0) {
    console.log('Connected. Current user ID:', res.data?.userId);
  } else {
    console.warn('Connection failed. Code:', res.code);
  }
});

warning

• All Chat SDK business APIs (channels, messages, etc.) require a successful connection first.

Get the channel list

The Nexconn Chat SDK uses different classes for different channel types:

Channel type	Class	targetId
Direct channel	DirectChannel	The other user's ID
Group channel	GroupChannel	Group ID
Open channel	OpenChannel	Open channel ID
Community channel	CommunityChannel / CommunitySubChannel	Community channel ID

TypeScript

import { BaseChannel, BaseChannel as BC } from '@nexconn/chat';

// Get the channel list (paginated)
const query = BaseChannel.createChannelsQuery({ pageSize: 20 });
const { code, data: channelList } = await query.loadNextPage();
if (code === 0) {
  console.log('Channel list:', channelList);
} else {
  console.log('Failed to get channel list. Code:', code);
}

Send a message

Send a text message to a user with userId 2. Besides text messages, you can also send images, files, voice messages, and more. See Message types.

TypeScript

import { DirectChannel, SendTextMessageParams } from '@nexconn/chat';

// Create a direct channel instance (targetId is the other user's ID)
const channel = new DirectChannel('2');

// Send a text message
const params = new SendTextMessageParams({ text: 'Hello, Nexconn!' });
const { code, data } = await channel.sendMessage(params);
if (code === 0) {
  console.log('Message sent:', data);
} else {
  console.log('Send failed. Code:', code);
}

Receive messages

Incoming messages are delivered through the message listener registered with NCEngine.addMessageHandler. See the Set up listeners section above.

Get remote messages

Example: Get remote messages from a direct channel with user 2.

TypeScript

import { DirectChannel, BaseChannel } from '@nexconn/chat';

const channel = new DirectChannel('2');

// Paginated fetch of remote messages
const query = BaseChannel.createMessagesQuery({
  channelIdentifier: channel.identifier,
  startTime: Date.now(), // Start timestamp — fetches messages before this time
  pageSize: 20,          // Number of messages per page (valid range: 1–100)
  isAscending: false,    // false: descending (newest first), true: ascending
});
const { code, data } = await query.loadNextPage();
if (code === 0) {
  console.log('Messages:', data);
} else {
  console.log('Failed to get messages. Code:', code);
}

Disconnect

warning

• Disconnecting prevents you from receiving messages, sending messages, fetching remote messages, and getting channel lists.
• After reconnecting, missed messages from the offline period are delivered. Missed messages are stored for 7 days by default.

TypeScript

import { NCEngine } from '@nexconn/chat';

await NCEngine.disconnect();
console.log('Disconnected');

Next steps

You have now completed the basic Chat SDK integration. See the other sections for detailed guidance on channels, messages, and related features.