Repository: hipchat/hipchat-cli Branch: master Commit: aa3a932da94d Files: 4 Total size: 12.1 KB Directory structure: gitextract_3no6fb00/ ├── LICENSE ├── README.md ├── hipchat_room_message └── tutorial/ └── README.md ================================================ FILE CONTENTS ================================================ ================================================ FILE: LICENSE ================================================ Copyright (c) HipChat, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ hipchat-cli =========== Some command line scripts for performing [HipChat][hc] API calls. For details on how to obtain a token and room id, see [the tutorial](tutorial/README.md). ./hipchat\_room\_message ----- Used to send a message to a room. ```bash $ cat message.txt | ./hipchat_room_message -t -r -f "System" ``` [hc]: http://www.hipchat.com Configuration ----- hipchat-cli can be configured with one of the following options in a combination of those. * Command-line options * Environment variables * Configuration file ### Command-line options Command-line options are passed into hipchat-cli. A list of options is available by executing ```hipchat_room_message -h```. ``` $ ./hipchat_room_message -h Usage: ./hipchat_room_message -t -r -f This script will read from stdin and send the contents to the given room as a system message. Or use -i message. OPTIONS: -h Show this message -t API token -r Room ID -f From name (optional in v2 API) -c Message color (yellow, red, green, purple, gray or random - default: yellow) -m Message format (html or text - default: html) -i Optional: Input to send to room (default: stdin) -l Nagios message level (critical, warning, unknown, ok, down, up). Will override color. -n Trigger notification for people in the room -o API host (api.hipchat.com) -v API version (default: v1) -k Allow curl to make insecure SSL connections ``` #### Usage example: ```bash $ ./hipchat_room_message -vv2 -t -r -i "This is a message" ``` ### Environment variables All options available as command-line options can be passed in as environment variables. Environment variable | Description -------------------- | ----------- HIPCHAT_TOKEN | API token HIPCHAT_ROOM_ID | Room ID HIPCHAT_FROM | From name HIPCHAT_COLOR | Message color (yellow, red, green, purple, gray or random - default: yellow) HIPCHAT_FORMAT | Message format (html or text - default: html) HIPCHAT_NOTIFY | Trigger notification for people in the room (default: 0) HIPCHAT_HOST | API host (default: api.hipchat.com) HIPCHAT_LEVEL | Message Level (targetting Nagios states, critical, warning, unknown, ok) HIPCHAT_API | API version (default: v1) #### Usage example: ```bash $ cat message.txt | HIPCHAT_TOKEN= HIPCHAT_ROOM_ID=1234 ./hipchat_room_message -f "System" ``` ### Configuration file All environment variables can be specified in a configuration file. The configuration file is ```/etc/hipchat```. #### Usage example: Configuration in ```/etc/hipchat```: ```bash HIPCHAT_TOKEN= HIPCHAT_ROOM_ID=1234 ``` Command-line: ```bash $ cat message.txt | HIPCHAT_FROM="System" ./hipchat_room_message -c green ``` ================================================ FILE: hipchat_room_message ================================================ #!/usr/bin/env bash ############################################################################### # # ./hipchat_room_message # # A script for sending a system message to a room. # # Docs: http://github.com/hipchat/hipchat-cli # # Usage: # cat message.txt | ./hipchat_room_message -t -r 1234 -f "System" # echo -e "New\nline" | ./hipchat_room_message -t -r 1234 -f "System" # ############################################################################### # exit on failure set -e # http://apple.stackexchange.com/questions/68684/why-sh-c-echo-n-1-is-different-from-bash-c-echo-n-1 shopt -u xpg_echo usage() { cat << EOF Usage: $0 -t -r -f This script will read from stdin and send the contents to the given room as a system message. Or use -i message. OPTIONS: -h Show this message -t API token -r Room ID -f From name (optional in v2 API) -c Message color (yellow, red, green, purple, gray or random - default: yellow) -m Message format (html or text - default: html) -i Optional: Input to send to room (default: stdin) -l Nagios message level (critical, warning, unknown, ok, down, up). Will override color. -n Trigger notification for people in the room -o API host (api.hipchat.com) -v API version (default: v1) -k Allow curl to make insecure SSL connections EOF } # Include hipchat defaults if available test -f /etc/hipchat && . /etc/hipchat test -f ~/.hipchat && . ~/.hipchat TOKEN=${HIPCHAT_TOKEN:-} ROOM_ID=${HIPCHAT_ROOM_ID:-} FROM=${HIPCHAT_FROM:-} COLOR=${HIPCHAT_COLOR:-yellow} FORMAT=${HIPCHAT_FORMAT:-html} MESSAGE=${HIPCHAT_MESSAGE:-html} NOTIFY=${HIPCHAT_NOTIFY:-0} HOST=${HIPCHAT_HOST:-api.hipchat.com} LEVEL=${HIPCHAT_LEVEL:-} API=${HIPCHAT_API:-v1} ALLOW_INSECURE=false while getopts "ht:r:f:c:m:o:i:l:v:nk" OPTION; do case $OPTION in h) usage; exit 1;; t) TOKEN=$OPTARG;; r) ROOM_ID=$OPTARG;; f) FROM=$OPTARG;; c) COLOR=$OPTARG;; m) FORMAT=$OPTARG;; n) NOTIFY=1;; i) INPUT=$OPTARG;; l) LEVEL=$OPTARG;; o) HOST=$OPTARG;; v) API=$OPTARG;; k) ALLOW_INSECURE=true;; [?]) usage; exit;; esac done # check for required args if [[ -z $TOKEN ]] || [[ -z $ROOM_ID ]] || [[ -z $FROM && $API = "v1" ]]; then if [[ -z $TOKEN ]]; then echo "$(basename $0): missing TOKEN" fi if [[ -z $ROOM_ID ]]; then echo "$(basename $0): missing ROOM_ID" fi if [[ -z $FROM && $API = "v1" ]]; then echo "$(basename $0): missing FROM" fi usage exit 1 fi # nagios levels if [ ! -z "$LEVEL" ]; then if [[ $LEVEL == 'CRITICAL' ]] || [[ $LEVEL == 'critical' ]]; then COLOR="red"; elif [[ $LEVEL == 'WARNING' ]] || [[ $LEVEL == 'warning' ]]; then COLOR="yellow"; elif [[ $LEVEL == 'UNKNOWN' ]] || [[ $LEVEL == 'unknown' ]]; then COLOR="gray"; elif [[ $LEVEL == 'OK' ]] || [[ $LEVEL == 'ok' ]]; then COLOR="green"; elif [[ $LEVEL == 'DOWN' ]] || [[ $LEVEL == 'down' ]]; then COLOR="red"; elif [[ $LEVEL == 'UP' ]] || [[ $LEVEL == 'up' ]]; then COLOR="green"; fi fi if [ -z "$INPUT" ]; then # read stdin INPUT=$(cat) fi # replace newlines with XHTML
if [ $FORMAT == 'html' ]; then INPUT=$(echo -n "${INPUT}" | perl -p -e 's/\n/
/') fi # replace bare URLs with real hyperlinks INPUT=$(echo -n "${INPUT}" | perl -p -e "s/(?\1\<\/a>/g") # urlencode with perl if [ $API == 'v1' ]; then INPUT=$(echo -n "${INPUT}" | perl -p -e 's/([^A-Za-z0-9])/sprintf("%%%02X", ord($1))/seg') fi # escape special characters in json if [ $API == 'v2' ]; then INPUT=$(echo -n "${INPUT}" | sed 's/\\/\\\\/g' | sed 's/"/\\\"/g') fi # replace notification boolean from 1/0 to 'true'/'false' for API v2 if [ $API == 'v2' ]; then if [ $NOTIFY -eq 0 ]; then NOTIFY='false' else NOTIFY='true' fi fi curl_opts="-sS" if [ $ALLOW_INSECURE == true ]; then curl_opts+=" --insecure" fi # do the curl, using a temporary filename # (stored in BODY) to avoid long URL errors BODY=`mktemp` if [ $API == 'v2' ]; then (echo "{\"color\":\"$COLOR\", " if [[ -n "$FROM" ]] ; then echo "\"from\": \"$FROM\", " fi echo "\"message\":\"$INPUT\", \"message_format\":\"$FORMAT\", \"notify\":$NOTIFY}" ) > $BODY curl ${curl_opts} \ -H 'Content-type: application/json' \ -H "Authorization: Bearer $TOKEN" \ -d @$BODY \ https://$HOST/v2/room/$ROOM_ID/notification else echo "auth_token=$TOKEN&room_id=$ROOM_ID&from=$FROM&color=$COLOR&message_format=$FORMAT&message=$INPUT¬ify=$NOTIFY" > $BODY curl ${curl_opts} \ -d @$BODY \ https://$HOST/v1/rooms/message fi rm -f $BODY ================================================ FILE: tutorial/README.md ================================================ Tutorial ======== Here is a step-by-step tutorial on how to use this command-line tool to integration with [HipChat][hc]. This tutorial only describes `v2` access. * [Obtaining an Access Token](#obtaining-an-access-token) * [Obtaining a Room API ID](#obtaining-a-room-api-id) * [Sending Messages](#sending-messages) * [Getting Fancy](#getting-fancy) * [Color](#color) * [From](#from) * [Inline Markup](#inline-markup) ## Obtaining an Access Token In order to talk to the hipchat servers, you will require an access token. This is easily obtained from your profile. Log in to your site's home page, http://_site_.hipchat.com ![HipChat Home Page](image/01-frontpage.png) From the home page, click on the Edit Profile button. You may need to re-authenticate, but that should bring up your profile page: ![Profile Page](image/02-editing-profile.png) There, on the left menu is a panel for **API access**. Click that to bring up the API access management page: ![API Access Page](image/04-create-key.png) At the bottom of that page is a **Create new token** section; select the scopes you want (for normal posting of messages to a room, all you need is the _Send Notification_ scope). Give the token a label so you can remember later why you created it, and click **Create**. That should update the page to include the new token: ![New Token Display](image/05-created-key.png) The Personal token is the one you want. Save it off for later use. ## Obtaining a Room API ID Now you need to figure out the room ID. Click on the **Rooms** tab in the admin page. ![Rooms Listing](image/06-rooms-list.png) You can search for the room or rooms you are interested; in this case I only have a few. Click on the name of the room of interest to get its details: ![Room Details](image/07-room-details.png) The room details page includes the **API ID** of the room, which is what you will use in the CLI to send messages to that room. ## Sending Messages Now you have all the information needed to send messages. (Note that the API keys obtained in the first step are is only for v2 of the API, be sure to include the HIPCHAT_API settting) export HIPCHAT_TOKEN=jPn....Pq8 export HIPCHAT_ROOM_ID=32...8 export HIPCHAT_API=v2 echo Hello | ./hipchat_room_message Congratulations! That should have sent a message to your room. Also, if you like, you can configure these variables in a `~/.hipchat file, which will be sourced by the command-line tool. ![Hello Message](image/08-hello.png) ### Getting Fancy There are several options that can be used to make your messages a little fancier. #### Color The `-c` option sets the background color of the message: ./hipchat_room_message -c red -i "Something is amiss" ![Amiss Message](image/09-amiss.png) #### From You can use the **from** option (`-f`) to mark your message as being from a particular place. echo Work with your destiny. Stop trying to outrun it. | \ ./hipchat_room_message -c green -f "Fortune Cookie" ![Fortune Cookie Message](image/10-fortune.png) #### Inline Markup And, the message body supports HTML-style inline markup. echo 'Scorpio: Carpe diem!' | \ ./hipchat_room_message -c green -f "Fortune Cookie" ![Inline Markup](image/11-inline-markup.png) [hc]: http://www.hipchat.com