API Version: Development

Reference

/

Classes

/

IPCortex.Types.Room

   
  • IPCortex.Types.Room
  • Permissions
  • Roster permissions
  • Room types
  • Properties
  • Static Properties
  • Methods
  • room.post
  • room.add
  • room.getHistory
  • room.leave
  • room.remove
  • room.sendFile
  • room.videoChat
  • room.modify
  • room.setSeen
  • room.addListener
  • room.removeListener
  • Events

    • IPCortex.Types.Room

    A Room instance represents a chatroom, its members and the messages in it. It is also used to access AV, Command channel and File sharing features.

    Permissions

    There are 3 levels of permission with rooms:
    • External users - Have very little permission. They can participate in a Room to which they have been invited, and may choose to leave that room. Once in a room they have access to any of the room features that have been loaded into their API instance, such as AV or File transfer.
    • Regular PABX account users - May create a Room and invite other contacts who are in their 'Roster' (see Roster permissions below) and may also invite any external user who is currently active to a room.
    • api_chat accounts - Have all the same access levels of a regular user, but will also have visibility of all active Room sessions in their administered company list, even if they are not a participant in the room. They may not participate in these rooms, but may add users to any room they can see, and can create rooms without needing to be a participant.

    Roster permissions

    When contacts exist within the same company (or container) all contacts are presumed permitted to chat with all other contacts. Outside of this, XMPP-style permissions are used.
    Roster permissions represent standard XMPP style permissions, where each party must acknowledge the other in order to grant permission for conversations to be started. The system (PABX) administrator may pre-configure the system so that all contacts within a company are automatically configured to be able to chat with all other contacts. See the Contact.xmppReq(), Contact.xmppAuth() and Contact.xmppDel() methods for means of setting up these permissions at a more granular level.

    Room types (transient one-to-one)

    A room where neither public nor archive flags have been set, and which involves only 2 parties. The remote party may be an XMPP user. As long as no XMPP user is present in the room, this room may be upgraded to a transient multi room by simply inviting an additional user.
    This room will be expired a short time after the last member leaves the room and all messages lost.

    Room types (transient multi)

    A room where neither public nor archive flags have been set, and which involves 2 or more parties. XMPP users may not be included in this room type since we do not support any of the XMPP multi-user room protocols.
    This room will be expired a short time after the last member leaves the room and all messages lost.

    Room types (persistent one-to-one)

    A room where the archive flag has been set on creation, and which involves only 2 parties. The remote party may be an XMPP user. As long as no XMPP user is present in the room, this room may be upgraded to a persistent multi room by simply inviting an additional user.
    This room will be retained permanently, and if a persistent one-to-one room between the same 2 users is subsequently requested, then the room will be reopened.
    NOTE: Because a persistent one-to-one room may have significant history of messages, it is not considered appropriate to actually directly upgrade this room to a multi-room. Instead, the one-to-one room is closed, and a new multi-room is opened with the relevant members in it, but none of the historical chat.

    Room types (persistent multi)

    A room where the archive flag has been set on creation, and which involves 2 or more parties. XMPP users may not be included in this room type since we do not support any of the XMPP multi-user room protocols.
    This room will be retained permanently, but once the last member leaves, it can only be reopened/discovered administratively.
    The IPCortex.PBX.archiveRooms property can be used as a means of discovering accessible rooms where the user is not currently a member (was involved but subsequently left.)

    Room types (public)

    A room where the archive and public flags have both been set on creation, and which involves 2 or more parties. XMPP users may not be included in this room type since we do not support any of the XMPP multi-user room protocols.
    Even when all members have left, this room will persist, and any attempt to open a public room of the same name will reopen this room. Members of a public room will automatically go online in the room when they connect.
    The IPCortex.PBX.publicRooms property can be used as a means of discovering accessible rooms where the user is not currently a member.

    Properties

    Name Type Description
    roomID Number Unique identifer.
    cID Number Private room remote party contact ID.
    seen Number Message ID of the last seen message.
    label String Friendly name/label.
    messages Array List of message

    Object message

    Name Type Description
    cID Number Contact ID of the message owner.
    cN String Friendly name of the message owner.
    msg String The message that has been posted into the Room.
    msgID Number Unique number to identify the message.
    own Boolean True if the message is owned by the logged in user.
    initial Boolean True if the Room is new.
    time Epoch (seconds) Time the message was posted into the Room.
    Objects. IMPORTANT Reading this property flushes the message queue, so a 2nd read will return no messages.
    hist_messages Array List of message Objects. Filled by getHistory() class method. IMPORTANT Reading this property flushes the message queue, so a 2nd read will return no messages.
    members Object List of member

    Object member

    Name Type Description
    desc String Displayable description of online state.
    email String Email address.
    name String Friendly name.
    state String Online state.
    uname String Unique name.
    Objects by contact id.
    multi Boolean True if more than two members.
    archive Boolean True if room is set be be archive/permanent.
    public Boolean True if room is set be be public, ie. shared companywide.
    chatID String Unique identifier for matching with Address or Contact Classes.
    voyeur Bool If a room is only being seen becasue of admin rights, not membership of the room, then this property is true.
    replaces Number If a room was created as a replacement for another, this is set to the old room's roomID, else null.
    state String Room state.
    • new
    • invited
    • inviting
    • open
    • closed
    • dead (This state indicates the class will be destroyed)

    Static Properties

    Name Type Description
    canSMS Bool Boolean indicating whether SMS based chat invites are configured on the PABX.

    Methods

    room.post(message, callback) ⇒ Promise

    Kind: class method of IPCortex.Types.Room Returns: Promise - Resolves with message ID number on success.
    Parameter Type Description
    message String Message to post into the room.
    In a one-to-one chat room, calling post will cause the remote party to be re-added to the room if they have left, as if the room had been re-opened. The response to this call is always success becasue no attempt is made to verify delivery; Instead, if the message is correctly delivered, it will also be delivered back to the sender.

    room.add(contacts, callback) ⇒ Promise

    Kind: class method of IPCortex.Types.Room Returns: Promise - Resolves with Room class instance on success.
    Add a contact to the room. A room will automatically convert from a one-to-one chat room to a multi-user chat room if this call succeeds. Note that it is not possible to add to a room that has an XMPP contact in it, and that a room with a temporary/external contact in it is always considered a multi-user chat room.
    Parameter Type Description
    contacts Array Array of members to invite. Each contact is either the unique contact ID of an internal party, or an Object describing an external user. Each array element may also be an Address or Contact.
    See also IPCortex.PBX.chatInvite

    room.getHistory(restart) ⇒ Promise

    Kind: class method of IPCortex.Types.Room Returns: Promise - Resolves once all messages received
    Requests that the chat engine check for messages older than those returned to-date. If there are no older messages, this will have no effect, otherwise the hist_messages buffer will be filled and a history event will be raised. Each time this is called up to 100 messages will be fetched, and these messages will be progressively older. It is up to the recipient of these messages to ensure that received messaged are de-duped and correclty ordered client-side.
    This method is only useful on archive or public rooms since no persistent storage means there are no messages to fetch. The promise will reject for other room types.
    Parameter Type Description
    restart Bool (Optional) If true, resets history fetch low-water mark and requests newest messages.
    See also IPCortex.PBX.publicRooms

    room.leave()

    Kind: class method of IPCortex.Types.Room
    Request to leave a chatroom. Other members remain unmodified.

    room.remove(contact, callback)

    Kind: class method of IPCortex.Types.Room
    Request the removal of a contact from a room. This may only be called by a user with the api_chat permission. It will also not work on a 1-to-1 room, only a multi-room, though all rooms created administratively by the api_chat use of createRoom are created as multi-rooms.
    Parameter Type Description
    contact Number Contact ID of member to remove.

    room.sendFile(data) ⇒ File

    Kind: class method of IPCortex.Types.Room Returns: File - Class object for the file transfer.
    Send a file to all members in the room. See IPCortex.Types.File for more detail.
    Parameter Type Description
    data File File handle.

    room.videoChat(stream) ⇒ Av

    Kind: class method of IPCortex.Types.Room Returns: Av - Class object for the video call.
    Start a video conversation with all members in the room. See IPCortex.Types.Av for more detail.
    Parameter Type Description
    stream mediaStream mediaStream from getUserMedia()

    room.modify(data)

    Kind: class method of IPCortex.Types.Room
    Currently only useful for modifying room name.
    Parameter Type Description
    data Object {name: "room name", gomulti: Bool}

    room.setSeen(msgID)

    Kind: class method of IPCortex.Types.Room
    Set the highest message number seen. By default this is handled automatically and is updated to the latest message received; This can be changed using the autoseen property of the settings to IPCortex.PBX.enableChat when setting up chat.
    Parameter Type Description
    msgID Number The msg id from the most recently read message.

    room.addListener(event, callback)

    Kind: class method of IPCortex.Types.Room
    Add listener method, inherited from Api base class and common to all classes.
    Parameter Type Description
    event String Name of event, e.g. 'update'
    callback Function Callback which is passed a reference to the updated Class object

    room.removeListener(event, callback)

    Kind: class method of IPCortex.Types.Room
    Remove listener method, inherited from Api base class and common to all classes. event and callback must be identical to those used in addListener() in order for the remove to succeed.
    Parameter Type Description
    event String Name of event, e.g. 'update'
    callback Function Callback which is passed a reference to the updated Class object

    Events

    • new - A new room is created.
    • update - The room state changes, including new message arrival.
    • members - The member list or details about a member have changed. An update event will also fire for this change.
    • message - A message has arrived; There may be a 100ms pause while several messages are combined into one event. An update event will also fire for this change.
    • history - A requested history message has arrived; There may be a 500ms pause while several messages are combined into one event.