->Ruby hacker? Download the official jaconda gem.<-

You can easily send notifications from your systems to Jaconda rooms.

Requests

All notifications will be made against the domain that your account is accessed from. For instance, if you want to send a notification to the support room of bigbang account, you should make an authenticated POST request to https://bigbang.jaconda.im/api/v2/rooms/support/notify.xml.

Authentication

Each room has it's own Room token, which you can find on the Integrations page of the room. To send notifications, you should use this Room token and not the API token of your user in Jaconda.

The preferred method of authentication is HTTP Basic Authentication with Room token as the username, and "X" (or some otherwise bogus text) as the password. The second form of authentication is appending a _token parameter to your requests.

Parameters

Parameters can be transmitted in 3 ways: plain text, xml and json. For xml and json requests, you should specify appropriate Content-Type header. Regardless the format, parameters should be encapsulated in the message array.

• text Required. The text of the message. The value must pass xhtml validation. Allowed tags are: a, br, em, b, i, span. All other tags will be removed. Don't forget to escape special characters.
• sender_name Optional. The name of the sender. Can be anything, defaulted to the api.

Example with plain parameters and HTTP auth:

$ curl -u room_token:x -d 'message[text]=Hello from api' https://bigbang.jaconda.im/api/v2/rooms/support/notify.xml

Example with xml as a body and parameter auth:

$ curl -u -H 'Content-Type: application/xml' -d '<message><sender-name>Build Server</sender-name><text>Build succeeded</text></message>' https://bigbang.jaconda.im/api/v2/rooms/support/notify.xml?_token=room_token

Example with json as a body:

$ curl -u room_token:x -H 'Content-Type: application/json' -d '{"message": {"text": "Hello with json"}}' https://bigbang.jaconda.im/api/v2/rooms/support/notify.xml

Note that responses in above examples will be in xml, because url is followed by .xml

Responses

Success responses

The server will respond with 200 OK response if there is no errors. The response body will contain requested resource or resources.

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <created-at type="datetime">2011-02-25T16:49:15+05:00</created-at>
  <id type="integer">5304167</id>
  <kind>api</kind>
  <sender-id>127.0.0.1</sender-id>
  <sender-name>Build Server</sender-name>
  <text>Build succeeded</text>
  <updated-at type="datetime">2011-02-25T16:49:15+05:00</updated-at>
</message>

Failure responses

If request fails, the server will respond with failure code and message. There are several possible failure responses:
400 - the request can't be processed due to invalid format or auth type - supported response formats are XML and JSON, supported authentication methods are HTTP Basic and parameter-based
401 - unauthorized access - ensure that Room token is correct
404 - the requested resource cannot be found - ensure that Room ID is correct
422 - the submitted data was invalid - check the corresponding error messages
500 - unexpected errors - submit a bug report at http://help.jaconda.im

The response body for 422 failure will contain description of the error.
The XML response will have a root element "errors" with one or more "error" children, describing each error that occurred.
The JSON response will have array of one or more errors, describing each error that occurred.