Murmurs Channels API

Murmurs Channels

There are two ways to setup Murmurs for your project; one is using built-in Murmurs and the other is integrating built-in Murmurs with an external Jabber chat room. All projects have the built-in Murmurs enabled as default. You can manage both settings via the Murmurs channels API.

Please note that all POST and PUT requests must be in XML format by default. This is not illustrated in the examples here. To specify parameters as shown in the examples you will have to set the request header for Content-Type to "application/x-www-form-urlencoded".

Structure of a built-in murmurs channel resource

The structure of the murmurs channel resource, and its attributes are described below, along with their data type. Also included with each attribute is whether you are allowed to update the value.

murmurs channel for built-in murmurs resource xml - attributes

enabled: Boolean; represents whether a project has Murmurs enabled or not. Set this to true to enable Murmurs.
project: Resource; name and identifier of a project. Both Strings.

Enable Murmurs for your project

You can enable or disable Murmurs from your project. By default all projects will have Murmurs enabled.

Reference

    Request Method: POST

    URL: /api/v2/projects/project_identifier/murmurs_channels/builtin.xml
  
    Parameters:
    murmurs_channel[enabled]: Boolean, determines whether to enable or disable Murmurs for this project.

Example

    POST

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/murmurs_channels/builtin.xml

    murmurs_channels[enabled]=true

Explanation

The above is an example of a PUT to enable Murmurs in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<murmurs_channel>
  <enabled type="boolean">true</enabled>
  <project url="http://localhost:8080/api/v2/projects/test_project.xml">
    <name>test project</name>
    <identifier>test_project</identifier>
  </project>
</murmurs_channel>

Disable Murmurs for your project

Example

    POST

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/murmurs_channels/builtin.xml

    murmurs_channel[enabled]=false

Explanation

The above is an example of a PUT to disable Murmurs in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<murmurs_channel>
  <enabled type="boolean">false</enabled>
  <project url="http://localhost:8080/api/v2/projects/test_project.xml">
    <name>test project</name>
    <identifier>test_project</identifier>
  </project>
</murmurs_channel>

Structure of a murmurs channel resource for a Jabber chat room

The structure of the murmurs channel resource, and its attributes are described below, along with their data type. Also included with each attribute is whether you are allowed to update the value.

murmurs channel for a project integrated with a Jabber chatroom resource xml - attributes

enabled: Boolean; represents whether a project is connected to a Jabber channel or not.
project: Resource; name and identifier of a project. Both Strings.
jabber_server_host: String; location of the host machine, sometimes called Server name, e.g. localhost.
jabber_server_port: Integer; Jabber server connection port, port on which the server accepts connections, usually 5222 as this is the standard port for clients to connect to the Jabber server.
jabber_conference_service: String; name of the Jabber server's chat service, provided by the Jabber server, usually conference.host.
jabber_chat_room_id: String; the id (name) of the Jabber channel you are trying to connect your project to.
jabber_chat_room_status: String; the current status of your Jabber channel your project is connected to.

Connect your project to an external Jabber chat room

Please note that you can only connect your project to an external Jabber channel if following conditions are met:

a Jabber server is configured for use with Mingle.
Murmurs is enabled for a project.

Connect to a Mingle generated external Jabber chat room

Reference

    Request Method: POST
    
    URL: /api/v2/projects/project_identifier/murmurs_channels/jabber.xml

    Parameters:
    jabber_channel[enabled]: Boolean, determines whether to connect or disconnect Murmurs.

Example

    POST

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/murmurs_channels/jabber.xml

    jabber_channel[enabled]=true

Explanation

The above is an example of a POST to connect Mingle to a chat room in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password. Since no Jabber channel id is provided with the request, Mingle will generate a new Jabber channel and connect your project to that channel.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

Please notice that your project is connected to an external Jabber chat room called 'mingle.test_project.1256718933.104'. Since each Jabber channel needs to have a unique name, Mingle added randomly generated integers after the project's identifier.

<?xml version="1.0" encoding="UTF-8"?>
<murmurs_channel>
  <enabled type="boolean">true</enabled>
  <project url="http://localhost:8080/api/v2/projects/test_project.xml">
    <name>test project</name>
    <identifier>test_project</identifier>
  </project>
  <jabber_server_host>test.server.com</jabber_host>
  <jabber_server_port type="integer">5222</jabber_port>
  <jabber_conference_service>conference.test.server.com</jabber_conference_service>
  <jabber_chat_room_id>mingle.test_project.1256718933.104</jabber_chat_room_id>
  <jabber_chat_room_status>Ok</jabber_chat_room_status>
