RPC Namespaces & Methods

channels

class chat.rpc.Channels(user, **kwargs)

Namespace for all channel (room, pm) relevant RPC methods

Provides all methods to retrieve and alter any data associated with a channel:

messages
channel members
presence

Mind that Channel is an abstract idea of any kind of “channel” within Grape. A channel could be a private message, a public or a private room.

Private messages usually have only 2 participants and do not implement channel-invitations.

Rooms can have 1 or more participants and have some additional attributes like a room title, description, etc.

See the namespaces Rooms and PM for a list of room or PM specific methods.

delete(ch_id, roomname)

Deletes a Channel irrevocably

This action can not be undone (history and channel information will be deleted entirely). Due to the “sensible” nature of this rpc call, a simple challenge/response mechanism is used to prevent unwanted deletions. See documentation on the roomname parameter.

The requesting user needs to be admin, organization-owner or the room-creator in order to delete a room.

Parameters
  • ch_id (int) – ID of the channel to be deleted

  • roomname (string) – The name of the channel to be deleted. This acts as a simple “verify your action” step. Whe deleting the user is asked to enter the unwanted room’s name to lower the chance of mistakenly delete the wrong room.

Raises
  • instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights

  • instant.rpc.ValidationError – if the provided roomname argument does not match the channels actual room name (case insensitive)

Events
delete_attachment(ch_id, msg_id, attachment_url, action=0)

Deletes a link attachment

Parameters
  • ch_id (int) – ID of the channel that contains the message to be deleted

  • msg_id (string) – ID of the message to be deleted

  • attachment_url (string) – the source_url of the link attachment that should be removed

  • action (int) –

    What should be done?

    • 0: just remove this link preview

    • 1: remove the link and blacklist the domain

    • 2: remove the link and block link previews for that link

Events
delete_message(ch_id, msg_id)

Deletes a message

Allows a user to delete a message or activity in a chat-history. Users may delete their own messages if the message edit timeout is not passed or, if the organization feature “channel admin is moderator” is activated, channel admins can delete any message from the channel. Activities can be deleted by the room admin, room creator and the organization admin.

Parameters
  • ch_id (int) – ID of the channel that contains the message to be deleted

  • msg_id (string) – ID of the message to be deleted

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights

Events
focus_message(ch_id, msg_id, before=5, after=5, strict=False)

Returns a range of messages surrounding a specific message

Returns a configurable number of messages before and after (chronologically) a given message ID.

Parameters
  • ch_id (int) – ID of the message’s channel

  • msg_id (string) – ID of the reference message

  • before (int, optional) – Number of messages to fetch before the reference message, including the message itself. Defaults to 5.

  • after (int, optional) – number of messages to fetch after the reference message, not including the message itself. Defaults to 5.

  • strict (bool, optional) – If set to True and the reference message is not in the result, it’ll raise an exception (MessageNotFound)

Returns

The Object’s format is identical to the one returned by chat.rpc.Channels.get_history().

Return type

Array[Object]

Raises

instant.rpc.UserExceptionMessageNotFound – If strict == True and msg_id was not found

get(channel_id)

Get the Channel (Room or PM) with the given channel_id.

Parameters

channel_id (int) –

Returns

A JSON object with the following fields:

  • unread (int) - number of messages in the channel the requesting user did not read yet

  • mentions (int) - number of unread messages containing a mention of the requesting since the last read message

  • group_mentions (int) - number of unread messages containing a mention of the whole room since the last read message

  • id (int) - the channels id

  • created (str) - ISO8601 formatted creation date of the channel

  • type (str) - the type of the channel, room or pm

  • last_message (object|None) - the last message from the channel or None if there is none yet. See chat.rpc.Rooms.get_overview()

  • icon (str) - in case of a room, its icon, otherwise the avatar of the partner

If type is room, the following attributes will be returned additionally:

  • name (str) - name of the room

  • creator (object) - See accounts.rpc.Users.get_user()

  • description (str) - room description

  • color (str) - hex color of the channel, starting with ‘#’

  • slug (str) - url slug of the channel

  • reference_url (str) - the room’s reference URL

  • abbr (str) - a safe to display representation of the room’s name

  • is_managed (bool) - whether the room is managed or not

  • is_public (bool) - whether the room is public or not

  • reference_label (str) - the room’s reference label

  • is_encrypted (bool) - Is this room End 2 End encrypted

  • permissions (object) - The permissions the logged in user has in this room

    • can_delete_channel (bool) - is the user allowed to delete this channel

    • can_edit_channel (bool) - Is the user allowed to edit this channel

    • can_invite_members (bool) - Is the user allowed invite members to this channel

    • can_leave_channel (bool) - Is the user allowed to leave this channel

    • can_post_messages (bool) - Is the user allowed post messages in this channel

    • can_see_members_list (bool) - Is the user allowed to see the members in this channel

    • can_remove_members (bool) - Is the user allowed to remove other members from this channel

If the type is pm, the following extra attribute is present:

Return type

Object

get_bulk_history(ch_ids, params=None)

Returns histories of multiple channels

A multi-channel version of get_history. Accepts only one params Object which will be considered when fetching each channel’s history. This is equivalent to calling get_history() for each channel id individually with the same params argument.

Parameters
Returns

Keys are the channel-ids and the respective values are the channel’s histories.

Return type

Object

get_history(ch_id, params=None)

Returns part of the history of a channel

Returns all messages of a channel that match criteria defined in the params argument.

Parameters
  • ch_id (int) – ID of the channel whose history to fetch

  • params (Object, optional) –

    Specifies query options when fetching the history:

    • time_from (string) - ISO8601 timestamp of lower bound for message time

    • time_to (string) - ISO8601 timestamp of upper bound for message time

    • limit (int) - maximum number of results to return (default: 50)

    • sort (string) - “asc” or “desc” (default: “desc”)

    All fields are optional and unlogical combinations (e.g. time_from > time_to) will result in an empty response.

Returns

An Array of message objects. Any message can either be a “real” message (i.e. posted by a user/bot) or an activity created by a service integration. Message and activity objects vary greatly in their set of provided properties. Messages contain the following fields:

  • id (string) - Message ID

  • prev_id (string|null) - Previous Message ID

  • text (string) - Rendered message text; may contain html

  • plain_text (string) - Plain text version of the message

  • time (string) - ISO8601 timestamp of post-time

  • organization (int) - Organization ID of the channel

  • channel (int) - Channel ID where the message was posted

  • mentions (Object)

    • user (Array[int]) - User-ids of all users mentioned in this message

    • group (Array[int]) - group-ids of all group mentions

  • clientside_id (string) - See chat.rpc.Channels.post()

  • author (Object)

    • type (string) - "user"

    • id (int) - User ID of the message author

    • username (string)

    • display_name (string)

    • avatar (string) - URL of the avatar

  • attachments (Array[Object]) - A list of attachment Objects which have the following fields:

    • url (string) - The attachments URL

    • id (string) - Attachment ID

    • name (string)

    • type (string) attachment type. obsolete, please use mime_type instead.

    • mime_type (string)

    • source (string) - if attachment was created through an external service, this indicates its source (e.g. giphy)

    • time (string)

    • thumbnail_url (string)

    • thumbnail_width (int)

    • thumbnail_height (int)

  • pinned (bool)

  • deleted (string, optional) - ISO8601 timestamp indicating when the message was deleted; only present in deleted messages

