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:

JSON

The following are the properties of a typing event:

PropertyDescriptionType
typeThe type of the event.String
currentlyTypingA set of all users currently typing.Set
changeThe 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:

JavaScript

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 a typing.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 clientIds for all users that are currently typing in the room:

Select...