Typing indicators
Typing indicators enable you to display which users are currently writing a message in a room. This feature can be used to display a message such as Sandi is typing..., or when a certain threshold is reached you could instead display Multiple people are typing... or 12 people are typing.... Typing events are emitted whenever a user starts or stops typing.
Subscribe to typing events
Subscribe to typing events by registering a listener. Typing events can be emitted when a user starts typing, and when they stop typing. Use the typing.subscribe()
method in a room to receive these updates:
Typing event structure
The following is the structure of a typing event:
The following are the properties of a typing event:
Property | Description | Type |
---|---|---|
type | The type of the event. | String |
currentlyTyping | A set of all users currently typing. | Set |
change | The single change that resulted in the event. | Object |
type : The type of change that occurred. | String | |
clientId : The clientId of the user that triggered the change. | String |
You can use the size of the currentlyTyping
set to decide whether to display individual user names, or that multiple people are typing in your user interface.
Unsubscribe from typing events
Use the unsubscribe()
function returned in the subscribe()
response to remove a typing listener:
Use the typing.unsubscribeAll()
method to remove all typing listeners in a room:
Set typing status
Use the typing.keystroke()
method to emit a typing event with type
set to typing.started
.
Use the stop()
method to emit a typing event with isTyping
set to false
.
Typing Event Frequency
The Typing feature includes a configurable timer that controls how often typing events are sent to the server. This timer is reset each time a new typing event is sent, it works as follows:
- On the first call to
keystroke()
, the timer is set and an event is sent to the server. - Subsequent calls before the timer expires result in a no-op.
- After the timer expires, a new typing event is sent and the timer is reset.
- If
stop()
is called, the timer is reset and atyping.stopped
event is sent to the server.
You can configure the length of this timer using the heartbeatThrottleMs
parameter in RoomOptions
(default: 10,000ms).
It is recommended that you call keystroke()
with every keypress, and the SDK will handle when and if to send a typing indicator to the server.
Emulating User Behavior
You can emulate user behavior (e.g., in chatbots) by setting a timeout to call keystroke()
at intervals equal to the heartbeatThrottleMs
plus a small delay, e.g. 200ms. This will ensure the typing indicator remains active.
Grace Period for Typing Events
For the recipient of typing events:
- The typing indicator remains active for the duration defined by the
heartbeatThrottleMs
parameter, plus a predefined 2000ms grace period. - Receiving a new typing event before the grace period ends will reset the timeout.
- If the grace period ends without receiving a new typing event, the SDK will emit a
typing.stopped
event for that client to any subscribed listeners.
For example: With the heartbeatThrottleMs
set to 10,000ms, the typing indicator remains active for 12,000ms. If no new typing event is received within this time, the SDK will emit a typing.stopped
event.
Adjusting the Event Frequency
You can adjust the heartbeatThrottleMs
parameter to balance responsiveness and resource costs:
- Increase responsiveness: Lower the value → More typing events are sent to the server → Higher cost as more messages are sent.
- Save resource costs: Raise the value → Fewer typing events are sent to the server → Lower responsiveness, but less cost as fewer messages are sent overall.
This balance allows you to optimize cost and responsiveness based on your applications needs.
Retrieve a list of users that are currently typing
Use the typing.get()
method to retrieve a set of clientId
s for all users that are currently typing in the room: