cl-hipchat is a HipChat API wrapper client library for Common Lisp. With it you may manage HipChat rooms, read the chat history, send messages publicly and privately, share files, and so on.

State: Usable but not complete. Breaking changes may occur!

In this example we retrieve the list of all available rooms and echo the most recent message in one of them.

(let* ((room (car (hipchat:get-all-rooms)))
       (room-id (hipchat:room-id room))
       (message (car (hipchat:recent-room-history room-id 
                                                  :max 1))))
  (hipchat:send-notification room-id 
                             (hipchat:message-text message) 
                             :from "Echo bot" 
                             :color :random))

Notice that hipchat exists as a nickname (alias) for cl-hipchat.

You will not found cl-hipchat in QuickLisp yet, but it you clone this repo into your QuickLisp local-projects folder it does not matter. Load it like this:

(ql:quickload :cl-hipchat)

Before you can make any API requests you need to set the access token. You can find information about HipChat's access tokens here, but the simplest way to get started is to use your personal access token.

Once you have obtained a token, you may set it globaly like this:

(setf hipchat.config:*AUTH-TOKEN* "your-token-value")

.. or use let to create a dynamic binding scope.

(let ((hipchat.config:*AUTH-TOKEN* "your-token-value"))
  ;; Do your API calls here...
  )

An API function call is a success as long as the call returns a value other than nil.

Data will be returned as association lists.

Some exceptional situations may signal an error condition.

get-room (room-id-or-name)
Gets the details for a room.
HipChat API detials..

get-all-rooms (&key (start 0) (max 100) (include-private t) include-archived)
Get all rooms, optionally including private and archived rooms. Results are paged, and max returned rooms per request should be between 0 and 1000 (defaults to 100).
HipChat API detials..

create-room (name &key guest-access owner-user-id (privacy :public) (topic ""))
Creates a new room. Only the name parameter (length between 1 and 50) is required.
HipChat API detials..

delete-room (room-id-or-name)
Delete a room.
HipChat API detials..

set-topic (room-id-or-name topic)
Set a room's topic.
HipChat API detials..

get-user (name)

get-all-users (&key (start 0) (max 100) include-guests include-deleted)

send-notification (room-id-or-name message &key (from "") (color :yellow) notify (message-format :html))
HipChat API detials..

send-message (room-id-or-name message)
HipChat API detials..

send-private-message (user message &key notify (message-format :text))
HipChat API detials..

share-file-with-room (room filepath &optional message)
HipChat API detials..

share-link-with-room (room-id-or-name link &optional (message ""))
HipChat API detials..

room-history (room &key (date "recent") (timezone "UTC") (start 0) (max 100) (reverse t))
HipChat API detials..

recent-room-history (room &key not-before (timezone "UTC") (max 100) (include-deleted t))
HipChat API detials..