package ozulip

  1. Overview
  2. Docs

Module Ozulip.EventsSource

The Events module provides an interface to Zulip's real-time events API.

This module provides both high-level and low-level interfaces to the real-time events API.

High-Level Interface

Sourcemodule Message : sig ... end

The Message module represents the content of "message" events returned by Zulip's real-time events API.

Sourceval interact : ?switch:Lwt_switch.t -> ?trusted_ids:int list -> ?trusted_emails:string list -> ?privmsg:bool -> ?mention:bool -> Ozulip__.Config.config -> (string -> string option Lwt.t) -> unit Lwt.t

Interact with other users.

This is a utility function meant for bot authors.

interact config f will call the function f on each command received (see commands for details), and replies (see Message.reply) with the result of the call to f, if any.

Interactions are parallelized internally, so that a long-running interaction will not block the processing of other commands.

Sourceval commands : ?switch:Lwt_switch.t -> ?trusted_ids:int list -> ?trusted_emails:string list -> Ozulip__.Config.config -> Message.t Lwt_stream.t

Returns a stream of the commands sent to the user.

This is an utility function meant for bot authors.

A command is a message:

  • That was not sent by the current user,
  • That has not been read yet,
  • That either was sent in a one-on-one private conversation, or starts by a mention of the current user (must be a regular mention, not a wildcard).

If either trusted_ids or trusted_emails are provided, this function discards messages that are not trusted (as determined by Message.is_trusted). Otherwise, all messages are kept.

Sourceval messages : ?switch:Lwt_switch.t -> Ozulip__.Config.config -> Message.t Lwt_stream.t

Returns a stream of the message events.

This stream contains all the messages returned by Zulip, and includes unread messages, and messages sent by the current user.

Bot authors may find commands or interact more useful.

Low-Level Interface

Sourcetype event = ..

Events returned by the real-time events API.

This is an extensible type to allow supporting additional event types in the future without breaking backwards compatibility.

Sourcetype event +=
  1. | Message of Message.t
    (*

    A message that was sent to the user.

    *)
  2. | Heartbeat
    (*

    Heartbeat events sent by Zulip to keep the connection alive.

    These should only be relevant to users of the low-level events interface. High-level interfaces such as stream automatically deals with heartbeat events for you.

    *)
Sourcetype event_type = [
  1. | `Message
]

The event types that can be filtered in calls to register.

Sourcetype queue_id = private string

A queue identifier is really just a string, but we wrap it in a private type for clarity.

Sourcetype events_queue = {
  1. queue_id : queue_id;
  2. last_event_id : int;
  3. zulip_feature_level : int;
  4. event_queue_longpoll_timeout_seconds : int;
}

Event queue configuration.

This is the type returned by the "register" endpoint.

Sourceval register : ?apply_markdown:bool -> ?client_gravatar:bool -> ?include_subscribers:bool -> ?slim_presence:bool -> ?event_types:[< event_type as 'a ] list -> ?all_public_streams:bool -> ?fetch_event_types:'a list -> ?narrow:(string * string) list -> Ozulip__.Config.config -> (events_queue, int * string option) Lwt_result.t

Low-level wrapper around the "register" endpoint.

See the Zulip documentation for more details.

Sourceval events : ?last_event_id:int -> ?blocking:bool -> queue_id:queue_id -> Ozulip__.Config.config -> ((int * event) list, int * string option) Lwt_result.t

Low-level wrapper around the "events" endpoint.

See the Zulip documentation for more details.

Sourceval deregister : queue_id:string -> Ozulip__.Config.config -> (unit, int * string option) Lwt_result.t

Low-level wrapper around the "deregister" endpoint.

See the Zulip documentation for more details.

Sourceval stream : ?switch:Lwt_switch.t -> ?event_types:event_type list -> Ozulip__.Config.config -> event Lwt_stream.t

Returns a stream of events sent by the Zulip API.

This is a wrapper around the low-level register and events function that takes care of dealing with reconnections, queue management, and heartbeats automatically (in particular, the returned stream will never contain a Heartbeat event).

Most of the time, you want to use messages or commands instead.