Send a message

This guide covers how to send messages using the Chat SDK.

The client SDK limits message sending to a maximum of 5 messages per second.

Prerequisites

1. Initialize the SDK — Complete the SDK initialization and configure basic parameters (App Key, etc.). See the Initialization guide.
2. Connect to the server — Ensure the client has connected successfully using a valid access token. See Connect.
3. Create a message — Build the appropriate message object (text, image, voice, etc.) based on your needs. See Message types for constructor details.

Send a standard message

Create a channel instance and call channel.sendMessage() with a SendMessageParams object.

Method

Dart

Future<int> sendMessage(SendMessageParams params, {SendMessageCallback? callback})

Parameters

Parameter	Type	Description
params	SendMessageParams	Contains the messageParams describing the message content, optional pushConfig, and optional directedUserIds.
callback	SendMessageCallback?	Send event callback with onMessageSaved and onMessageSent.

Code example

Dart

final channel = DirectChannel('<target-user-id>');
await channel.sendMessage(
  SendMessageParams(
    messageParams: TextMessageParams(
      text: 'Hello!',
    ),
  ),
  callback: SendMessageCallback(
    onMessageSaved: (message) {
      // Message saved to local database
    },
    onMessageSent: (code, message) {
      if (code == null) {
        print('Message sent successfully');
      }
    },
  ),
);

Send a media message

Call channel.sendMediaMessage() with a SendMediaMessageParams object containing the appropriate MessageParams subclass (e.g., ImageMessageParams, VoiceMessageParams, FileMessageParams).

Method

Dart

Future<int> sendMediaMessage(SendMediaMessageParams params, {SendMediaMessageHandler? handler})

Code example

Dart

final channel = DirectChannel('<target-user-id>');
await channel.sendMediaMessage(
  SendMediaMessageParams(
    messageParams: ImageMessageParams(
      path: '<local-image-path>',
    ),
  ),
  handler: SendMediaMessageHandler(
    onMediaMessageSaved: (message) {
      // Media message saved locally
    },
    onMediaMessageSending: (message, progress) {
      print('Upload progress: $progress%');
    },
    onMediaMessageSent: (code, message) {
      if (code == null) {
        print('Media message sent successfully');
      }
    },
    onSendingMediaMessageCanceled: (message) {
      print('Media message upload canceled');
    },
  ),
);

Handle send failures

For locally stored message types, if onMessageSaved fires, the message has been saved to the local database. If a saved message fails to send (no onMessageSent fires), display the failed message temporarily and cache the instance from onMessageSaved. Retry by calling sendMessage with the same instance — creating a new message results in duplicates.

Forward and broadcast messages

Forward: The Chat SDK does not provide a forwarding API. To forward a message, send a new message with the same content.

Broadcast: Broadcasting sends a message to multiple target IDs. Two approaches:

• Loop through target IDs and call the send API for each. The client SDK limits sending to 5 messages per second.
• Use the Server API on your app server. The Send Direct Message API supports sending to multiple users in a single call.