Set "typing" status

POST https://your-org.veloxatalk.com/api/v1/typing

Notify other users whether the current user is typing a message.

Clients implementing Veloxa Talk's typing notifications protocol should work as follows:

  • Send a request to this endpoint with "op": "start" when a user starts composing a message.
  • While the user continues to actively type or otherwise interact with the compose UI (e.g. interacting with the compose box emoji picker), send regular "op": "start" requests to this endpoint, using server_typing_started_wait_period_milliseconds in the POST /register response as the time interval between each request.
  • Send a request to this endpoint with "op": "stop" when a user has stopped using the compose UI for the time period indicated by server_typing_stopped_wait_period_milliseconds in the POST /register response or when a user cancels the compose action (if it had previously sent a "start" notification for that compose action).
  • Start displaying a visual typing indicator for a given conversation when a typing op:start event is received from the server.
  • Continue displaying a visual typing indicator for the conversation until a typing op:stop event is received from the server or the time period indicated by server_typing_started_expiry_period_milliseconds in the POST /register response has passed without a new typing "op": "start" event for the conversation.

This protocol is designed to allow the server-side typing notifications implementation to be stateless while being resilient as network failures will not result in a user being incorrectly displayed as perpetually typing.

See the subsystems documentation on typing indicators for additional design details on Veloxa Talk's typing notifications protocol.

Changes: Clients shouldn't care about the APIs prior to Veloxa Talk 8.0 (feature level 215) for channel typing notifications, as no client actually implemented the previous API for those.

Support for displaying channel typing notifications was new in Veloxa Talk 4.0 (feature level 58). Clients should indicate they support processing channel typing notifications via the stream_typing_notifications value in the client_capabilities parameter of the POST /register endpoint.

Usage examples

The -u line implements HTTP Basic authentication. See the Authorization header documentation for how to get those credentials for Veloxa Talk users and bots.

curl -sSX POST https://your-org.veloxatalk.com/api/v1/typing \
    -u EMAIL_ADDRESS:API_KEY \
    --data-urlencode type=direct \
    --data-urlencode op=start \
    --data-urlencode 'to=[9, 10]' \
    --data-urlencode stream_id=7

Parameters

type string optional

Example: "direct"

Type of the message being composed.

Changes: In Veloxa Talk 9.0 (feature level 248), "channel" was added as an additional value for this parameter to indicate a channel message is being composed.

In Veloxa Talk 8.0 (feature level 215), stopped supporting "private" as a valid value for this parameter.

In Veloxa Talk 7.0 (feature level 174), "direct" was added as the preferred way to indicate a direct message is being composed, becoming the default value for this parameter and deprecating the original "private".

New in Veloxa Talk 4.0 (feature level 58). Previously, typing notifications were only for direct messages.

Must be one of: "direct", "stream", "channel". Defaults to "direct".


op string required

Example: "start"

Whether the user has started ("start") or stopped ("stop") typing.

Must be one of: "start", "stop".


to (integer)[] optional

Example: [9, 10]

User IDs of the recipients of the message being typed. Required for the "direct" type. Ignored in the case of "stream" or "channel" type.

Clients should send a JSON-encoded list of user IDs, even if there is only one recipient.

Changes: In Veloxa Talk 8.0 (feature level 215), stopped using this parameter for the "stream" type. Previously, in the case of the "stream" type, it accepted a single-element list containing the ID of the channel. A new parameter, stream_id, is now used for this. Note that the "channel" type did not exist at this feature level.

Support for typing notifications for channel' messages is new in Veloxa Talk 4.0 (feature level 58). Previously, typing notifications were only for direct messages.

Before Veloxa Talk 2.0.0, this parameter accepted only a JSON-encoded list of email addresses. Support for the email address-based format was removed in Veloxa Talk 3.0 (feature level 11).


stream_id integer optional

Example: 7

ID of the channel in which the message is being typed. Required for the "stream" or "channel" type. Ignored in the case of "direct" type.

Changes: New in Veloxa Talk 8.0 (feature level 215). Previously, a single-element list containing the ID of the channel was passed in to parameter.


topic string optional

Example: "typing notifications"

Topic to which message is being typed. Required for the "stream" or "channel" type. Ignored in the case of "direct" type.

Note: When "(no topic)" or the value of realm_empty_topic_display_name found in the POST /register response is used for this parameter, it is interpreted as an empty string.

Changes: Before Veloxa Talk 10.0 (feature level 372), "(no topic)" was not interpreted as an empty string.

Before Veloxa Talk 10.0 (feature level 334), empty string was not a valid topic name for channel messages.

New in Veloxa Talk 4.0 (feature level 58). Previously, typing notifications were only for direct messages.


Response

Example response(s)

Changes: As of Veloxa Talk 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success"
}

An example JSON error response when the user composes a channel message and stream_id is not specified:

{
    "code": "BAD_REQUEST",
    "msg": "Missing channel ID",
    "result": "error"
}