Typing Notifications

Users may wish to be informed when another user is typing in a room. This can be achieved using typing notifications. These are ephemeral events scoped to a room_id. This means they do not form part of the Event Graph but still have a room_id key.

Events

`m.typing`

Informs the client of the list of users currently typing.

Event type:	Message event

Content

Name	Type	Description
`user_ids`	`[string]`	Required: The list of user IDs typing in this room, if any.

Examples

{
  "content": {
    "user_ids": [
      "@alice:matrix.org",
      "@bob:example.com"
    ]
  },
  "type": "m.typing"
}

Client behaviour

When a client receives an m.typing event, it MUST use the user ID list to REPLACE its knowledge of every user who is currently typing. The reason for this is that the server does not remember users who are not currently typing as that list gets big quickly. The client should mark as not typing any user ID who is not in that list.

It is recommended that clients store a boolean indicating whether the user is typing or not. Whilst this value is true a timer should fire periodically every N seconds to send a typing HTTP request. The value of N is recommended to be no more than 20-30 seconds. This request should be re-sent by the client to continue informing the server the user is still typing. As subsequent requests will replace older requests, a safety margin of 5 seconds before the expected timeout runs out is recommended. When the user stops typing, the state change of the boolean to false should trigger another HTTP request to inform the server that the user has stopped typing.

PUT /_matrix/client/v3/rooms/{roomId}/typing/{userId}

This tells the server that the user is typing for the next N milliseconds where N is the value specified in the timeout key. Alternatively, if typing is false, it tells the server that the user has stopped typing.

Rate-limited:	Yes
Requires authentication:	Yes

Request

Request parameters

path parameters
Name	Type	Description
`roomId`	`string`	Required: The room in which the user is typing.
`userId`	`string`	Required: The user who has started to type.

Request body

Name	Type	Description
`timeout`	`integer`	The length of time in milliseconds to mark this user as typing.
`typing`	`boolean`	Required: Whether the user is typing or not. If `false`, the `timeout` key can be omitted.

Request body example

{
  "timeout": 30000,
  "typing": true
}

Responses

Status	Description
`200`	The new typing state was set.
`429`	This request was rate-limited.

200 response

{}

429 response

RateLimitError
Name	Type	Description
`errcode`	`string`	Required: The M_LIMIT_EXCEEDED error code
`error`	`string`	A human-readable error message.
`retry_after_ms`	`integer`	The amount of time in milliseconds the client should wait before trying the request again.

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

Security considerations

Clients may not wish to inform everyone in a room that they are typing and instead only specific users in the room.