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
Objects. IMPORTANT Reading this property flushes the message queue, so a 2nd read will return no messages. |
members |
Object |
List of
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.
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()
Request to leave a chatroom. Other members remain unmodified.
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
Parameter |
Type |
Description |
data |
File |
File handle. |
room.videoChat(stream) ⇒ Av
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)
Currently only useful for modifying room name.
Parameter |
Type |
Description |
data |
Object |
{name: "room name", gomulti: Bool} |
room.setSeen(msgID)
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)
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)
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.