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.

Chat room related REST Endpoints

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