Skip to content

Realtime ​

See Connecting to Realtime and Groups and Messages. Every method raises SkapiError.

connect_realtime ​

python
skapi.connect_realtime(callback) -> None

Opens the realtime connection and returns once it is open. callback(event) runs on a background thread for every event; see Events. Called again while connected, it only swaps the callback. The connection reopens on its own after a drop.

Errors ​

codemessage
INVALID_REQUESTCallback must be a function.
INVALID_REQUESTNo access. (not signed in)
INVALID_REQUESTWebSocket closed before it opened.

close_realtime ​

python
skapi.close_realtime() -> None

Closes the connection. The callback gets "close"; the group gets USER_DISCONNECTED and USER_LEFT. Does nothing when no connection is open.

join_realtime ​

python
skapi.join_realtime(group: str | None) -> dict

Joins a group, leaving the current one. None (or "") leaves the group. {"group": ...} is accepted too.

python
{"type": "success", "message": 'Joined realtime message group: "lobby".'}
{"type": "success", "message": "Left realtime message group."}

Errors ​

codemessage
INVALID_REQUESTNo realtime connection. Execute connect_realtime() before this method.
INVALID_PARAMETER"group" must be a string | None.

post_realtime ​

python
skapi.post_realtime(message, recipient: str, notification: dict | None = None) -> dict

Sends any JSON value to a user (recipient is a user ID) or to the group you joined (recipient is its name). Returns {"type": "success", "message": "Message sent."}.

notification: {"title": str, "body": str, "config"?: {"always": bool}}, a web push for recipients in a browser. See Notifications.

Errors ​

codemessage
INVALID_REQUESTNo realtime connection. Execute connect_realtime() before this method.
INVALID_REQUESTNo recipient.
INVALID_REQUESTUser has not joined to the recipient group. Run join_realtime("<group>")
INVALID_REQUESTRealtime connection is not open. Try reconnecting with connect_realtime(). (the connection is down)
INVALID_PARAMETERMessage is <n> bytes; a realtime message can be at most 32768 bytes including its headers.
INVALID_PARAMETER"notification" should be an object with "title" and "body". / Key "title" is required. / "title" should be type: <string>. / "config.always" should be type: <boolean>.
INVALID_PARAMETERNotification size exceeds 3kb.

get_realtime_groups ​

python
skapi.get_realtime_groups(params: dict | None = None, fetch_options: dict | None = None) -> dict

Groups that have members now: {"list": [{"group", "number_of_users"}], ...}. Left out, params lists every group.

key
searchFor"group" (default) or "number_of_users"
valuea str for "group", a number for "number_of_users"
condition">", ">=", "=", "<", "<=", "!=" (or gt, gte, eq, lt, lte, ne)
rangean upper bound of the same type as value; replaces condition

fetch_options: see Paging.

Errors ​

codemessage
INVALID_PARAMETER"<value>" is invalid in "searchFor". allowed types or values are: "group", "number_of_users".
INVALID_PARAMETER"<value>" is invalid in "condition". allowed types or values are: ...
INVALID_PARAMETER"value" must be a number. / "value" must be a string. / "range" must be a number. / "range" must be a string.

get_realtime_users ​

python
skapi.get_realtime_users(params: dict | None = None, fetch_options: dict | None = None) -> dict

Connections in a group: {"list": [{"user_id", "cid"}], ...}.

key
groupthe group; left out, the one you joined
user_idonly this user's connections

Errors ​

codemessage
INVALID_PARAMETERNo group has been joined. Otherwise "group" is required.
INVALID_PARAMETER"<value>" is invalid in "group". allowed type or value is: Type<string>.
INVALID_PARAMETERUser ID is empty. / User ID is invalid. (in user_id)

skapi-py 2.4.0