MUC Service Plugin Readme

MUC Service is a plugin to manage the chat rooms over the REST/HTTP interface.
It is possible to get a XML based overview over all or filtered chat rooms and also to Create / Update / Delete chat rooms and there user roles.

Installation

Copy the file, “mucservice.jar” into the plugins directory of your Openfire installation. The plugin will then be automatically deployed.

Explanation of REST

To provide a standard way of accessing the data the MUC Service is using REST.

HTTP Method	Usage
GET	Receive a read-only data
PUT	Overwrite an existing resource
POST	Creates a new resource
DELETE	Deletes the given resource

Basic HTTP Authentication

All REST Endpoint are secured by Basic HTTP Authentication.

To access the endpoints is that required to send the Username and Password of a Openfire Admin account in your header request.

E.g. Header: Authorization: Basic YWRtaW46MTIzNDU= (username: admin / password: 12345)

Example for Jersey Client
Client c = Client.create(); c.addFilter(new HTTPBasicAuthFilter(user, password));

Data types

Chatroom

Parameter	Optional	Description
roomName	No	The name/id of the room. Can only contains lowercase and alphanumeric characters.
naturalName	No	Also the name of the room, but can contains non alphanumeric characters. It’s mainly used for users while discovering rooms hosted by the Multi-User Chat service.
description	No	Description text of the room.
password	Yes	The password that the user must provide to enter the room
creationDate	Yes	The date when the room was created. Will be automatically set by creation. Example: 2014-07-10T09:49:12.411+02:00
modificationDate	Yes	The last date when the room’s configuration was modified. If the room’s configuration was never modified then the initial value will be the same as the creation date. Will be automatically set by update. Example: 2014-07-10T09:49:12.411+02:00
maxUsers	Yes	the maximum number of occupants that can be simultaneously in the room. 0 means unlimited number of occupants.
persistent	Yes	Can be “true” or “false”. Persistent rooms are saved to the database to make their configurations persistent together with the affiliation of the users. Otherwise the room will be destroyed if the last occupant leave the room.
publicRoom	Yes	Can be “true” or “false”. True if the room is searchable and visible through service discovery.
registrationEnabled	Yes	Can be “true” or “false”. True if users are allowed to register with the room. By default, room registration is enabled.
canAnyoneDiscoverJID	Yes	Can be “true” or “false”. True if every presence packet will include the JID of every occupant.
canOccupantsChangeSubject	Yes	Can be “true” or “false”. True if participants are allowed to change the room’s subject.
canOccupantsInvite	Yes	Can be “true” or “false”. True if occupants can invite other users to the room. If the room does not require an invitation to enter (i.e. is not members-only) then any occupant can send invitations. On the other hand, if the room is members-only and occupants cannot send invitation then only the room owners and admins are allowed to send invitations.
canChangeNickname	Yes	Can be “true” or “false”. True if room occupants are allowed to change their nicknames in the room. By default, occupants are allowed to change their nicknames.
logEnabled	Yes	Can be “true” or “false”. True if the room’s conversation is being logged. If logging is activated the room conversation will be saved to the database every couple of minutes. The saving frequency is the same for all the rooms and can be configured by changing the property “xmpp.muc.tasks.log.timeout”.
loginRestrictedToNickname	Yes	Can be “true” or “false”. True if registered users can only join the room using their registered nickname. By default, registered users can join the room using any nickname.
membersOnly	Yes	Can be “true” or “false”. True if the room requires an invitation to enter. That is if the room is members-only.
moderated	Yes	Can be “true” or “false”. True if the room in which only those with “voice” may send messages to all occupants.
broadcastPresenceRoles	Yes	The list of roles of which presence will be broadcasted to the rest of the occupants.
owners	Yes	A collection with the current list of owners. The collection contains the bareJID of the users with owner affiliation.
admins	Yes	A collection with the current list of admins. The collection contains the bareJID of the users with admin affiliation.
members	Yes	A collection with the current list of room members. The collection contains the bareJID of the users with member affiliation. If the room is not members-only then the list will contain the users that registered with the room and therefore they may have reserved a nickname.
outcasts	Yes	A collection with the current list of outcast users. An outcast user is not allowed to join the room again. The collection contains the bareJID of the users with outcast affiliation.

GET /mucservice/chatrooms

Endpoint to get all chat rooms

Payload: none
Return value: Chatrooms

