Send a custom signal

Custom signals deliver lightweight business coordination payloads—such as raising hands, requesting layout changes, or syncing transient presentation state—to participants in an active call room. Custom signaling is not a chat messaging API and does not replace RTC media data channels.

Parameters

Code example

final signal = jsonEncode({
  'version': 1,
  'eventID': eventID,
  'type': 'hand-raised',
  'userID': currentUserID,
  'sentAt': DateTime.now().millisecondsSinceEpoch,
});

await OpenIM.iMManager.signalingManager.signalingSendCustomSignal(
  roomID: roomID,
  customInfo: signal,
);

Return value

A successful Future indicates that the server accepted the signaling payload for dispatch. It does not guarantee that other participants have processed it. Custom signaling is designed for lightweight, ephemeral in-call coordination; do not use it to transfer large files or persist long-term state.

Receive custom signals

Receive custom signals through the onReceiveCustomSignal callback on OnSignalingListener:

void handleCustomSignal(CustomSignaling info) {
  final signalRoomID = info.roomID;
  final customInfo = info.customInfo;
  if (signalRoomID != activeRoomID || customInfo == null) return;

  final signal = parseAndValidateCallSignal(customInfo);
  if (hasAppliedSignal(signalRoomID!, signal.eventID)) return;
  applyCallSignal(signal);
}

Future<void> registerCustomSignalListener() {
  return OpenIM.iMManager.signalingManager.setSignalingListener(
    OnSignalingListener(onReceiveCustomSignal: handleCustomSignal),
  );
}

Include a protocol version and an idempotency key (eventID) within the custom business payload. Deduplicate actions using roomID:eventID to prevent duplicate processing or out-of-order execution from corrupting UI state. Because the SDK does not provide an unregister method, stop dispatching events to old state stores when logging out or switching accounts, and overwrite the listener with a fresh instance upon the next login. For general call event handling, see Handle call events.