API Version: 6.2

Reference

/

Classes

/

IPCortex.Types.Room

   
  • IPCortex.Types.Room
  • Permissions
  • Roster permissions
  • Properties
  • Static Properties
  • Methods
  • room.post
  • room.add
  • 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

    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.

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