Events
Subscribe to real-time events to build reactive UIs and handle PTT communication.
Subscribing to Events
// Subscribe to an event
const handler = (event) => {
console.log('Event received:', event);
};
client.on('broadcast_start', handler);
// Unsubscribe when done
client.off('broadcast_start', handler);
Connection Events
connection_change
Fired when the connection status changes.
client.on('connection_change', (event: ConnectionChangeEvent) => {
console.log('Connected:', event.connected);
console.log('Status:', event.status);
});
// ConnectionChangeEvent:
// {
// connected: boolean, // true if fully connected
// status: 'connected' | 'connecting' | 'disconnected'
// }
| Property | Type | Description |
|---|---|---|
connected |
boolean |
True when both Socket and WebRTC are connected |
status |
ConnectionStatus |
Current connection state |
Broadcast Events
broadcast_start
Fired when someone starts speaking.
client.on('broadcast_start', (event: BroadcastStartEvent) => {
console.log(`${event.senderName} started speaking in ${event.channelId}`);
});
// BroadcastStartEvent:
// {
// channelId: string,
// senderId: string,
// senderName: string,
// messageId?: string,
// timestamp: number
// }
instant_broadcast_start
Fired immediately when a broadcast is received, before it enters the playback queue. Use this for instant UI updates (e.g., showing a "speaking" indicator) while the queued broadcast_start handles actual playback.
client.on('instant_broadcast_start', (event: BroadcastStartEvent) => {
// Same payload as broadcast_start, fired immediately (before queue)
showSpeakingIndicator(event.senderName, event.channelId);
});
broadcast_end
Fired when someone stops speaking.
client.on('broadcast_end', (event: BroadcastEndEvent) => {
console.log(`User ${event.senderId} stopped speaking`);
});
// BroadcastEndEvent:
// {
// channelId: string,
// senderId: string,
// timestamp: number
// }
playback_progress
Fired during audio playback with current progress.
client.on('playback_progress', (event: PlaybackProgressEvent) => {
console.log(`Playback duration: ${event.duration} seconds`);
});
// PlaybackProgressEvent:
// {
// duration: number // seconds elapsed
// }
audio_received
Fired when raw PCM audio data is received from an incoming broadcast. Use this for custom audio processing, visualization, or recording.
client.on('audio_received', (pcmData: ArrayBuffer) => {
// Raw PCM audio data (16-bit, 16kHz, mono)
const int16Array = new Int16Array(pcmData);
// Example: Calculate audio level for visualization
let sum = 0;
for (let i = 0; i < int16Array.length; i++) {
sum += Math.abs(int16Array[i]);
}
const avgLevel = sum / int16Array.length / 32768;
console.log('Audio level:', avgLevel);
});
// Audio format:
// - Format: PCM (raw samples)
// - Bit depth: 16-bit signed integer
// - Sample rate: 16000 Hz
// - Channels: 1 (mono)
The SDK automatically plays received audio through the speaker. The audio_received event provides access to the raw data for additional processing without affecting playback.
Channel Events
new_channel
Fired when a new channel is created.
client.on('new_channel', (event: NewChannelEvent) => {
console.log('New channel:', event.channel.channelName);
});
// NewChannelEvent:
// {
// channel: {
// channelId: string,
// channelName: string,
// channelType: 'group' | 'direct'
// },
// timestamp: number
// }
channel_name_update
Fired when a channel is renamed.
client.on('channel_name_update', (event: ChannelNameUpdateEvent) => {
console.log(`Channel ${event.channelId} renamed to ${event.newName}`);
});
// ChannelNameUpdateEvent:
// {
// channelId: string,
// newName: string,
// timestamp: number
// }
channel_participant_added
Fired when users are added to a channel.
client.on('channel_participant_added', (event: ParticipantAddedEvent) => {
event.participants.forEach((p) => {
console.log(`${p.name} joined channel ${event.channelId}`);
});
});
// ParticipantAddedEvent:
// {
// channelId: string,
// participants: AddedParticipant[],
// // { userId: string, name: string, admin: boolean }
// timestamp: number
// }
channel_participant_removed
Fired when a user is removed from a channel.
client.on('channel_participant_removed', (event: ParticipantRemovedEvent) => {
console.log(`User ${event.removedParticipant} left channel ${event.channelId}`);
});
// ParticipantRemovedEvent:
// {
// channelId: string,
// removedParticipant: string, // user ID / mobile_no
// timestamp: number
// }
channel_admin_added
Fired when a user is promoted to admin.
client.on('channel_admin_added', (event: AdminAddedEvent) => {
console.log(`User ${event.userId} is now admin of ${event.channelId}`);
});
// AdminAddedEvent:
// {
// channelId: string,
// userId: string,
// timestamp: number
// }
channel_admin_removed
Fired when admin privileges are removed from a user.
client.on('channel_admin_removed', (event: AdminRemovedEvent) => {
console.log(`User ${event.userId} is no longer admin of ${event.channelId}`);
});
// AdminRemovedEvent:
// {
// channelId: string,
// userId: string,
// timestamp: number
// }
User Events
new_sdk_user
Fired when a new user is created in the workspace.
client.on('new_sdk_user', (event: NewSdkUserEvent) => {
console.log(`New user: ${event.userName}`);
});
// NewSdkUserEvent:
// {
// userId: string,
// userName: string,
// timestamp: number
// }
Live Status Events
Live status indicates a user's availability for real-time audio. A channel is live when at least one participant is live.
channel_live_status
Fired when a channel's live status changes. A channel becomes live when the first participant goes live, and drops from live when the last participant drops.
client.on('channel_live_status', (event: ChannelLiveStatusEvent) => {
if (event.live) {
console.log(`Channel ${event.channelId} is now live!`);
} else {
console.log(`Channel ${event.channelId} is no longer live`);
}
});
// ChannelLiveStatusEvent:
// {
// channelId: string,
// live: boolean,
// timestamp: number
// }
channel_participant_live_status
Fired when a participant goes live or drops from live in a channel.
client.on('channel_participant_live_status', (event: ParticipantLiveStatusEvent) => {
if (event.live) {
console.log(`User ${event.participantMobileNo} is now live in ${event.channelId}`);
} else {
console.log(`User ${event.participantMobileNo} dropped from live in ${event.channelId}`);
}
});
// ParticipantLiveStatusEvent:
// {
// channelId: string,
// participantMobileNo: string,
// live: boolean,
// timestamp: number
// }
channel_participant_ptt_status
Fired when a participant changes their PTT mode setting.
client.on('channel_participant_ptt_status', (event: ParticipantPttStatusEvent) => {
console.log(`User ${event.participantMobileNo} PTT mode: ${event.pttMode}`);
});
// ParticipantPttStatusEvent:
// {
// channelId: string,
// participantMobileNo: string,
// pttMode: boolean,
// timestamp: number
// }
Message Events
message
Fired when a text or file message is received.
client.on('message', (event: MessageEvent) => {
const { message } = event;
if (message.attachments?.images) {
console.log(`${message.senderId} sent images:`, message.attachments.images);
}
if (message.description) {
console.log(`${message.senderId}: ${message.description}`);
}
});
// MessageEvent:
// {
// message: {
// messageId: string,
// channelId: string,
// senderId: string,
// description?: string, // Text content or caption
// attachments?: Record<string, string[]>, // e.g. { images: ['https://...'] }
// sentAt: string // ISO timestamp
// }
// }
Event Summary
| Event | Type | Description |
|---|---|---|
connection_change |
ConnectionChangeEvent |
Connection status changed |
broadcast_start |
BroadcastStartEvent |
Someone started speaking |
instant_broadcast_start |
BroadcastStartEvent |
Broadcast received immediately (before queue) |
broadcast_end |
BroadcastEndEvent |
Someone stopped speaking |
playback_progress |
PlaybackProgressEvent |
Audio playback progress |
audio_received |
ArrayBuffer |
Raw PCM audio data received |
new_channel |
NewChannelEvent |
New channel created |
channel_name_update |
ChannelNameUpdateEvent |
Channel renamed |
channel_participant_added |
ParticipantAddedEvent |
Users added to channel |
channel_participant_removed |
ParticipantRemovedEvent |
User removed from channel |
channel_admin_added |
AdminAddedEvent |
User promoted to admin |
channel_admin_removed |
AdminRemovedEvent |
Admin privileges removed |
new_sdk_user |
NewSdkUserEvent |
New user created |
channel_live_status |
ChannelLiveStatusEvent |
Channel live status changed |
channel_participant_live_status |
ParticipantLiveStatusEvent |
Participant joined/left live session |
channel_participant_ptt_status |
ParticipantPttStatusEvent |
Participant PTT mode changed |
message |
MessageEvent |
Message received |