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. For now, users may only delete their own messages. Activities can be deleted by the channel creator, and the organization admins.

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
  • 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_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 deletted; 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
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
        • 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 channel_id: id of the channel the message is in. :type channel_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
        • 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]) – An array of email-addresses to be invited
  • 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)
  • **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::class:`instant.rpc.Userpc.pyrException` ``ChannelNotFound`` – 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) – Body of the message (as entered by user)
  • 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 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)
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.
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 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

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

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 - optional url
  • reference_label - optional label
    An Array of email addresses to be invited.
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)
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

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

      • 0 Offline
      • 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

  • 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
    • 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

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
    • query (string, optional) - Search term for user
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)

    • 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

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,
    }
]