Send your first message

This guide walks you through the minimum steps to integrate the Chat SDK into an iOS app: install the SDK, initialize it, connect a user, and send a message.

Requirements

• Xcode 14.0 or later
• iOS 13.0 or later
• CocoaPods 1.10.0 or later (if using CocoaPods)
• Swift 5.0 or later (if using Swift Package Manager)

Before you start

1. Register a developer account on the Nexconn Console. Registration automatically creates an app in the development environment.
2. On the Key Management page, copy the App Key for the development environment.

tip

Each app has separate App Keys for development and production. Data is isolated between the two environments. Switch to the production App Key before releasing your app.

Step 1: Install the SDK

CocoaPods

Add the following to your Podfile:

ruby

pod 'NexconnChat/Chat', '~> x.y.z'

Then run:

shell

pod install

Open the generated .xcworkspace file in Xcode.

Swift Package Manager

1. In Xcode, go to File > Add Package Dependency.

2. Enter the SDK repository URL:

   https://github.com/NexconnAI-Dev/nexconn-chat-sdk-ios

3. Select a version rule, check NexconnChatSDK, and click Add Package.

Step 2: Initialize the SDK

Import the SDK and call NCEngine.initialize(_:) once in application:didFinishLaunchingWithOptions:, before using any other SDK features.

Swift

swift

import NexconnChatSDK

let params = InitParams(appKey: "Your_AppKey")
NCEngine.initialize(params)

Objective-C

Objective C

#import <NexconnChatSDK/NexconnChatSDK.h>

// Basic initialization
NCInitParams *params = [[NCInitParams alloc] initWithAppKey:@"Your_AppKey"];
[NCEngine initializeWithParams:params];

If your app connects to a specific data center, set the area code:

Swift

swift

let params = InitParams(appKey: "Your_AppKey")
params.areaCode = .sg
NCEngine.initialize(params)

Objective-C

Objective C

NCInitParams *params = [[NCInitParams alloc] initWithAppKey:@"Your_AppKey"];
params.areaCode = NCAreaCodeSg; // Singapore data center
[NCEngine initializeWithParams:params];

info

Find your App Key and data center region in the Nexconn Console under Service Management.

For all initialization options, see Initialize the SDK.

Step 3: Get an access token

An access token is a per-user authentication credential. Your app server must request it from the Nexconn Server API and pass it to the client.

For quick testing, use the API Debugger in the console to call the Register User endpoint and get a token for a test user.

warning

Never call the Server API to obtain tokens directly from client code. This requires embedding your App Secret in the app, which exposes it to decompilation. Always fetch tokens through your own app server.

Step 4: Connect to the server

Register a connection status handler before connecting, then call NCEngine.connect(params:databaseOpenedHandler:completionHandler:) with the user's access token.

Swift

swift

import NexconnChatSDK

final class MyConnectionHandler: NSObject, ConnectionStatusHandler {
  func onConnectionStatusChanged(_ status: ConnectionStatus) {
    print("Connection status: \(status.rawValue)")
  }
}

let connectionHandler = MyConnectionHandler()
NCEngine.addConnectionStatusHandler(identifier: "MyApp", handler: connectionHandler)

let connectParams = ConnectParams(token: "user-access-token")
NCEngine.connect(
  params: connectParams,
  databaseOpenedHandler: { isRecreated, error in
    guard error == nil else { return }
    // Local database is ready — safe to show main UI
    if isRecreated {
      // Local data was cleared
    }
  },
  completionHandler: { userId, error in
    if error == nil {
      // Connection successful
    } else if error?.errorCode == 15 {
      // Token expired — fetch a new one from your server and reconnect
    }
  }
)

Objective-C

Objective C

// 1. Register a connection status handler
[NCEngine addConnectionStatusHandlerWithIdentifier:@"MyApp" handler:self];

// 2. Connect
NCConnectParams *connectParams = [[NCConnectParams alloc] initWithToken:@"user-access-token"];
[NCEngine connectWithParams:connectParams
     databaseOpenedHandler:^(BOOL isRecreated, NCError * _Nullable error) {
         // Local database is ready — safe to show main UI
         // isRecreated == YES means local data was cleared
     }
      completionHandler:^(NSString *userId, NCError *error) {
         if (error == nil) {
             // Connection successful
         } else if (error.errorCode == 15) {
             // Token expired — fetch a new one from your server and reconnect
         }
     }];

The SDK has a built-in reconnection mechanism. Call connect only once per app lifecycle. For details and error codes, see Connect to the server.

Step 5: Send a message

Send a text message to another user:

Swift

swift

guard let channel = DirectChannel(channelId: "recipient-user-id") else {
  return
}

let textContent = TextMessage(text: "Hello!")
let params = SendMessageParams(content: textContent)

channel.sendMessage(
  params: params,
  attachedHandler: { message in
    // Saved to local database — update UI here
  },
  completionHandler: { message, error in
    if let error {
      print("Send failed: \(error.localizedDescription)")
    } else {
      print("Sent successfully, messageId: \(message?.messageId ?? "")")
    }
  }
)

Objective-C

Objective C

// 1. Create a direct channel to the recipient
NCDirectChannel *channel = [[NCDirectChannel alloc] initWithChannelId:@"recipient-user-id"];

// 2. Build message content and send parameters
NCTextMessage *textContent = [[NCTextMessage alloc] initWithText:@"Hello!"];
NCSendMessageParams *params = [[NCSendMessageParams alloc] initWithContent:textContent];

// 3. Send
[channel sendMessageWithParams:params
              attachedHandler:^(NCMessage *message) {
    // Saved to local database — update UI here
} completionHandler:^(NCMessage *message, NCError *error) {
    if (error == nil) {
        NSLog(@"Sent successfully, messageId: %@", message.messageId);
    } else {
        NSLog(@"Send failed: %@", error.localizedDescription);
    }
}];

What's next

Topic	Description
Import the SDK	All installation methods in detail
Initialize the SDK	Area codes and advanced configuration options
Connect to the server	Connection error codes and usage patterns
Monitor connection status	Handle network changes in your UI
Send messages	Images, files, voice, and more