├── LICENSE ├── README.md ├── hipchat_room_message └── tutorial ├── README.md └── image ├── 01-frontpage.png ├── 02-editing-profile.png ├── 04-create-key.png ├── 05-created-key.png ├── 06-rooms-list.png ├── 07-room-details.png ├── 08-hello.png ├── 09-amiss.png ├── 10-fortune.png └── 11-inline-markup.png /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) HipChat, Inc. 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining 4 | a copy of this software and associated documentation files (the 5 | "Software"), to deal in the Software without restriction, including 6 | without limitation the rights to use, copy, modify, merge, publish, 7 | distribute, sublicense, and/or sell copies of the Software, and to 8 | permit persons to whom the Software is furnished to do so, subject to 9 | the following conditions: 10 | 11 | The above copyright notice and this permission notice shall be 12 | included in all copies or substantial portions of the Software. 13 | 14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 15 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 16 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 17 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 18 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 19 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 20 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | hipchat-cli 2 | =========== 3 | 4 | Some command line scripts for performing [HipChat][hc] API calls. 5 | For details on how to obtain a token and room id, see 6 | [the tutorial](tutorial/README.md). 7 | 8 | ./hipchat\_room\_message 9 | ----- 10 | Used to send a message to a room. 11 | 12 | ```bash 13 | $ cat message.txt | ./hipchat_room_message -t -r -f "System" 14 | ``` 15 | 16 | [hc]: http://www.hipchat.com 17 | 18 | Configuration 19 | ----- 20 | 21 | hipchat-cli can be configured with one of the following options in a combination of those. 22 | 23 | * Command-line options 24 | * Environment variables 25 | * Configuration file 26 | 27 | ### Command-line options 28 | 29 | Command-line options are passed into hipchat-cli. A list of options is available by executing ```hipchat_room_message -h```. 30 | ``` 31 | $ ./hipchat_room_message -h 32 | Usage: ./hipchat_room_message -t -r -f 33 | 34 | This script will read from stdin and send the contents to the given room as 35 | a system message. Or use -i message. 36 | 37 | OPTIONS: 38 | -h Show this message 39 | -t API token 40 | -r Room ID 41 | -f From name (optional in v2 API) 42 | -c Message color (yellow, red, green, purple, gray 43 | or random - default: yellow) 44 | -m Message format (html or text - default: html) 45 | -i Optional: Input to send to room (default: stdin) 46 | -l Nagios message level (critical, warning, unknown, 47 | ok, down, up). Will override color. 48 | -n Trigger notification for people in the room 49 | -o API host (api.hipchat.com) 50 | -v API version (default: v1) 51 | -k Allow curl to make insecure SSL connections 52 | ``` 53 | 54 | #### Usage example: 55 | ```bash 56 | $ ./hipchat_room_message -vv2 -t -r -i "This is a message" 57 | ``` 58 | 59 | ### Environment variables 60 | 61 | All options available as command-line options can be passed in as environment variables. 62 | 63 | Environment variable | Description 64 | -------------------- | ----------- 65 | HIPCHAT_TOKEN | API token 66 | HIPCHAT_ROOM_ID | Room ID 67 | HIPCHAT_FROM | From name 68 | HIPCHAT_COLOR | Message color (yellow, red, green, purple, gray or random - default: yellow) 69 | HIPCHAT_FORMAT | Message format (html or text - default: html) 70 | HIPCHAT_NOTIFY | Trigger notification for people in the room (default: 0) 71 | HIPCHAT_HOST | API host (default: api.hipchat.com) 72 | HIPCHAT_LEVEL | Message Level (targetting Nagios states, critical, warning, unknown, ok) 73 | HIPCHAT_API | API version (default: v1) 74 | 75 | #### Usage example: 76 | ```bash 77 | $ cat message.txt | HIPCHAT_TOKEN= HIPCHAT_ROOM_ID=1234 ./hipchat_room_message -f "System" 78 | ``` 79 | 80 | ### Configuration file 81 | 82 | All environment variables can be specified in a configuration file. The configuration file is ```/etc/hipchat```. 83 | 84 | #### Usage example: 85 | 86 | Configuration in ```/etc/hipchat```: 87 | ```bash 88 | HIPCHAT_TOKEN= 89 | HIPCHAT_ROOM_ID=1234 90 | ``` 91 | 92 | Command-line: 93 | ```bash 94 | $ cat message.txt | HIPCHAT_FROM="System" ./hipchat_room_message -c green 95 | ``` 96 | -------------------------------------------------------------------------------- /hipchat_room_message: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ############################################################################### 4 | # 5 | # ./hipchat_room_message 6 | # 7 | # A script for sending a system message to a room. 8 | # 9 | # Docs: http://github.com/hipchat/hipchat-cli 10 | # 11 | # Usage: 12 | # cat message.txt | ./hipchat_room_message -t -r 1234 -f "System" 13 | # echo -e "New\nline" | ./hipchat_room_message -t -r 1234 -f "System" 14 | # 15 | ############################################################################### 16 | 17 | # exit on failure 18 | set -e 19 | # http://apple.stackexchange.com/questions/68684/why-sh-c-echo-n-1-is-different-from-bash-c-echo-n-1 20 | shopt -u xpg_echo 21 | 22 | usage() { 23 | cat << EOF 24 | Usage: $0 -t -r -f 25 | 26 | This script will read from stdin and send the contents to the given room as 27 | a system message. Or use -i message. 28 | 29 | OPTIONS: 30 | -h Show this message 31 | -t API token 32 | -r Room ID 33 | -f From name (optional in v2 API) 34 | -c Message color (yellow, red, green, purple, gray 35 | or random - default: yellow) 36 | -m Message format (html or text - default: html) 37 | -i Optional: Input to send to room (default: stdin) 38 | -l Nagios message level (critical, warning, unknown, 39 | ok, down, up). Will override color. 40 | -n Trigger notification for people in the room 41 | -o API host (api.hipchat.com) 42 | -v API version (default: v1) 43 | -k Allow curl to make insecure SSL connections 44 | EOF 45 | } 46 | 47 | # Include hipchat defaults if available 48 | test -f /etc/hipchat && . /etc/hipchat 49 | test -f ~/.hipchat && . ~/.hipchat 50 | 51 | TOKEN=${HIPCHAT_TOKEN:-} 52 | ROOM_ID=${HIPCHAT_ROOM_ID:-} 53 | FROM=${HIPCHAT_FROM:-} 54 | COLOR=${HIPCHAT_COLOR:-yellow} 55 | FORMAT=${HIPCHAT_FORMAT:-html} 56 | MESSAGE=${HIPCHAT_MESSAGE:-html} 57 | NOTIFY=${HIPCHAT_NOTIFY:-0} 58 | HOST=${HIPCHAT_HOST:-api.hipchat.com} 59 | LEVEL=${HIPCHAT_LEVEL:-} 60 | API=${HIPCHAT_API:-v1} 61 | ALLOW_INSECURE=false 62 | 63 | while getopts "ht:r:f:c:m:o:i:l:v:nk" OPTION; do 64 | case $OPTION in 65 | h) usage; exit 1;; 66 | t) TOKEN=$OPTARG;; 67 | r) ROOM_ID=$OPTARG;; 68 | f) FROM=$OPTARG;; 69 | c) COLOR=$OPTARG;; 70 | m) FORMAT=$OPTARG;; 71 | n) NOTIFY=1;; 72 | i) INPUT=$OPTARG;; 73 | l) LEVEL=$OPTARG;; 74 | o) HOST=$OPTARG;; 75 | v) API=$OPTARG;; 76 | k) ALLOW_INSECURE=true;; 77 | [?]) usage; exit;; 78 | esac 79 | done 80 | 81 | # check for required args 82 | if [[ -z $TOKEN ]] || [[ -z $ROOM_ID ]] || [[ -z $FROM && $API = "v1" ]]; then 83 | if [[ -z $TOKEN ]]; then 84 | echo "$(basename $0): missing TOKEN" 85 | fi 86 | if [[ -z $ROOM_ID ]]; then 87 | echo "$(basename $0): missing ROOM_ID" 88 | fi 89 | if [[ -z $FROM && $API = "v1" ]]; then 90 | echo "$(basename $0): missing FROM" 91 | fi 92 | usage 93 | exit 1 94 | fi 95 | 96 | # nagios levels 97 | if [ ! -z "$LEVEL" ]; then 98 | if [[ $LEVEL == 'CRITICAL' ]] || [[ $LEVEL == 'critical' ]]; then 99 | COLOR="red"; 100 | elif [[ $LEVEL == 'WARNING' ]] || [[ $LEVEL == 'warning' ]]; then 101 | COLOR="yellow"; 102 | elif [[ $LEVEL == 'UNKNOWN' ]] || [[ $LEVEL == 'unknown' ]]; then 103 | COLOR="gray"; 104 | elif [[ $LEVEL == 'OK' ]] || [[ $LEVEL == 'ok' ]]; then 105 | COLOR="green"; 106 | elif [[ $LEVEL == 'DOWN' ]] || [[ $LEVEL == 'down' ]]; then 107 | COLOR="red"; 108 | elif [[ $LEVEL == 'UP' ]] || [[ $LEVEL == 'up' ]]; then 109 | COLOR="green"; 110 | fi 111 | fi 112 | 113 | if [ -z "$INPUT" ]; then 114 | # read stdin 115 | INPUT=$(cat) 116 | fi 117 | 118 | # replace newlines with XHTML
119 | if [ $FORMAT == 'html' ]; then 120 | INPUT=$(echo -n "${INPUT}" | perl -p -e 's/\n/
/') 121 | fi 122 | 123 | # replace bare URLs with real hyperlinks 124 | INPUT=$(echo -n "${INPUT}" | perl -p -e "s/(?\1\<\/a>/g") 125 | 126 | # urlencode with perl 127 | if [ $API == 'v1' ]; then 128 | INPUT=$(echo -n "${INPUT}" | perl -p -e 's/([^A-Za-z0-9])/sprintf("%%%02X", ord($1))/seg') 129 | fi 130 | 131 | # escape special characters in json 132 | if [ $API == 'v2' ]; then 133 | INPUT=$(echo -n "${INPUT}" | sed 's/\\/\\\\/g' | sed 's/"/\\\"/g') 134 | fi 135 | 136 | # replace notification boolean from 1/0 to 'true'/'false' for API v2 137 | if [ $API == 'v2' ]; then 138 | if [ $NOTIFY -eq 0 ]; then 139 | NOTIFY='false' 140 | else 141 | NOTIFY='true' 142 | fi 143 | fi 144 | 145 | curl_opts="-sS" 146 | if [ $ALLOW_INSECURE == true ]; then 147 | curl_opts+=" --insecure" 148 | fi 149 | 150 | # do the curl, using a temporary filename 151 | # (stored in BODY) to avoid long URL errors 152 | BODY=`mktemp` 153 | 154 | if [ $API == 'v2' ]; then 155 | (echo "{\"color\":\"$COLOR\", " 156 | 157 | if [[ -n "$FROM" ]] ; then 158 | echo "\"from\": \"$FROM\", " 159 | fi 160 | echo "\"message\":\"$INPUT\", \"message_format\":\"$FORMAT\", \"notify\":$NOTIFY}" 161 | ) > $BODY 162 | curl ${curl_opts} \ 163 | -H 'Content-type: application/json' \ 164 | -H "Authorization: Bearer $TOKEN" \ 165 | -d @$BODY \ 166 | https://$HOST/v2/room/$ROOM_ID/notification 167 | else 168 | echo "auth_token=$TOKEN&room_id=$ROOM_ID&from=$FROM&color=$COLOR&message_format=$FORMAT&message=$INPUT¬ify=$NOTIFY" > $BODY 169 | curl ${curl_opts} \ 170 | -d @$BODY \ 171 | https://$HOST/v1/rooms/message 172 | fi 173 | 174 | rm -f $BODY 175 | -------------------------------------------------------------------------------- /tutorial/README.md: -------------------------------------------------------------------------------- 1 | Tutorial 2 | ======== 3 | 4 | Here is a step-by-step tutorial on how to use this command-line 5 | tool to integration with [HipChat][hc]. This tutorial only 6 | describes `v2` access. 7 | 8 | * [Obtaining an Access Token](#obtaining-an-access-token) 9 | * [Obtaining a Room API ID](#obtaining-a-room-api-id) 10 | * [Sending Messages](#sending-messages) 11 | * [Getting Fancy](#getting-fancy) 12 | * [Color](#color) 13 | * [From](#from) 14 | * [Inline Markup](#inline-markup) 15 | 16 | ## Obtaining an Access Token 17 | 18 | In order to talk to the hipchat servers, you will require an access 19 | token. This is easily obtained from your profile. 20 | 21 | Log in to your site's home page, http://_site_.hipchat.com 22 | 23 | ![HipChat Home Page](image/01-frontpage.png) 24 | 25 | From the home page, click on the Edit Profile button. You may need to 26 | re-authenticate, but that should bring up your profile page: 27 | 28 | ![Profile Page](image/02-editing-profile.png) 29 | 30 | There, on the left menu is a panel for **API access**. Click 31 | that to bring up the API access management page: 32 | 33 | ![API Access Page](image/04-create-key.png) 34 | 35 | At the bottom of that page is a **Create new token** section; 36 | select the scopes you want (for normal posting of messages 37 | to a room, all you need is the _Send Notification_ scope). 38 | Give the token a label so you can remember later why you created 39 | it, and click **Create**. 40 | That should update the page to include the new token: 41 | 42 | ![New Token Display](image/05-created-key.png) 43 | 44 | The Personal token is the one you want. Save it off for later use. 45 | 46 | ## Obtaining a Room API ID 47 | 48 | Now you need to figure out the room ID. Click on the **Rooms** 49 | tab in the admin page. 50 | 51 | ![Rooms Listing](image/06-rooms-list.png) 52 | 53 | You can search for the room or rooms you are interested; in this case 54 | I only have a few. Click on the name of the room of interest to get 55 | its details: 56 | 57 | ![Room Details](image/07-room-details.png) 58 | 59 | The room details page includes the **API ID** of the room, which is 60 | what you will use in the CLI to send messages to that room. 61 | 62 | ## Sending Messages 63 | 64 | Now you have all the information needed to send messages. (Note that 65 | the API keys obtained in the first step are is only for v2 of the API, 66 | be sure to include the HIPCHAT_API settting) 67 | 68 | export HIPCHAT_TOKEN=jPn....Pq8 69 | export HIPCHAT_ROOM_ID=32...8 70 | export HIPCHAT_API=v2 71 | echo Hello | ./hipchat_room_message 72 | 73 | Congratulations! That should have sent a message to your room. 74 | 75 | Also, if you like, you can configure these variables in a `~/.hipchat 76 | file, which will be sourced by the command-line tool. 77 | 78 | ![Hello Message](image/08-hello.png) 79 | 80 | ### Getting Fancy 81 | 82 | There are several options that can be used to make your messages 83 | a little fancier. 84 | 85 | #### Color 86 | 87 | The `-c` option sets the background color of the message: 88 | 89 | ./hipchat_room_message -c red -i "Something is amiss" 90 | 91 | ![Amiss Message](image/09-amiss.png) 92 | 93 | #### From 94 | 95 | You can use the **from** option (`-f`) to mark your message as 96 | being from a particular place. 97 | 98 | echo Work with your destiny. Stop trying to outrun it. | \ 99 | ./hipchat_room_message -c green -f "Fortune Cookie" 100 | 101 | ![Fortune Cookie Message](image/10-fortune.png) 102 | 103 | #### Inline Markup 104 | 105 | And, the message body supports HTML-style inline markup. 106 | 107 | echo 'Scorpio: Carpe diem!' | \ 108 | ./hipchat_room_message -c green -f "Fortune Cookie" 109 | 110 | ![Inline Markup](image/11-inline-markup.png) 111 | 112 | [hc]: http://www.hipchat.com 113 | -------------------------------------------------------------------------------- /tutorial/image/01-frontpage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hipchat/hipchat-cli/aa3a932da94d4946574bcbd91eff5c8a2d4eb4cc/tutorial/image/01-frontpage.png -------------------------------------------------------------------------------- /tutorial/image/02-editing-profile.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hipchat/hipchat-cli/aa3a932da94d4946574bcbd91eff5c8a2d4eb4cc/tutorial/image/02-editing-profile.png -------------------------------------------------------------------------------- /tutorial/image/04-create-key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hipchat/hipchat-cli/aa3a932da94d4946574bcbd91eff5c8a2d4eb4cc/tutorial/image/04-create-key.png -------------------------------------------------------------------------------- /tutorial/image/05-created-key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hipchat/hipchat-cli/aa3a932da94d4946574bcbd91eff5c8a2d4eb4cc/tutorial/image/05-created-key.png -------------------------------------------------------------------------------- /tutorial/image/06-rooms-list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hipchat/hipchat-cli/aa3a932da94d4946574bcbd91eff5c8a2d4eb4cc/tutorial/image/06-rooms-list.png -------------------------------------------------------------------------------- /tutorial/image/07-room-details.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hipchat/hipchat-cli/aa3a932da94d4946574bcbd91eff5c8a2d4eb4cc/tutorial/image/07-room-details.png -------------------------------------------------------------------------------- /tutorial/image/08-hello.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hipchat/hipchat-cli/aa3a932da94d4946574bcbd91eff5c8a2d4eb4cc/tutorial/image/08-hello.png -------------------------------------------------------------------------------- /tutorial/image/09-amiss.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hipchat/hipchat-cli/aa3a932da94d4946574bcbd91eff5c8a2d4eb4cc/tutorial/image/09-amiss.png -------------------------------------------------------------------------------- /tutorial/image/10-fortune.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hipchat/hipchat-cli/aa3a932da94d4946574bcbd91eff5c8a2d4eb4cc/tutorial/image/10-fortune.png -------------------------------------------------------------------------------- /tutorial/image/11-inline-markup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hipchat/hipchat-cli/aa3a932da94d4946574bcbd91eff5c8a2d4eb4cc/tutorial/image/11-inline-markup.png --------------------------------------------------------------------------------