API Version: Development

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 Objects. IMPORTANT Reading this property flushes the message queue, so a 2nd read will return no messages.
members Object List of member 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.

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.