</murmurs_channel>

Connect to an external Jabber chat room

Reference

    Request Method: POST
    
    URL: /api/v2/projects/project_identifier/murmurs_channels/jabber.xml
    
    Parameters:
    jabber_channel[enabled]: Boolean, determines whether to connect or disconnect Murmurs settings.
    jabber_channel[jabber_chat_room_id]: String, id(name) of the Jabber channel to connect your project to.

Example

    POST

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/murmurs_channels/jabber.xml

    jabber_channel[enabled]=true
    jabber_channel[jabber_chat_room_id]=your_jabber_chat_room_id

Explanation

The above is an example of a POST to enable Murmurs and connect to your external Jabber channel with a chat room id "your_jabber_chat_room_id" in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<murmurs_channel>
  <enabled type="boolean">true</enabled>
  <project url="http://localhost:8080/api/v2/projects/test_project.xml">
    <name>test project</name>
    <identifier>test_project</identifier>
  </project>
  <jabber_server_host>test.server.com</jabber_host>
  <jabber_server_port type="integer">5222</jabber_port>
  <jabber_conference_service>conference.test.server.com</jabber_conference_service>
  <jabber_chat_room_id>your_jabber_chat_room_id</jabber_chat_room_id>
  <jabber_chat_room_status>Ok</jabber_chat_room_status>
</murmurs_channel>

Disconnect your project from an external Jabber chat room

Example

    POST

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/murmurs_channels/jabber.xml

    jabber_channel[enabled]=false

Explanation

The above is an example of a POST to disconnect Mingle from an external chat room in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

Please note that if the project was ever connected to a Jabber channel, the last Jabber channel id the project was connected to will be displayed in a returned result - e.g. mingle.test_project.1256718933.104. Thus as long as you have a jabber_config.yml file configured, the server information will be available on the result as well.

<?xml version="1.0" encoding="UTF-8"?>
<murmurs_channel>
  <enabled type="boolean">false</enabled>
  <project url="http://localhost:8080/api/v2/projects/test_project.xml">
    <name>test project</name>
    <identifier>test_project</identifier>
  </project>
  <jabber_server_host>test.server.com</jabber_host>
  <jabber_server_port type="integer">5222</jabber_port>
  <jabber_conference_service>conference.test.server.com</jabber_conference_service>
  <jabber_chat_room_id>mingle.test_project.1256718933.104</jabber_chat_room_id>
  <jabber_chat_room_status>Ok</jabber_chat_room_status>
</murmurs_channel>

Get Murmurs settings status for your project

There are two Murmurs settings you can check; one is whether Murmurs is enabled or disabled for a project and the other is whether your project is connected to an external Jabber channel or not.

To check if Murmurs are enabled for your project...

Reference

    Request Method: GET
    
    URL: /api/v2/projects/project_identifier/murmurs_channels/builtin.xml
    
    Parameters: NA

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/murmurs_channels/builtin.xml

Explanation

The above is an example of a GET to check the Murmurs settings in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<murmurs_channel>
  <enabled type="boolean">true</enabled>
  <project url="http://localhost:8080/api/v2/projects/test_project.xml">
    <name>test_project</name>
    <identifier>test_project</identifier>
  </project>
</murmurs_channel>

To check if your project is connected to an external Jabber chat room...

Reference

    Request Method: GET
    
    URL: /api/v2/projects/project_identifier/murmurs_channels/jabber.xml
    
    Parameters: NA

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/murmurs_channels/jabber.xml

Explanation

The above is an example of a GET to check the Murmurs settings in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<murmurs_channel>
  <enabled type="boolean">true</enabled>
  <project url="http://localhost:8080/api/v2/projects/test_project.xml">
    <name>test project</name>
    <identifier>test_project</identifier>
  </project>
  <jabber_server_host>test.server.com</jabber_host>
  <jabber_server_port type="integer">5222</jabber_port>
  <jabber_conference_service>conference.test.server.com</jabber_conference_service>
  <jabber_chat_room_id>mingle.test_project.1256718933.104</jabber_chat_room_id>
  <jabber_chat_room_status>Ok</jabber_chat_room_status>
</murmurs_channel>

Help documentation