hipchat

README

Hipchat

This project implements a Go client library for the Hipchat API (API version 2 is not supported).

Pull requests are welcome as the API is limited to only a few calls right now.

API documentation can be found on godoc.org.

Star this or get at me on the Twitters if you end up using this since this is pretty early stage and I may make breaking changes to the API. – @andybons

Installing

Run

go get github.com/andybons/hipchat

Example usage:

package main

import (
	"github.com/andybons/hipchat"
	"log"
)

func main() {
	c := hipchat.NewClient("<PUT YOUR AUTH TOKEN HERE>")
	req := hipchat.MessageRequest{
		RoomId:        "Rat Man's Den",
		From:          "GLaDOS",
		Message:       "Bad news: Combustible lemons failed.",
		Color:         hipchat.ColorPurple,
		MessageFormat: hipchat.FormatText,
		Notify:        true,
	}

	if err := c.PostMessage(req); err != nil {
		log.Printf("Expected no error, but got %q", err)
	}
}

Setting a custom HipChat Server:

c := hipchat.NewClient("<AUTH TOKEN>")
c.BaseURL = "https://your.host.name/v1"
...

Use customized proxy settings In case you need to use transport other than http.DefaultTransport:

c := hipchat.NewClient("<AUTH TOKEN>")

proxyURL, err := url.Parse("<PROXY_URL:PROXY_PORT>")
if err != nil {
	log.Fatalf("Expected no error, but got %q", err)
}
c.Transport = &http.Transport{Proxy: http.ProxyURL(proxyURL)}

Contributors

• Akshay Shah (@akshayjshah)
• Michael Biven (@michaelbiven)
• Tarrant Rollins (@tarrant)
• Edward Muller (@freeformz)
• Matt Blair (@mblair)
• Gordon Goetz (@gtosh4)
• Paras Patel (@patelparas)

Documentation

Overview

Package hipchat provides a client library for the Hipchat REST API.

Index

• Constants
• type AuthResponse
• type Client
  • func NewClient(authToken string) Client
  • func (c *Client) PostMessage(req MessageRequest) error
  • func (c *Client) RoomHistory(id, date, tz string) ([]Message, error)
  • func (c *Client) RoomList() ([]Room, error)
• type ErrorResponse
• type HipchatError
  • func (e HipchatError) Error() string
• type Message
  • func (m *Message) Time() (time.Time, error)
• type MessageRequest
• type Room

Constants

const (
	ColorYellow = "yellow"
	ColorRed    = "red"
	ColorGreen  = "green"
	ColorPurple = "purple"
	ColorGray   = "gray"
	ColorRandom = "random"

	FormatText = "text"
	FormatHTML = "html"

	ResponseStatusSent = "sent"
)

const (
	ISO8601 = "2006-01-02T15:04:05-0700"
)

Types

type AuthResponse

type AuthResponse struct {
	Success, Error *HipchatError
}

type Client

type Client struct {
	AuthToken string
	BaseURL   string
	Timeout   time.Duration
	Transport http.RoundTripper
}

func NewClient

func NewClient(authToken string) Client

NewClient allocates and returns a Client with the given authToken. By default, the client will use the publicly available HipChat servers. For internal or custom servers, set the BaseURL field of the Client.

func (*Client) PostMessage

func (c *Client) PostMessage(req MessageRequest) error

func (*Client) RoomHistory

func (c *Client) RoomHistory(id, date, tz string) ([]Message, error)

func (*Client) RoomList

func (c *Client) RoomList() ([]Room, error)

type ErrorResponse

type ErrorResponse struct {
	Error HipchatError
}

type HipchatError

type HipchatError struct {
	Code    int
	Type    string
	Message string
}

func (HipchatError) Error

func (e HipchatError) Error() string

type Message

type Message struct {
	// Date message was sent in ISO-8601 format in request timezone.
	ISODate string `json:"date"`

	// Name and user_id of sender. user_id will be "api" for API messages and "guest" for guest messages.
	From struct {
		Name   string
		UserId interface{} `json:"user_id"`
	}

	// Message body.
	Message string

	// Name, size, and URL of uploaded file.
	File struct {
		Name string
		Size int
		URL  string
	}
}

func (*Message) Time

func (m *Message) Time() (time.Time, error)

type MessageRequest

type MessageRequest struct {
	// Required. ID or name of the room.
	RoomId string

	// Required. Name the message will appear to be sent from. Must be less
	// than 15 characters long. May contain letters, numbers, -, _, and spaces.
	From string

	// Required. The message body. 10,000 characters max.
	Message string

	// Determines how the message is treated by our server and rendered
	// inside HipChat applications.
	// html - Message is rendered as HTML and receives no special treatment.
	// Must be valid HTML and entities must be escaped (e.g.: & instead of &).
	// May contain basic tags: a, b, i, strong, em, br, img, pre, code.
	// Special HipChat features such as @mentions, emoticons, and image previews
	// are NOT supported when using this format.
	// text - Message is treated just like a message sent by a user. Can include
	// @mentions, emoticons, pastes, and auto-detected URLs (Twitter, YouTube, images, etc).
	// (default: html)
	MessageFormat string

	// Whether or not this message should trigger a notification for people
	// in the room (change the tab color, play a sound, etc). Each recipient's
	// notification preferences are taken into account. 0 = false, 1 = true.
	// (default: 0)
	Notify bool

	// Background color for message. One of "yellow", "red", "green",
	// "purple", "gray", or "random".
	// (default: yellow)
	Color string

	// Whether to test authentication. Note: the normal actions will NOT be performed.
	// (default: false)
	AuthTest bool
}

type Room

type Room struct {
	// The ID of the room.
	Id int `json:"room_id"`

	// The name of the room.
	Name string

	// The current room topic.
	Topic string

	// Time of last activity (sent message) in the room in UNIX time (UTC).
	// May be 0 in rare cases when the time is unknown.
	LastActive int `json:"last_active"`

	// Time the room was created in UNIX time (UTC).
	Created int

	// Whether or not this room is archived.
	Archived bool `json:"is_archived"`

	// Whether or not this room is private.
	Private bool `json:"is_private"`

	// User ID of the room owner.
	OwnerUserId int `json:"owner_user_id"`

	// XMPP/Jabber ID of the room.
	XMPPJabberId string `json:"xmpp_jid"`
}