Activities may have service-specific properties added by the service integrations themselves. All activities should contain these properties:

  • author (Object)

    • type (string) - "service"

    • id (string) - the service integrations key

  • type (string) - The activities type. The value is Service integration specific (i.e. there might be 2 independent integrations which implement actions with the same type.

For any further activity properties, consult the integration’s documentation on its activities.

Return type

Array[Object]

get_message(channel_id, message_id)

Return the message with the given message_id

Parameters
  • channel_id (int) – ID of the message’s channel

  • message_id (int) – ID of the message

Returns

The Object’s format is identical to the one returned by chat.rpc.Channels.get_history().

Return type

Object

get_overview(organization_id, params=None)

Gives an overview over all rooms and pms a user is joined

Parameters
  • organization_id (int) – The organization id

  • params (Object) –

    Optional arguments for filtering and limiting

    • limit (int) - number of elements to return

    • exclude_pinned (bool) - Should pinned channels be excluded from the results.

Returns

An object with the following fields:

  • channels (Array[Object]) - objects containing channel and channelmember data.

    • id (string) - Room ID

    • pin (int) - sorting value of the room

    • last_message (Object) - The last Message Object

      • id (string) - Message ID

      • clientside_id (string) - See chat.rpc.Channels.post()

      • text (string) - Rendered message text; may contain html

      • plain_text (string) - Plain text version of the message

      • time (string) - ISO8601 timestamp of post-time

      • user_time (string) - ISO8601 timestamp of poster’s post-time

      • author (Object)

        • id (int) - User ID of the message-author

        • type (string) - "user"

        • username (string)

        • avatar- (string) - URL to the avatar image of the user

        • display_name- (string) - name according to the configuration

      • organization (int) - Organization ID of the channel

      • channel (int) - Channel ID where the message was posted (always the same as room ID)

      • mentions (Object)

        • user (Array[int]) - User-ids of all users mentioned in this message

        • group (Array[int]) - group-ids of all group mentions

      • link_attachments (Object)

        • TBD

      • cglinks (Array)

      • attachments (Array[Object]) - A list of attachment Objects which have the following fields:

        • url (string) - The attachments URL

        • id (string) - Attachment ID

        • name (string)

        • type (string) attachment type. obsolete, please use mime_type instead.

        • mime_type (string)

        • source (string) - if attachment was created through external service, this indicates its source (e.g. giphy)

        • time (string)

        • thumbnail_url (string)

        • thumbnail_width (int)

        • thumbnail_height (int)

      • pinned (bool) - is this a pinned message

      • edited (datetime)

    • unread (int) - number of unread messages

    • mentions (int) - number of mentions since the last read

    • group_mentions (int) - number of group mentions since the last read

    • created (int) - unix timestamp of creation-time

    • type (string) - ‘room’ | ‘pm’

    If the channel type is a room the following fields are available:

    • name (string) - Room name

    • description (string) - room description text

    • slug (string) - the slug of the room

    • abbr (string) - Two-Character abbreviated Name of the room

    • color (string) - hexadecimal color code - e.g. #BC7215

    • icon (string) - icon-slug for display in sidebar.

    • creator (int) - User ID of the room’s creator

    • is_public (bool)

    • is_managed (bool)

    • reference_url (string) - url managed rooms

    • reference_label (string) - label for urls in managed rooms

    • notify_room (bool)

    If the channel type is a pm the following fields are available:

    • partner (Object) - PM Channel User

      • avatar (string) - URL to the user’s avatar

      • display_name (string)

      • email (string)

      • firstName (string)

      • id (int) - user ID

      • status (int) - presence status within the organization:

        • 0 Offline

        • 4 Reachable

        • 16 Online

        • null if online status is turned off

      • username (string)

Return type

Object

get_pinned_messages(ch_id, options=None)

Get the latest 100 pinned messages in a given channel. :param ch_id: id of the channel the message is in. :type ch_id: integer

Returns

An object with the following fields:

  • total (int) - total number of results.

  • results (array[object]) - a list of message objects as described in get_history()

Return type

object

get_pinned_overview(organization_id, params=None)

Get sorted list of pinned channels serialized with unread, mentions and last_message

Parameters
  • organization_id (int) – The organization id

  • params (Object) –

    Optional arguments for filtering and limiting

    • limit (int) - number of elements to return

Returns

An object with the following fields:

  • channels (Array[Object]) - objects containing channel and channelmember data.

    • id (string) - Room ID

    • pin (int) - sorting value of the room

    • last_message (Object) - The last Message Object

      • id (string) - Message ID

      • clientside_id (string) - See chat.rpc.Channels.post()

      • text (string) - Rendered message text; may contain html

      • plain_text (string) - Plain text version of the message

      • time (string) - ISO8601 timestamp of post-time

      • user_time (string) - ISO8601 timestamp of poster’s post-time

      • author (Object)

        • id (int) - User ID of the message-author

        • type (string) - "user"

        • username (string)

        • avatar- (string) - URL to the avatar image of the user

        • display_name- (string) - name according to the configuration

      • organization (int) - Organization ID of the channel

      • channel (int) - Channel ID where the message was posted (always the same as room ID)

      • mentions (Object)

        • user (Array[int]) - User-ids of all users mentioned in this message

        • group (Array[int]) - group-ids of all group mentions

      • link_attachments (Object)

        • TBD

      • cglinks (Array)

      • attachments (Array[Object]) - A list of attachment Objects which have the following fields:

        • url (string) - The attachments URL

        • id (string) - Attachment ID

        • name (string)

        • type (string) attachment type. obsolete, please use mime_type instead.

        • mime_type (string)

        • source (string) - if attachment was created through external service, this indicates its source (e.g. giphy)

        • time (string)

        • thumbnail_url (string)

        • thumbnail_width (int)

        • thumbnail_height (int)

      • pinned (bool) - is this a pinned message

      • edited (datetime)

    • unread (int) - number of unread messages

    • mentions (int) - number of mentions since the last read

    • group_mentions (int) - number of group mentions since the last read

    • created (int) - unix timestamp of creation-time

    • type (string)- ‘room’ | ‘pm’

    If the channel type is a room the following fields are available:

    • name (string) - Room name

    • description (string) - room description text

    • slug (string) - the slug of the room

    • abbr (string) - Two-Character abbreviated Name of the room

    • color (string) - hexadecimal color code - e.g. #BC7215

    • icon (string) - icon-slug for display in sidebar.

    • creator (int) - User ID of the room’s creator

    • is_public (bool)

    • is_managed (bool)

    • reference_url (string) - url managed rooms

    • reference_label (string) - label for urls in managed rooms

    • notify_room (bool)

    If the channel type is a pm the following fields are available:

    • partner (Object) - PM Channel User

      • avatar (string) - URL to the user’s avatar

      • display_name (string)

      • email (string)

      • firstName (string)

      • id (int) - user ID

      • status (int) - presence status within the organization:

        • 0 Offline

        • 4 Reachable

        • 16 Online

        • null if online status is turned off

      • username (string)

Return type

Object

get_pins(organization_id)

Get the sorted list of channel_ids of all pinned channels of the given organization.

Parameters

organization_id (integer) – ID of the channels organization

Returns

Return type

Array

get_unread_channel_count(organization: Optional[int] = None) → List[dict]
invite(ch_id, users, invite_sso_user=False)

Invites one or more users to a channel by email or username

Tries to invite every email/username from users to a channel. If an email is provided and no user with such email exists in the organization, an organization-invite will be created.

Parameters
  • ch_id (int) – ID of the channel to which users shall be invited

  • users (Array[string|int]) – An array of invitee identifiers to be invited. Those can be mixed types and has following actions associated: email-addresses (str): invite users by email. if this user is part of the organization, he will be added. if not, he will be invited. user-ids (int): user ids to be added to the channel usernames (str): same as email but without invite action.

  • invite_sso_user (bool) – Should newly created users be setup in a way that they can login via SSO? This requires the organization associated with the Channel to have SSO configured properly. If SSO is not configured, a UserException will be raised.

Raises

instant.rpc.UserException – For any exceptions that should be presented to the user (e.g. invalid email or SSO not configured)

:raises **Events**:: - notifications.events.NewNotification sent to a user’s PubSub channel if a user is already part of the organization, and has notifications enabled.

join(ch_id)

Joins current user to a channel

Flags the current user as joined in the channel identified by ch_id. After a successful join, the current user will receive events about the channel through its PubSub subscription.

Parameters

ch_id (int) – ID of the channel to join

Raises

instant.rpc.UserExceptionChannelNotFound – If channel with ch_id wasn’t found

Events:
join_multiple(ch_ids)

Joins current user to a list of channels

Flags the current user as joined in the channel identified by ch_id. After a successful join, the current user will receive events about the channel through its PubSub subscription.

Parameters

ch_ids (list) – List of IDs to join

Returns

A JSON object with the following fields:

  • joined (list) - list of joined channels IDs

  • not_joined (list) - list of not joined channels IDs

Return type

Object

Raises

instant.rpc.Userpc.pyrException – if channel with ch_id wasn’t found

Events:
kick(ch_id, uid)

Kicks a user out of the room

Only admins, organization owners and the room creator may use this RPC to kick a user out of the room. Once a user has been kicked out of a private room, they cannot join back later, but would have to be re-invited.

Note

Room creators can never be kicked out of their rooms.

Parameters
  • ch_id (int) – ID of the channel

  • uid (int) – ID of the user to kick

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights or when trying to kick the room creator

Events
leave(ch_id)

Un-joins current user from a channel

Removes current user from the channels list of joined users. Current user will not received PubSub events for the channel.

When leaving a private room voluntarily (in contrast to being kicked out, c.f chat.rpc.Channels.kick()), the user is allowed to re- join and the left room will still show up in the user’s available channels.

Parameters

ch_id (int) – ID of the channel to leave

Raises

instant.rpc.UserExceptionChannelNotFound – If channel with ch_id wasn’t found

Events:
  • chat.rpc.Left on the room’s pubsub channel.

pin_message(channel_id, message_id, pin=True)

Pins a message. Every user can pin and unpin a message. Pins are always visible for everybody in the channel. they are not unique to a user. Pinned messages can be retrieved with get_pinned_messages.

Parameters
  • channel_id (integer) – id of the channel the message is in.

  • message_id (integer) – id of the message to be pinned

  • pin (boolean) – should the pin be set or removed?

post(ch_id, message, options=None)

Posts a new message in a channel

Parameters
  • ch_id (int) – ID of the channel to post in

  • message (string or object) – if it’s a string it’s considered the body of the message (as entered by user) if it’s an object, it must be formatted as specified in the Message API.

  • options (Object) –

    An Object with extra-data to be stored along with the message. Supported fields are:

    • clientside_id (string)

      A client-provisioned message-id used by the client for acknowledging posted messages. Once saved, the server will include the clientside_id in the response body (along with the server-provisioned, actual message id).

    • attachments (Array[Object], optional)

      An Array of attachments associated to this message. Entries of this list can be either of:

      • Uploaded attachment: These files have been uploaded via the chatgrape upload endpoint which returns an upload-id upon success. In order to post an uploaded attachment to a channel, the client includes its upload-id here.

      • External attachments: are hosted by a third party provider. As these files are not uploaded and thus have no upload id, the ``attachments`N` entry must be more verbose, here’s an example:

        { 'url': url to the attachment,
          'name': name of the attachment
          'source': "giphy"|? (found in content)
          'category': "image"|? (found in content)
          'thumbnail_url': url of a thumbnail image,
          'thumbnail_width': width of the thumbnail in px,
          'thumbnail_height': height of the thumbnail in px,
          'mime_type':  the attachment's mime-type,
          'type': the attachment's type (obsolete)
        }
        

      The only mandatory field is url, all others being optional. thumbnail_url defaults to the value of url if omitted. mime_type defaults to the value of type which defaults to "image" if omitted. If both fields are provided, the value of mime_type is used for both of them (and the value of type ignored!)

Returns

The message ID of the newly created message object

Return type

string

Raises

instant.rpc.UserExceptionChannelNotFound – If channel with ch_id wasn’t found

Events:
  • chat.events.NewMessage to every session which has read permissions to this channel and wants to receive its events.

read(ch_id, msg_id)

Marks a message read by the current user

Save msg_id as the last read message by the requesting user in for the channel with id ch_id. The timestamp encoded in msg_id must not be in the future or older than the last-saved ID’s timestamp. In that case the call to read would result in a no-op and no new last- read mark be saved.

Parameters
  • ch_id (int) – ID of the channel for which to set the last-read state

  • msg_id (string) – ID of the message which should be saved as being read by the requesting user.

Events:
remove_pin(channel_id)

Remove a pin from a channel. :param channel_id: Id of the channel to be unpinned :type channel_id: integer

Raises

instant.rpc.UserExceptionInvalidChannel – If there is no ChannelMember of the user and the channel

Events:
set_pin(channel_id, pin=None)

Mark a channel with a pin. A pin is a positive integer that is used for sorting.

Parameters
  • channel_id (integer) – ID of the channel to be pinned

  • pin (integer) –

    • a positive integer represents the sort index of the channel.

    • if omitted or None the channel will be pinned as last channel.

Returns

Return type

pin - final pin number after resorting the channels (usually the given pin)

Raises
  • instant.rpc.UserExceptionInvalidChannel – If there is no ChannelMember of the user and the channel

  • instant.rpc.UserExceptionInvalidPin – If the pin value is invalid

Events:
set_typing(ch_id, typing)

Notify channel-users that a user has started or stopped typing

When a user starts or stops typing, its client can call this rpc to notify other members of the channel of it.

Parameters
  • ch_id (int) – ID of the channel where the user is currently typing

  • typing (bool) – Indicates whether the typing has started (True) or stopped (False)

Raises

instant.rpc.ValidationError – if the parameter is not a boolean value

Events
update_message(ch_id, msg_id, text)

Changes a chat-message’s contents

Currently users can only edit their own messages. Admins and company owners have no special rights to edit messages of other users. The message-text is changed in place and no history of the message’s contents are being retained.

Parameters
  • ch_id (int) – ID of the channel that contains the message to be edited

  • msg_id (string) – ID of the message which contents should be changed

  • text (text) – The new content of the message

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights

Events

rooms

class chat.rpc.Rooms(user, **kwargs)
assert_permission(membership, group)

Verifies permissions according to the Namespace calling this method

Parameters
  • membership

  • group

create(params)

Creates a new public or private room

Parameters

params (Object) –

An Object with all relevant room-data:

  • name (string) - Name of the new Room. Must be unique per organization (case-insensitively), non-empty and max 50 characters long.

  • organization (int) - ID of the organization where to create the room

  • description (string, optional) - A short user-defined descriptional text.

  • is_public (bool, optional)

    If True, will create a public room that every member of the organization can see and join. Private rooms (created with is_public = False) can only be joined through invitation. Defaults to True

  • users (Array[string], optional)

    An Array of email addresses to be invited.

  • is_encrypted (bool) - Is this room End 2 End encrypted

Returns

An object with the following fields:

  • id (int)

  • type (string)

  • creator (int) - User ID of the room’s creator

  • created (int) - unix timestamp of creation-time

  • name (string) - Room name

  • slug (string) - generated URL-slug (derived from name)

  • description (string) - room description text

  • abbr (string) - 2 letter abbreviation of room name

  • color (string) - icon-color for display in sidebar. See set_color()

  • icon (string) - icon-slug for display in sidebar. See set_icon()

  • is_public (bool)

  • users (Array[int]) - An Array of user-ids of channel members

  • invites (Array[int]) - Array of user-ids of invited users

Return type

Object

Raises

instant.rpc.ValidationError – if any of the provided data is invalid (e.g. room-name does already exist)

Events
get(channel_id)

Get the room with the given channel_id

Parameters

channel_id (int) –

Returns

Return type

object: a serialized room

get_overview(org_id)

Gives a overview over all the rooms the user joined

Parameters

org_id (int) – The Organization ID

Returns

An Array of Room objects. Rooms contain the following fields:

  • abbr (string) - Two-Character abbreviated Name of the room

  • color (string) - hexadecimal color code - e.g. #BC7215

  • creator (int) - User ID of the room’s creator

  • created (int) - unix timestamp of creation-time

  • description (string) - room description text

  • group_mentions (int) - count of group mentions in the room

  • icon (string) - icon-slug for display in sidebar. See set_icon()

  • id (string) - Room ID

  • is_public (bool)

  • last_message (Object) - The last Message Object

    • attachments (Array[Object]) - A list of attachment Objects which have the following fields:

      • url (string) - The attachments URL

      • id (string) - Attachment ID

      • name (string)

      • type (string) attachment type. obsolete, please use mime_type instead.

      • mime_type (string)

      • source (string) - if attachment was created through external service, this indicates its source (e.g. giphy)

      • time (string)

      • thumbnail_url (string)

      • thumbnail_width (int)

      • thumbnail_height (int)

    • author (Object)

      • type (string) - "user"

      • id (int) - User ID of the message-author

      • displayName- (string)

      • firstName- (string)

      • lastName- (string)

      • avatar- (string) - URL to the avatar image of the user

    • channel (int) - Channel ID where the message was posted (always the same as room ID)

    • clientside_id (string) - See chat.rpc.Channels.post()

    • id (string) - Message ID

    • mentions (Object)

      • user (Array[int]) - User-ids of all users mentioned in this message

      • group (Array[int]) - group-ids of all group mentions

    • organization (int) - Organization ID of the channel

    • plain_text (string) - Plain text version of the message

    • text (string) - Rendered message text; may contain html

    • time (string) - ISO8601 timestamp of post-time

    • user_time (string) - ISO8601 timestamp of poster’s post-time

  • mentions (int) - count of mentions in the room

  • name (string) - Room name

  • type (string) - Room type (always ‘room’)

  • unread (int) - count of unread messages

  • pin (int) - sorting value of the room

  • slug (string) - the slug of the room

Return type

Array[Object]

get_rooms(org_id, params=None)

Get a paginated list of rooms available for the calling user

Parameters
  • org_id (int) – ID of the organization

  • params (Object, optional) –

    Specifies query options when fetching the rooms:

    • membership (boolean, optional) - filter for active memberships of the user:

      -True Return rooms where the requesting user has an active membership

      -False Return rooms where the requesting user does not have an active membership

      -None|missing Return all rooms the user is allowed to see.

    • page (int, optional) - Page number Default: 1

    • page_size (int, optional) - Page size Default: 25

    • query (string, optional) - Search term for rooms

Returns

  • result (list) A List of Rooms objects sorted by last sent message and name
    • color (string) e.g.: “#36BDBD”

    • icon (string) either icon name or image URL

    • id (string)

    • is_public (bool)

    • name (string)

    • slug (string)

    • description (string)

    • members_count (int) - room member count

    • is_managed (bool) - manged rooms cannot be edited with the normal Rooms API

    • membership (bool) - whether the requesting user is member of the room or not

    • is_encrypted (bool) - Is this room End 2 End encrypted

Return type

Object

invite_guests(room_id, emails, expires_at)

invite guests to a Room. If the user does not exist yet it will be created. If a user with this email address already exists, they will be added to the room with the set expiration date

Parameters
  • room_id (int) – room-ID to invite guests to

  • emails (string) – email addresses to invite to the room as a comma separated list (e.g. franz@ferdinand.at,sepp@forcher.at,lachs@manner.at)

  • expires_at (string) – the date when the room membership for the invited guests should expire (ISO8601 formatted date - e.g.: ‘2019-09-11’) must be in the future

Returns

users (array) with user objects (object). These users have the following format:

  • email (string) - email from the list of emails

  • new (bool) - was the user newly created

  • id (int) - the user’s ID or Null if an error occurred

  • error (string) - the error text if an error occurred (e.g. invalid email address) or Null if it was successful

Return type

Array

Raises
  • instant.rpc.UserExceptionInvalidRoom – If the the room cannot be found

  • instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to perform the invite

list_members(room_id, params=None)

Get basic information to display about the members of a room. The room members are ordered by the time they joined.

Parameters
  • room_id (int) –

  • params (object) –

    Optional arguments for pagination:

    • limit (int) - maximum of entries to return (defaults to 25)

    • after (string) - ISO8601 timestamp specifying where in the ordered list of room members to begin – the returned members will have a joined_at timestamp strictly grater than this value

Returns

A JSON object with the following fields:

  • total (int) - the total number of members

  • results (array[object]) - a list of objects containing basic information about room members:

    • id (int)

    • username (string)

    • email (string)

    • avatar (string) - URL of the avatar

    • display_name (string)

    • status (int) - presence status within the organization:

      • null: status events disabled

      • 0: offline

      • 16: online

    • pm (int) - ID of the private message channel between the current user, and the specified user, null if the users don’t have a PM channel

    • joined_at (timestamp) - when the user joined the room

  • next_page (object) - the value of params to use to get the next page of members; null if there cannot be a next page

Return type

Object

rename(channel_id, name)

Change a rooms name (and slug).

Only organization owners, admins and the room creator may rename a room.

Parameters
  • channel_id (int) – ID of the channel to rename

  • name (string) – New name for the room. The slug will be created automatically from the name. Has to abide the same restrictions as name in create()

Returns

An object with two properties: - name (string) - slug (string)

Return type

Object

Raises
  • instant.rpc.UserExceptionInvalidRoom – If the the room cannot be found

  • instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to perform the rename

  • instant.rpc.UserExceptionInputError – If the name is not valid for any reason (empty, too long or already taken)

Events
set_color(channel_id, color)

Sets a color of the room-icon in the sidebar navigation

Parameters
  • channel_id (int) – ID of the channel to rename

  • color (string) –

    The new room color as RGB hex value. Allowed formats are:
    • RRGGBB

    • #RRGGBB

    Lower/uppercase doesn’t matter. Only a specific pallette of colors is valid. The allowed pallete can be found in the module chat’s ROOM_ICON_COLOR_PALETTE attribute.

Raises
  • instant.rpc.UserExceptionInvalidRoom – If the room was not found

  • instant.rpc.UserExceptionInvalidColor – If the color is not in the allowed color palette.

  • instant.rpc.UserExceptionNotAuthorized – If the current user has insufficient rights to modify the room

set_description(channel_id, description)

Set a room’s description.

The description explains what should be talked about in the room and it usually doesn’t change very often. It’s not the current topic of discussion, there is no such thing yet.

Parameters
  • channel_id (int) – ID of the channel whose description to change

  • description (string) – actual description text for the channel

Raises
  • instant.rpc.UserExceptionNotAuthorized – If the requesting user is not admin or owner of the organization

  • instant.rpc.UserExceptionInvalidRoom – If the room was not found

Events
set_icon(channel_id, icon_slug)

Sets a room-icon in the sidebar navigation

Parameters
Raises
  • instant.rpc.UserExceptionInvalidRoom – If the room does not exist

  • instant.rpc.UserExceptionIconNotFound – If no icon with the provided slug exists

  • instant.rpc.UserExceptionNotAuthorized – If the current user has insufficient rights to modify the room

set_public(channel_id, public)

Sets the room privacy to public or private

Parameters
  • channel_id (int) –

  • public (bool) –

Raises
  • instant.rpc.UserExceptionInvalidRoom – If the room was not found

  • instant.rpc.UserExceptionNotAuthorized – If the current user has insufficient rights to modify the room

validate_group(org_id, params)

Validates name and description of a new group before really creating it.

Parameters
  • org_id (int) – ID of the organization

  • params (Object) –

    An Object with all relevant group-data:

    • name (string) - Name of the new Group.

    • organization (int) - Organization ID to which the group

      belongs

    • description (string, optional) - A short user-defined

      descriptional text.

Returns

An object with containing a dictionary of validation errors, if any: - errors (dict)

Return type

Object

managedrooms

class chat.rpc.ManagedRooms(user, **kwargs)

Namespace for managing “managed” rooms. These rooms can only be managed by the creator of the room by using this namespace.

add_members(channel_id, users, field='user_id')

Add Users to the given room.

Parameters
  • channel_id (int) –

  • users (Array) –

    • list of users values

  • field (string, optional) –

    • How to interpret the values in the users array. possible values see get_members

Returns

A JSON object with the following fields:

  • added - (list - user names that have been added to this room

  • failed - (list) - user names that raised an error when trying to add.

Return type

Object

create(params)

Creates a new public or private room

Parameters

params (Object) –

An Object with all relevant room-data:

  • name (string) - Name of the new Room. Must be unique per organization (case-insensitively), non-empty and max 50 characters long.

  • organization (int) - ID of the organization where to create the room

  • description (string, optional) - A short user-defined descriptional text.

  • reference_url (string, optional) - Just a reference URL

  • reference_label (string, optional) - label for urls in managed rooms

Returns

An object with the following fields:

  • id (int)

  • type (string)

  • creator (int) - User ID of the room’s creator

  • created (int) - unix timestamp of creation-time

  • name (string) - Room name

  • slug (string) - generated URL-slug (derived from name)

  • description (string) - room description text

  • abbr (string) - 2 letter abbreviation of room name

  • color (string) - icon-color for display in sidebar. See set_color()

  • icon (string) - icon-slug for display in sidebar. See set_icon()

  • is_public (bool)

  • users (Array[int]) - An Array of user-ids of channel members

  • invites (Array[int]) - Array of user-ids of invited users

Return type

Object

Raises

instant.rpc.ValidationError – if any of the provided data is invalid (e.g. room-name does already exist)

Events
delete(channel_id)

Delete the room and all his messages.

Parameters

channel_id (int) –

Returns

It always returns True

Return type

Bool

Raises

instant.rpc.UserException

get_members(channel_id, field='user_id')

Get the user_ids of all members of the given room.

Parameters
  • channel_id (int) –

  • field (string, optional -) –

    • Field to be returned for a user. choices are

      • ”id” - internal user id (default)

      • ”ad_name” - the active directory sAMAccountName if LDAP is configured

      • ”email” - the email

      • ”username” - the internal username

Returns

An Array of members’ IDs

Return type

list

remove_members(channel_id, users, field='user_id')

Remove members from the given room.

Parameters
  • channel_id (int) –

  • users (list - list of user ids to be added to the room) –

  • field (string, optional) –

    • How to interpret the values in the users array. possible values see get_members

Returns

A JSON object with the following fields:

  • deleted - (list) - user ids that have been removed from this room

Return type

Object

pm

class chat.rpc.PM(user, **kwargs)
broadcast_message(org_id: int, options: Optional[dict]) → dict

Sends PM messages to one or more users - this RPC call can only be used by a [Bot User]() every user receives the PM only once, no matter how often he is included in user IDs, groups or teams If any ID in the receivers object is invalid, the operation will fail and raise a UserException. In case of an Error the bot will send nothing.

Parameters
  • org_id ((int) - The Organization ID) –

  • options ((object) - a object that must contain the following) –

    • message: (string) or (object) The message that should be sent to the selected users. See .

    • receivers: (object) - the users that should receive a PM with the specified message from a bot user

      • users: (list<int>) a list of User IDs - optional

      • group: (list<int>) a list of Group IDs. All Users in those Groups will receive the PM - optional

      • teams: (list<int>) a list of Team IDs. All Users in those Teams will receive the PM - optional

Returns

  • status (string) - “ok”

  • status_code (int)

  • reached_users (list) name of all the users that where reached with the message

  • reached_users_count (int) how many users where contacted with this message

Return type

object

Raises

UserException

get_overview(org_id, exclude_empty=True)

Gives a overview over all the Users in the Organization for existing PM Channels last message, unread and mentions will be provided as well

Parameters
  • org_id (int - The Organization ID) –

  • exclude_empty (bool - (deprecated - always True now) whether to include or exclude empty PM channels) –

Returns

An Array of PM objects. PMs contain the following fields:

  • group_mentions (int) - count of group mentions in the room

  • id (string) - Room ID

  • last_message (Object) - The last Message Object

    • attachments (Array[Object]) - A list of attachment Objects which have the following fields:

      • url (string) - The attachments URL

      • id (string) - Attachment ID

      • name (string)

      • type (string) attachment type. obsolete, please use mime_type instead.

      • mime_type (string)

      • source (string) - if attachment was created through external service, this indicates its source (e.g. giphy)

      • time (string)

      • thumbnail_url (string)

      • thumbnail_width (int)

      • thumbnail_height (int)

    • author (Object)

      • type (string) - "user"

      • id (int) - User ID of the message-author

      • displayName- (string)

      • firstName- (string)

      • lastName- (string)

      • avatar- (string) - URL to the avatar image of the user

    • channel (int) - Channel ID where the message was posted (always the same as room ID)

    • clientside_id (string) - See chat.rpc.Channels.post()

    • id (string) - Message ID

    • mentions (Object)

      • user (Array[int]) - User-ids of all users mentioned

        in this message

      • group (Array[int]) - group-ids of all group mentions

    • organization (int) - Organization ID of the channel

    • plain_text (string) - Plain text version of the message

    • text (string) - Rendered message text; may contain html

    • time (string) - ISO8601 timestamp of post-time

    • user_time (string) - ISO8601 timestamp of poster’s post-time

  • mentions (int) - count of mentions in the room

  • partner (Object) - PM Channel User

    • avatar (string) - URL to the user’s avatar

    • displayName (string)

    • email (string)

    • firstName (string)

    • id (int) - user ID

    • is_only_invited `` *(bool)* - ``true if user has not signed up

    • lastName (string)

    • phone_number (string) or None

    • skype_username (string) or None

    • hide_email_field (boolean)

    • status (int) - presence status within the organization:

      • 0 Offline

      • 4 Reachable

      • 16 Online

      • null if online status is turned off

    • username (string)

    • what_i_do (string)

  • unread (int) - count of unread messages

  • pin (int|None) - sorting value of the PM

Return type

list

open(organization_id, user_id)

Open private message with a user

The first time a client opens a private conversation with another user, this method will create the necessary Channel objects in the database, and create an initial history.

Parameters
  • organization_id (int) –

  • user_id (int) –

Returns

An object with the following fields:

  • id (int) - channel id

  • type (string) - "pm"

  • creator (int) - User ID of the creator

  • created (int) - UNIX timestamp of creation time

  • users (Array[int]) - Array of user IDs of all active users in this room (should be exactly 2)

  • invites (Array[int]) - User IDs of invited users (empty in this case, as people cannot be invited to private channels).

Return type

Object

Raises

ValueError – if the requesting user is the same as the user from the parameters

organizations

class accounts.rpc.Organizations(user, **kwargs)
get_invite_url(organization_id)

Gets the invite_url of the organization.

Parameters

organization_id (int) – The organization id

Returns

Return type

invite_url - (string)

Raises

instant.rpc.UserExceptionInvalidOrganization – If the organization_id is not valid for the user.

get_organization(organization_id, options=None)

Returns details about an organization

Returns all relevant organization data for the organization with the given id. The response includes basic organization information (logo, name etc) along with all users and channels the company has.

Parameters
  • organization_id (int) – An organization-ID

  • options (object, optional) –

    An optional object with the following field:

    • return_users (bool) - indicates whether to include the users attribute in the results, or not, defaults to true

    • return_channels (bool) - indicates whether to include the channels attribute in the results, or not, defaults to true

Returns

An Object describing the organization. The result includes the following properties:

  • id (int)

  • name (string) - human-readable organization name

  • subdomain (string) - unique subdomain of this organization

  • logo (string) - URL of the logo

  • has_integrations (bool) deprecated - indicates whether the organization has any configured legacy integrations

  • custom_emojis (object) - a dictionary mapping custom emoji names to their image URLs

  • features (object) - a dictionary mapping optional feature names to boolean flags which indicate whether the feature is enabled for this organization, or not

  • invited_users (empty array) deprecated

  • inviter_role (int) - minimum role required to invite new members to this organization

  • message_edit_timeout (int) - how long it’s possible to edit or delete messages after posting, in seconds; null if there is no limit

  • users (array) - see below

  • channels (array) - see below

  • billing_warning (object, optional) - a dictionary only included for trial organizations, and only if the current user is an administrator; contains the following fields:

    • level (string) - emergency if the trial has expired, info otherwise

    • text (string) - a human-readable message about the trial status

  • support_link (string) - a link (HTTP(S) or mailto) that users in this organization should be directed to for support

  • defaults (object) - the organization defaults

    • group_defaults (object) - group specific defaults

      • visibility (string) - either public or private

  • permissions (object) - The permissions the logged in user has on this organization

    • can_invite_members (bool) - is the user allowed to invite members into the Organization

    • can_manage_members (bool) - Is the user allowed to manage members of the Organization

    • can_view_organization_settings (bool) - Is the user allowed to see the Organization Settings

    • can_add_integration (bool) - Is the user allowed to add Integrations

    • can_use_grapesearch (bool) - Is the user allowed to use the grapesearch (#)

    • can_create_room (bool) - Is the user allowed to create now groups

    • can_create_pm_guest (bool) - Is the user allowed to create PM with a guest

    • can_create_pm_user (bool) - Is the user allowed to create PM with a user

    • can_switch_organization (bool) - Can the user switch to a different organization

channels is an Array of channel-objects. A channel object can either describe a room or a private message (pm). Both room and pm objects have the following properties:

  • id (int) - channel ID

  • type (string) - “pm” or “room”

  • name (string) - channel name or display_name of the PM partner

  • icon (string) - PM partner avatar URL or slug of a room’s icon, see also list_icons() and set_icon()

  • users (Array[int]) - user IDs of all users in this channel

  • invites (Array[int]) - user IDs of invited users

  • creator (int) - user ID of creator

  • created (int) - UTC unix-timestamp of the creation time

Room objects have these additional properties:

  • slug (string) - A URL slug derived from name

  • description (string) - A brief room description

  • abbr (string) - 2 letter room abbreviation based on name which is used in room-listings

  • color (string) - RGB color code for UI elements regarding display of this room

  • is_public (bool) - public/private switch. See Rooms

  • is_managed (bool) - manged rooms cannot be edited with the normal Rooms API

Besides channels, unless return_users has been set to false in the arguments, the response also contains an Array of all users that exist within the company. This contains also deleted users (distinguised by an active flag). users entries follow this format:

  • id (int) - user ID

  • username (string)

  • firstName (string)

  • lastName (string)

  • displayName (string)

  • avatar (string) - URL to the user’s avatar

  • is_only_invited (bool) - true if user has not signed up

  • status (int) or None - presence status within the organization:

    • null status events disabled

    • 0 Offline

    • 4 Reachable

    • 16 Online

  • role (int) - role within organization:

    • 0: regular user

    • 1: admin

    • 2: organization owner

  • title (string) - the user’s title

  • active (bool) - false if user has been deleted

  • pm (int) - ID of the private message channel between the current user and this entry’s user, null if the users don’t have a PM channel

Return type

Object

get_stats(organization_id)

Returns stats about an organization

Parameters

organization_id (int) – An organization-ID

Returns

The result includes the following properties::
  • unreadCount (int)

  • channelCount (int)

  • unreadChannelCount (int)

  • userCount (int)

Return type

Object

get_user(organization_id, user_id)

Deprecated; use Users.get_user().

invite(organization_id, params)
Parameters
  • organization_id (int - the organization id where the users should be invited to) –

  • params (object - containing 3 keys) –

    • emails (string): should be a comma-separated list of email addresses to invite

    • message (string): the personalized message the invite mails contains

    • sso_user (bool), optional: should the invited users be able to login via SSO using the current IdP configuration? If no SSO is configured for the organization, this option is ignored. Note: when inviting users as SSO users, no invitation mails are sent.

Returns

emails that where invited

Return type

Array[String]

Raises
  • instant.rpc.ValidationError – the organization_id was invalid

  • PermissionDenied – if the user doesn’t have the permissions to invite users.

join(organization_id, subscribe=True)

Connect to a organization to receive events and be shown as online.

Parameters
  • organization_id (int) –

  • subscribe (bool (optional)) –

    • If True the user will be automatically subscribed to every available channel

    • If False only subscribe to the organization

leave(organization_id)

Tells the app you are offline in organization and no longer want to receive events

list_icons(organization_id)

Returns list of room icon slugs currently the icons are the same for all organizations. This is just a permission test if the user is in an active organization.

Parameters

organization_id (int) – An organization-ID

Returns

A list of icons: [‘education’, ‘chart’, ‘science’, …]

Return type

list

remove_member(organization_id, user_id)

Deactivate a user in the organization. This requires the active user to have respective permissions.

Parameters
  • organization_id (int) –

  • user_id (int) –

Returns

Return type

result - (bool) True if successfully removed, None if the membership doesn’t exist

Raises
  • instant.rpc.ValidationError – if the organization_id and or user_id is not valid.

  • PermissionDenied – if the user doesn’t have the permissions to remove the user.

users

class accounts.rpc.Users(user, **kwargs)
connect(session_id)

Called when the client connection is established.

Currently this is only called sever-side by our WAMP Implementation

disconnect(session_id)

Called when the client connection is destroyed.

Currently this is only called sever-side by our WAMP Implementation

get_profile(*args, **kwargs)
get_user(organization_id, user_id)

Returns the details of a single user in the context of an organization.

Parameters
  • organization_id (int) – The ID of an organization within which where the user should be looked up

  • user_id (int) – The ID of the user to be looked up

Returns

A JSON object with the following fields:

  • id (int)

  • username (string)

  • email (string)

  • avatar (string) - URL of the avatar

  • display_name (string)

  • status (int) - presence status within the organization:

    • null: status events disabled

    • 0: offline

    • 16: online

  • first_name (string)

  • last_name (string)

  • phone_number (string)

  • skype_username (string)

  • skype_for_business (string)

  • what_i_do (string)

  • role (int) - role within the organization:

    • 0: regular user

    • 1: administrator

    • 2: owner

  • title (string)

  • is_active (bool) - false indicates users removed from the organization

  • pm (int) - ID of the private message channel between the current user, and the specified user, null if the users don’t have a PM channel

  • permissions (object) - The permissions the logged in user has on the requested user
    • can_create_pm (bool) - is the logged in user allowed to start a PM with the requested user

Return type

Object

get_users(org_id, params=None)

Get a paginated list of users in the organization which are available for chatting with the requesting user.

The result does not include the requesting user.

Parameters
  • org_id (int) – ID of the organization

  • params (Object, optional) –

    Specifies query options when fetching the users:

    • page (int, optional) - Page number Default: 1

    • page_size (int, optional) - Page size Default: 25

    • section (string, optional) - Return only users who belong to that section. If the amount of users returned is not enough to fill the whole page, users from next section will be also returned

    • reversed (boolean, optional) - Returns results in reverse order

      -True Results will be in reverse order

      -False|None|missing Results in be alphabetically sorted

    • query (string, optional) - Search term for user. When this parameter is present, sorting will be according to relevance. Parameters section, reversed and memberships will be ignored.

    • membership (boolean, optional) - filter for active memberships of the user:

      -True Return users user has a PM with

      -False Return users user hasn’t a PM with

      -None|missing Return all users.

Returns

  • result (list) A List of user objects sorted by name

    • id (int)

    • username (string)

    • email (string)

    • avatar (string) - URL of the avatar

    • display_name (string)

    • status (int) - presence status within the organization:

      • null: status events disabled

      • 0: offline

      • 16: online

    • first_name (string)

    • last_name (string)

    • phone_number (string)

    • skype_username (string)

    • skype_for_business (string)

    • what_i_do (string)

    • hide_email_field (boolean)

    • role (int) - role within the organization:

      • 0: regular user

      • 1: administrator

      • 2: owner

    • title (string)

    • is_active (bool) - false indicates users removed from the organization

    • pm (int) - ID of the private message channel between the current user, and the specified user, null if the users don’t have a PM channel

    • last_message_timestamp` (string) - Timestamp in ISO Format and with timezone at which the last message was sent in a Private Conversation with this user. Returns null if no message was sent.

Return type

Object

There will also be present the pagination parameters (check the Pagination documentation for details).

get_users_by_ids(org_id, user_ids, params=None)

Get a paginated list of users in the organization based on there IDs.

Parameters
  • org_id (int) – ID of the organization

  • user_ids (list) – User’s IDs

  • params (Object, optional) –

    Specifies query options when fetching the users:

    • page (int, optional) - Page number Default: 1

    • page_size (int, optional) - Page size Default: 25

Returns

  • result (list) A List of user objects sorted by name
    • id (int)

    • username (string)

    • email (string)

    • avatar (string) - URL of the avatar

    • display_name (string)

    • status (int) - presence status within the organization:

      • null: status events disabled

      • 0: offline

      • 16: online

    • first_name (string)

    • last_name (string)

    • phone_number (string)

    • skype_username (string)

    • skype_for_business (string)

    • hide_email_field (boolean)

    • what_i_do (string)

    • role (int) - role within the organization:

      • 0: regular user

      • 1: administrator

      • 2: owner

    • title (string)

    • is_active (bool) - false indicates users removed from the organization

    • pm (int) - ID of the private message channel between the current user, and the specified user, null if the users don’t have a PM channel

    • last_message_timestamp` (string) - Timestamp in ISO Format and with timezone at which the last message was sent in a Private Conversation with this user. Returns null if no message was sent.

Return type

Object

There will also be present the pagination parameters (check the Pagination documentation for details).

get_users_sections(org_id, params=None)

Users can be grouped into sections according to the first letter of his or her first name of last name, depending on USER_DISPLAY_NAME_METHOD settings.

This endpoint will returns all sections available.

Parameters

org_id (int) – ID of the organization

Returns

  • result (list) A List of sections sorted alphabetically

Return type

Object

set_profile(*args, **kwargs)

notifications

class notifications.rpc.Notifications(user, **kwargs)

Notification related actions.

get_settings(path='')

Returns the current user’s notification settings.

Returns the user’s settings depending on the path scope provided. If path is empty, settings for all channels are returned.

Parameters

path (string) – An optional filter-string. Settings can be filtered by Organization (e.g. path=”1”) or by channel (e.g. path=”1:23”)

Returns

A list of setting setting objects which have these properties:

  • active (bool) - whether the user wants to receive notifications from dispatcher over transport

  • inherit (bool) - If true, the value of active is not set explicitly, but interhited from the system defaults or settings with a higher level path.

  • dispatcher (string) - dispatcher key, e.g. ‘pm’, ‘mention’

  • transport (string) - transport key, e.g. ‘push’, ‘email’

Return type

Array[Object]

Examples

[ { 'active': true,
    'inherit': true,
    'dispatcher': 'pm',
    'transport': 'push'
  },
  { 'active': true,
    'inherit': false,
    'dispatcher': 'pm',
    'transport': 'email'
  },
...
]

In this (incomplete) example, the user will receive push but no email notification for private messages. The push setting was interhited from the system defaults but the email one was deliberately chosen by the user.

remove_notification_session(organization_id, force=False)

Remove this session as the users session to receive desktop notifications.

Parameters
  • organization_id (integer) – The id of the currently active organization

  • force (boolean (default=False)) – Should the session be removed even if its not the own session.

Raises

instant.rpc.UserExceptionInvalidOrganization` – If the session is not online in the given organization.

set_notification_session(organization_id)

Set this session as the user session to receive desktop notifications

Parameters

organization_id (integer) – The id of the currently active organization

Raises

instant.rpc.UserExceptionInvalidOrganization – If the session is not online in the given organization.

update_settings(path, sequence)

Set the users notification settings for a given path.

Parameters
  • path (string) – The path of the setting (See get_settings() params for reference)

  • sequence (Array[Object]) –

    A sequence of changes made on the given path. Each entry contains these properties:

    • dispatcher (string) - dispatcher key, e.g. “pm”, “mention”

    • transport (string) - transport key, e.g. “push”, “email”

    • active (bool) - Whether to receive notifications from dispatcher via transport.

      Value can be null, in which case the default setting is being inherited (either from system defaults or settings with higher ranking path.

Raises

instant.rpc.UserExceptionMulitpleValues – If the request tries to change the same dispatcher/transport combination more than once in the same call.

Examples

sequence = [
    {
        "dispatcher": "pm",
        "transport": "email",
        "active": true
    },
    {
        "dispatcher": "pm",
        "transport": "push",
        "active": null
    },
    {
        "dispatcher": "mention",
        "transport": "push",
        "active": false,
    }
]

calls

class grapecall.rpc.Calls(user, **kwargs)

Namespace for all relevant RPC methods related to grapecall

call(params: dict)

Calls a user

Parameters

params (Object) –

An Object with all relevant call data:

  • channel_id (int): ID of the channel

cancel(params: dict)

Cancels a call. This RPC should be used when user cancels a call or when call is automatically canceled after ringing for some time.

Parameters

params (Object) –

An Object with all relevant call data:

  • channel_id (int): ID of the channel

get_channel_and_partner(channel_id)
get_token(params: dict)

Get Jitsi authorization token

Parameters

params (Object) –

An Object with all relevant call data:
  • channel_id (int): ID of the channel

hangup(params: dict)

Hung up a call

Parameters

params (Object) –

An Object with all relevant call data:

  • channel_id (int): ID of the channel

join(params: dict)

Joins a call

Parameters

params (Object) –

An Object with all relevant call data:

  • channel_id (int): ID of the channel

reject(params: dict)

Rejects a call

Parameters

params (Object) –

An Object with all relevant call data:

  • channel_id (int): ID of the channel