The hiplog program archives HipChat
private chats to data files on local disk. Both the chat content and any
uploaded files or images are archived. One example of why you might wish
to do this is if a co-worker is about to leave your company, but you
wish to archive your chats with them before their HipChat account is
shut down.
Get an HipChat API personal access token with View Messages privileges:
Install the hiplog program into any directory in your $PATH. You
will need any version of Ruby, and the json RubyGem.
$ cp hiplog ~/bin
Archive chats with co-workers Alice and Bob into JSON files in directory
hiplogs/alice and hiplogs/bob, respectively:
$ hiplog -t $access_token alice@example.com bob@example.com
hiplog uses the HipChat v2 API
to connect to HipChat and download chat content and uploaded files or
images to JSON data files on local disk. By default, it will try to
download all available private chat history with a particular user,
back to the beginning of when the two of you began chatting.
The supported mechanism for
exporting chat history
from HipChat requires administrative access. In contrast, hiplog uses a
personal API access token.
This means that administrative access is not required, but it also means
that only private chats which are still accessible to your regular
HipChat mobile or desktop client can be archived. You cannot, for
example, get chat history for someone whose account has been deleted,
or get chat history for a user other than yourself.
To use hiplog, you will need to
generate a personal API access token.
Log in using your usual HipChat credentials, then create a new access
token with at least View Messages privileges.
An access token is typically a 40-character alphanumeric string. Pass
the access token to hiplog using any of the following mechanisms, in
order of descending precedence:
- Pass via command line with the
-t(--token) option - Set as value of a
HIPCHAT_ACCESS_TOKENenvironment variable - Save it to the file
~/.hipchat_access_token
Note that your access token is as good as a password, so you may wish to
secure it accordingly (for example, by keeping restrictive permissions
on your .hipchat_access_token file).
hiplog requires Ruby, but any version should work—it has been tested
with versions from REE (Ruby 1.8.7) to Ruby 2.2.4. The only dependency
which might not be already present in the Ruby standard library is the
json RubyGem. You can install this the normal way:
$ gem install json
Or, you can install it with Bundler:
$ bundle install
To run hiplog, just copy it to any directory in your $PATH. Or, just
directly run hiplog from wherever you saved it.
hiplog recognizes the following command line options:
-
-h,--helpDisplay command line help, then exit.
-
-v,--verboseWhile running, print URLs and output filenames to stderr. The default is to run silently unless there is an error.
-
-t,--tokenUse this HipChat API access token. The default is to try to read an access token from the
HIPCHAT_ACCESS_TOKENenvironment variable, or the file~/.hipchat_access_token, respectively. -
-d,--output-dirWrite logs into subdirectories of this output directory. The default is a
hiplogsdirectory in the current directory. The output directory will be created if it does not already exist.
Any other non-option arguments to hiplog are assumed to be HipChat
user IDs (which may be usernames, like alice@example.com, or numeric
user IDs, obtained via your own HipChat API calls.
By default, hiplog will save chat history to the directory hiplogs
in the current directory. If that directory does not exist, it will be
created with default permissions. Logs will be saved to directories
underneath it named by username, then in JSON files named by the date
of the earliest item in that file:
hiplogs
├──alice@example.com
│ ├──20140919T014318.json
│ └──20151013T205334.json
└──bob@example.com
├──20150324T230614.json
├──20150324T230902.json
├──20150812T215405.json
├──20151005T220915.json
├──ZajifYh5KDgxtmS9i38K1A.upload.png
└──AlMb_11bTp24W1vY6z-8mA.IMG_0729.JPG
The datestamped JSON files contain chat logs. Attachments are saved with the UUID from their original message, encoded via Base64 for URLs, and with their original filenames appended.
hiplog will return zero on success, non-zero with the number of errors
recorded if there are errors.
Andrew Ho (andrew@zeuscat.com)
HipChat is a trademark of Atlassian Pty Ltd, and the use of that name in this documentation does not imply any affiliation with or endorsement by Atlassian Pty Ltd. The files in this repository are authored by Andrew Ho and are covered by the following 3-clause BSD license:
Copyright (c) 2016, Andrew Ho.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
Neither the name of the author nor the names of its contributors may
be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.