Possible parameters

Parameter	Parameter Type	Description	Default value
servicename	@QueryParam	The name of the Group Chat Service	conference
type	@QueryParam	public: Only as List Room in Directory set rooms all: All rooms.	public
search	@QueryParam	Search/Filter by room name. This act like the wildcard search %String%

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/mucservice/chatrooms

GET http://example.org:9090/plugins/mucservice/chatrooms?type=all

GET http://example.org:9090/plugins/mucservice/chatrooms?type=all&servicename=privateconf

GET http://example.org:9090/plugins/mucservice/chatrooms?search=test

GET /mucservice/chatrooms/{roomName}

Endpoint to get information over specific chat room

Payload: none
Return value: Chatroom

Possible parameters

Parameter	Parameter Type	Description	Default value
roomname	@Path	Exact room name
servicename	@QueryParam	The name of the Group Chat Service	conference

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/mucservice/chatrooms/test

GET http://example.org:9090/plugins/mucservice/chatrooms/test?servicename=privateconf

GET /mucservice/chatrooms/{roomName}/participants

Endpoint to get all participants with a role of specified room.

Payload: none
Return value: Participants

Possible parameters

Parameter	Parameter Type	Description	Default value
roomname	@Path	Exact room name
servicename	@QueryParam	The name of the Group Chat Service	conference

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/mucservice/chatrooms/room1/participants

POST /mucservice/chatrooms

Endpoint to create a new chat room.

Payload: Chatroom
Return value: HTTP status 201 (Created)

Possible parameters

Parameter	Parameter Type	Description	Default value
servicename	@QueryParam	The name of the Group Chat Service	conference

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

Header: Content-Type: application/xml

POST http://example.org:9090/plugins/mucservice/chatrooms

Payload Example 1 (required parameters):

<chatRoom>
    <naturalName>global-1</naturalName>
    <roomName>global</roomName>
    <description>Global Chat Room</description>
</chatRoom>

Payload Example 2 (available parameters):

<chatRoom>
    <roomName>global</roomName>
    <naturalName>global-2</naturalName>
    <description>Global Chat Room</description>
    <creationDate>2014-02-12T15:52:37.592+01:00</creationDate>
    <modificationDate>2014-09-12T15:35:54.702+02:00</modificationDate>
    <maxUsers>0</maxUsers>
    <persistent>true</persistent>
    <publicRoom>true</publicRoom>
    <registrationEnabled>false</registrationEnabled>
    <canAnyoneDiscoverJID>false</canAnyoneDiscoverJID>
    <canOccupantsChangeSubject>false</canOccupantsChangeSubject>
    <canOccupantsInvite>false</canOccupantsInvite>
    <canChangeNickname>false</canChangeNickname>
    <logEnabled>true</logEnabled>
    <loginRestrictedToNickname>false</loginRestrictedToNickname>
    <membersOnly>false</membersOnly>
    <moderated>false</moderated>
    <broadcastPresenceRoles>
        <broadcastPresenceRole>moderator</broadcastPresenceRole>
        <broadcastPresenceRole>participant</broadcastPresenceRole>
        <broadcastPresenceRole>visitor</broadcastPresenceRole>
    </broadcastPresenceRoles>
    <owners>
        <owner>owner@localhost</owner>
    </owners>
    <admins>
        <admin>admin@localhost</admin>
    </admins>
    <members>
        <member>member2@localhost</member>
        <member>member1@localhost</member>
    </members>
    <outcasts>
        <outcast>outcast1@localhost</outcast>
    </outcasts>
</chatRoom>

DELETE /mucservice/chatrooms/{roomName}

Endpoint to delete a chat room.

Payload: none
Return value: HTTP status 200 (OK)

Possible parameters

Parameter	Parameter Type	Description	Default value
roomname	@Path	Exact room name
servicename	@QueryParam	The name of the Group Chat Service	conference

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

DELETE http://example.org:9090/plugins/mucservice/chatrooms/testroom

DELETE http://example.org:9090/plugins/mucservice/chatrooms/testroom?servicename=privateconf

PUT /mucservice/chatrooms/{roomName}

Endpoint to update a chat room.

Payload: Chatroom
Return value: HTTP status 200 (OK)

Possible parameters

Parameter	Parameter Type	Description	Default value
roomname	@Path	Exact room name
servicename	@QueryParam	The name of the Group Chat Service	conference

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

