Send a custom signal

Use signalingSendCustomSignal() to send lightweight business negotiation data to a specified call room, such as a raised-hand action, a layout-change hint, or application state synchronization. It is not a chat-message API and does not replace the media engine's data channel.

Send a signal

customInfo is a string. To send structured data, define a stable format and serialize it as JSON.

const signal = {
  version: 1,
  eventID: crypto.randomUUID(),
  type: 'hand-raised',
  userID: currentUserID,
  sentAt: Date.now(),
};

await openimsdk.signalingSendCustomSignal({
  roomID,
  customInfo: JSON.stringify(signal),
});

Promise completion means that OpenIMServer accepted the custom signal for sending; it does not mean other participants have processed it. Keep custom signals compact and include a protocol version and unique event ID so old and new clients can interoperate and ignore duplicate events. Do not place large files, chat history, long-term state, or sensitive credentials in customInfo.

Receive a signal

Listen for custom room signaling through SdkEvent.OnReceiveCustomSignal. The event's data contains roomID and the customInfo string. Validate the room and your application protocol before updating the interface.

import { SdkEvent } from '@openim/wasm-client-sdk';

function handleCustomSignal({ data }) {
  try {
    const signal = parseAndValidateCallSignal(data.customInfo);
    if (data.roomID !== activeRoomID) return;
    if (hasAppliedSignal(data.roomID, signal.eventID)) return;
    applyCallSignal(signal);
  } catch (error) {
    console.warn('Unable to parse the custom call signal', { error });
  }
}

openimsdk.on(SdkEvent.OnReceiveCustomSignal, handleCustomSignal);

function removeCustomSignalListener() {
  openimsdk.off(SdkEvent.OnReceiveCustomSignal, handleCustomSignal);
}

parseAndValidateCallSignal() should validate the JSON structure, protocol version, eventID, type, and business fields before returning an application object. This page provides the complete listener example for the event. Use roomID:eventID to identify and ignore duplicate signals, and combine it with the protocol's user ID when updating participant state. Do not depend on event order. Call removeCustomSignalListener() when leaving the call view, logging out, or changing accounts.

Do not trust client-provided custom signals to grant host, paid-feature, or privacy permissions. State requiring authoritative validation must be stored and evaluated by a trusted backend. After reconnecting, query the room or business backend again and use the returned result; custom signals are not a replayable authoritative record.