Data Channel

Ordered/reliable semantics, topic reuse, size limits, messaging and the boundary with IM.

Version v1.1.0 · Updated 2026-10-26 · revision 1

A data channel is "reliable messaging over the RTC connection": a good fit for whiteboard deltas, courseware commands, cursor positions and simple signalling; it is not suitable for chat bubbles, offline messages or message history — that is IM's job (this project does not provide IM; see the integration boundary in the RTC provider interface definition).

What each platform can do (decide before you choose)#

Data channels are bound to the lifetime of the channel connection: when the connection drops the channel is gone, and nothing is resent.

Web usage (signatures from the public interface definition)#

import AgoraRTC from '@nimeet/rtc-web';

const client = AgoraRTC.createClient({ mode: 'rtc' });

// 1) Create and publish a data channel: the publish overload accepts IDataChannelConfig
const dataChannel = await client.publish({ ordered: true });   // ILocalDataChannel

// 2) Send: a binary payload (Uint8Array), not an arbitrary JS object
await dataChannel.send(new Uint8Array([1, 2, 3]));

// 3) Receive: remote channels are delivered through stream-message
client.on('stream-message', (uid, payload) => {
  console.log('from', uid, payload.byteLength);
});

// 4) Remember to unpublish when you are done
await client.unpublish(dataChannel);

Key points:

• publish(config) returns an ILocalDataChannel, and unpublish(dataChannel) takes it back;
• Payloads are binary: encode and decode JSON yourself with TextEncoder/TextDecoder;
• Channel parameters (ordered, maximum retransmissions) live in IDataChannelConfig and can be read back after publishing through dataChannel.getConfig() (IDataChannel exposes read-only properties such as id, maxRetransmits and metadata).

Encoding convention (used consistently in our team)#

const encoder = new TextEncoder();
const decoder = new TextDecoder();

function sendJson(channel, value) {
  return channel.send(encoder.encode(JSON.stringify(value)));
}

client.on('stream-message', (uid, payload) => {
  const message = JSON.parse(decoder.decode(payload));
  // { t: 'cursor', x, y } / { t: 'whiteboard.op', op }
});

Adding a t (type) field for multiplexing makes compatibility handling and instrumentation easier than opening several channels.

Size and rate#

Native platforms#

On native platforms the equivalent surface is the sendStreamMessage(streamId, data, length) / createDataStream(config) pair (check the API reference for each platform to see whether a method exists), with the same semantics as the web: create the stream first, then send messages, and dispatch incoming messages by streamId in the callback.

Common issues#