Header: Content-Type application/xml

PUT http://example.org:9090/plugins/mucservice/chatrooms/global

Payload:

<chatRoom>
    <roomName>global</roomName>
    <naturalName>global-2</naturalName>
    <description>Global Chat Room edit</description>
    <password>test</password>
    <creationDate>2014-02-12T15:52:37.592+01:00</creationDate>
    <modificationDate>2014-09-12T14:20:56.286+02:00</modificationDate>
    <maxUsers>0</maxUsers>
    <persistent>true</persistent>
    <publicRoom>true</publicRoom>
    <registrationEnabled>false</registrationEnabled>
    <canAnyoneDiscoverJID>false</canAnyoneDiscoverJID>
    <canOccupantsChangeSubject>false</canOccupantsChangeSubject>
    <canOccupantsInvite>false</canOccupantsInvite>
    <canChangeNickname>false</canChangeNickname>
    <logEnabled>true</logEnabled>
    <loginRestrictedToNickname>false</loginRestrictedToNickname>
    <membersOnly>false</membersOnly>
    <moderated>false</moderated>
    <broadcastPresenceRoles/>
    <owners>
        <owner>owner@localhost</owner>
    </owners>
    <admins>
        <admin>admin@localhost</admin>
    </admins>
    <members>
        <member>member2@localhost</member>
        <member>member1@localhost</member>
    </members>
    <outcasts>
        <outcast>outcast1@localhost</outcast>
    </outcasts>
</chatRoom>

POST /mucservice/chatrooms/{roomName}/{roles}/{jid}

Endpoint to add a new user role to a room.

Payload: none
Return value: HTTP status 201 (Created)

Possible parameters

Parameter	Parameter Type	Description	Default value
roomname	@Path	Exact room name
jid	@Path	JID of the owner (username@xmppDomain)
roles	@Path	Available roles: owners admins members outcasts
servicename	@QueryParam	The name of the Group Chat Service	conference

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

Header: Content-Type application/xml

POST http://example.org:9090/plugins/mucservice/chatrooms/global/owners/owner@localhost

POST http://example.org:9090/plugins/mucservice/chatrooms/global/admins/admin@localhost

POST http://example.org:9090/plugins/mucservice/chatrooms/global/members/member@localhost

POST http://example.org:9090/plugins/mucservice/chatrooms/global/outcasts/outcast@localhost

POST http://example.org:9090/plugins/mucservice/chatrooms/global/owners/owner@localhost?servicename=privateconf

DELETE /mucservice/chatrooms/{roomName}/{roles}/{jid}

Endpoint to remove a room user role.

Payload: none
Return value: HTTP status 200 (OK)

Possible parameters

Parameter	Parameter Type	Description	Default value
roomname	@Path	Exact room name
jid	@Path	JID of the owner (username@xmppDomain)
roles	@Path	Available roles: owners admins members outcasts
servicename	@QueryParam	The name of the Group Chat Service	conference

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

Header: Content-Type application/xml

DELETE http://example.org:9090/plugins/mucservice/chatrooms/global/owners/owner@localhost

DELETE http://example.org:9090/plugins/mucservice/chatrooms/global/admins/admin@localhost

DELETE http://example.org:9090/plugins/mucservice/chatrooms/global/members/member@localhost

DELETE http://example.org:9090/plugins/mucservice/chatrooms/global/outcasts/outcast@localhost

DELETE http://example.org:9090/plugins/mucservice/chatrooms/global/owners/owner@localhost?servicename=privateconf

MUC Service Plugin Readme

Installation

Explanation of REST

Basic HTTP Authentication

Data types

Chatroom

Chat room related REST Endpoints

GET /mucservice/chatrooms

Possible parameters

Examples

GET /mucservice/chatrooms/{roomName}

Possible parameters

Examples

GET /mucservice/chatrooms/{roomName}/participants

Possible parameters

Examples

POST /mucservice/chatrooms

Possible parameters

Examples

DELETE /mucservice/chatrooms/{roomName}

Possible parameters

Examples

PUT /mucservice/chatrooms/{roomName}

Possible parameters

Examples

POST /mucservice/chatrooms/{roomName}/{roles}/{jid}

Possible parameters

Examples

DELETE /mucservice/chatrooms/{roomName}/{roles}/{jid}

Possible parameters

Examples