hangouts

README

Google Hangouts Chat Library for Golang

Shortly after Hangouts Chat became publicly available, we built seibert-media/hangouts-jira-bot to try out how the bot connectivity works.

While doing this, one of our first steps was to build this mapping to easily create messages. As we are now aiming to try out building more bots and integrating Chat into our tool landscape it became reasonable to offer this as a standalone library which is well documented.

In addition to this, we added further helpers to easily build messages available in builder.go.

Requirements

All dependencies are managed using dep and checked into git. To update those dependencies use dep ensure --update after you added new imports to your code.

For building or running tests a onetime execution of make deps might be required.

Usage

For now, this package only offers sending messages. To receive messages and events, we suggest using PubSub. This implementation might be added here in the future but is out of scope for now. To learn how to do this, check the official docs or give our jira bot a look.

This package offers both a default connection using Google Service Accounts and sending messages via channel webhooks.

The entire connection Part relies on github.com/playnet-public/libs/log for logging. If you are not using Zap and are an external user, you could simply use log.NewNop() when initializing the connection to get an empty no-op logger.

Service Account

To send messages using a service account, use New(...) which is using the Google DefaultClient for taking credential as described here.

To send messages onto a webhook use NewWebhookClient(...).

Afterwards you can simply use Send(...) to post your messages. Check out code comments for further information on how to use this.

Examples

Documentation

Overview

Package hangouts offers both helpers for connecting with the Google Hangouts Chat API as well as building and sending messages.

Index

• Constants
• type Action
• type ActionParameter
  • func NewActionParameter(key, value string) *ActionParameter
• type Button
  • func NewImageActionButton(icon, iconURL, action string, parameters ...*ActionParameter) *Button
  • func NewImageLinkButton(icon, iconURL, url string) *Button
  • func NewTextActionButton(text, action string, parameters ...*ActionParameter) *Button
  • func NewTextLinkButton(text, url string) *Button
• type Card
  • func NewCard() *Card
  • func (c *Card) WithAction(a *Action) *Card
  • func (c *Card) WithHeader(title, subtitle, imageURL, imageStyle string) *Card
  • func (c *Card) WithSection(s *Section) *Card
• type Event
• type FormAction
• type Hangouts
  • func New(ctx context.Context, serviceAccount string) (*Hangouts, error)
  • func NewWebhookClient(url string) (*Hangouts, error)
  • func (h *Hangouts) Send(ctx context.Context, space string, msg *Message) error
• type Header
• type Image
  • func NewImage(url string, ratio int) *Image
  • func (i *Image) WithAction(name string, parameters ...*ActionParameter) *Image
  • func (i *Image) WithOpenLink(url string) *Image
• type ImageButton
• type KeyValue
  • func NewKeyValue(topLabel, content string, multiline bool) *KeyValue
  • func (kv *KeyValue) WithAction(name string, parameters ...*ActionParameter) *KeyValue
  • func (kv *KeyValue) WithBottomLabel(l string) *KeyValue
  • func (kv *KeyValue) WithButton(b *Button) *KeyValue
  • func (kv *KeyValue) WithOpenLink(url string) *KeyValue
• type Message
  • func NewMessage() *Message
  • func (m *Message) InThread(name string) *Message
  • func (m *Message) WithCard(c *Card) *Message
  • func (m *Message) WithSender(u User) *Message
  • func (m *Message) WithText(t string) *Message
• type OnClick
• type OpenLink
• type Section
  • func NewSection(header string) *Section
  • func (s *Section) WithWidget(w *Widget) *Section
• type TextButton
• type TextParagraph
• type Thread
• type User
• type Widget
  • func NewWidget() *Widget
  • func (w *Widget) WithButton(b *Button) *Widget
  • func (w *Widget) WithImage(i *Image) *Widget
  • func (w *Widget) WithKeyValue(kv *KeyValue) *Widget
  • func (w *Widget) WithTextParagraph(t string) *Widget

Constants

const (
	// MESSAGE event type
	MESSAGE = "MESSAGE"
	// ADDED event type
	ADDED = "ADDED_TO_SPACE"
	// REMOVED event type
	REMOVED = "REMOVED_FROM_SPACE"
)

Types

type Action

type Action struct {
	Label   string   `json:"actionLabel,omitempty"`
	OnClick *OnClick `json:"onClick,omitempty"`
}

Action struct

type ActionParameter

type ActionParameter struct {
	Key   string `json:"key,omitempty"`
	Value string `json:"value,omitempty"`
}

ActionParameter struct

func NewActionParameter

func NewActionParameter(key, value string) *ActionParameter

NewActionParameter for use in KeyValue

type Button

type Button struct {
	TextButton  *TextButton  `json:"textButton,omitempty"`
	ImageButton *ImageButton `json:"imageButton,omitempty"`
}

Button struct

func NewImageActionButton

func NewImageActionButton(icon, iconURL, action string, parameters ...*ActionParameter) *Button

NewImageActionButton containing FormAction

func NewImageLinkButton

func NewImageLinkButton(icon, iconURL, url string) *Button

NewImageLinkButton containing OpenLink

func NewTextActionButton

func NewTextActionButton(text, action string, parameters ...*ActionParameter) *Button

NewTextActionButton containing FormAction

func NewTextLinkButton

func NewTextLinkButton(text, url string) *Button

NewTextLinkButton containing OpenLink

type Card

type Card struct {
	Header   *Header    `json:"header,omitempty"`
	Sections []*Section `json:"sections"`
	Actions  []*Action  `json:"cardActions,omitempty"`
}

Card struct

func NewCard

func NewCard() *Card

NewCard for being used in Message

func (*Card) WithAction

func (c *Card) WithAction(a *Action) *Card

WithAction adds a new Action to Card

func (*Card) WithHeader

func (c *Card) WithHeader(title, subtitle, imageURL, imageStyle string) *Card

WithHeader adds the defined header values to card

func (*Card) WithSection

func (c *Card) WithSection(s *Section) *Card

WithSection adds a new Section to Card

type Event

type Event struct {
	Type  string `json:"type"`
	Space struct {
		Name string `json:"name"`
		Type string `json:"type"`
	} `json:"space"`
	Message Message `json:"message,omitempty"`
	User    User    `json:"user"`
}

Event struct

type FormAction

type FormAction struct {
	MethodName string             `json:"actionMethodName,omitempty"`
	Parameters []*ActionParameter `json:"parameters,omitempty"`
}

FormAction struct

type Hangouts

type Hangouts struct {
	*http.Client
	URL string
}

Hangouts handler

func New

func New(ctx context.Context, serviceAccount string) (*Hangouts, error)

New Hangouts client

func NewWebhookClient

func NewWebhookClient(url string) (*Hangouts, error)

NewWebhookClient for Hangouts

func (*Hangouts) Send

func (h *Hangouts) Send(ctx context.Context, space string, msg *Message) error

Send Message to Hangouts space can be left empty if using webhooks as it is used to identify the channel messages are being sent to

type Header

type Header struct {
	Title      string `json:"title"`
	Subtitle   string `json:"subtitle,omitempty"`
	ImageURL   string `json:"imageUrl,omitempty"`
	ImageStyle string `json:"imageStyle,omitempty"`
}

Header struct

type Image

type Image struct {
	ImageURL    string   `json:"imageUrl,omitempty"`
	OnClick     *OnClick `json:"onClick,omitempty"`
	AspectRatio int      `json:"aspectRatio,omitempty"`
}

Image struct

func NewImage

func NewImage(url string, ratio int) *Image

NewImage with URL and AspectRatio

func (*Image) WithAction

func (i *Image) WithAction(name string, parameters ...*ActionParameter) *Image

WithAction adds OnClick with FormAction to Image

func (*Image) WithOpenLink

func (i *Image) WithOpenLink(url string) *Image

WithOpenLink adds OnClick with OpenLink to Image

type ImageButton

type ImageButton struct {
	IconURL string   `json:"iconUrl,omitempty"`
	Icon    string   `json:"icon,omitempty"`
	OnClick *OnClick `json:"onClick,omitempty"`
}

ImageButton struct

type KeyValue

type KeyValue struct {
	TopLabel         string   `json:"topLabel,omitempty"`
	Content          string   `json:"content,omitempty"`
	ContentMultiline bool     `json:"contentMultiline,omitempty"`
	BottomLabel      string   `json:"bottomLabel,omitempty"`
	OnClick          *OnClick `json:"onClick,omitempty"`
	Icon             string   `json:"icon,omitempty"`
	IconURL          string   `json:"iconUrl,omitempty"`
	Button           *Button  `json:"button,omitempty"`
}

KeyValue struct

func NewKeyValue

func NewKeyValue(topLabel, content string, multiline bool) *KeyValue

NewKeyValue for use in Widget TopLabel and Content are required

func (*KeyValue) WithAction

func (kv *KeyValue) WithAction(name string, parameters ...*ActionParameter) *KeyValue

WithAction adds OnClick containing a FormAction to KeyValue

func (*KeyValue) WithBottomLabel

func (kv *KeyValue) WithBottomLabel(l string) *KeyValue

WithBottomLabel for KeyValue

func (*KeyValue) WithButton

func (kv *KeyValue) WithButton(b *Button) *KeyValue

WithButton adds new Button to KeyValue

func (*KeyValue) WithOpenLink

func (kv *KeyValue) WithOpenLink(url string) *KeyValue

WithOpenLink adds OnClick containing an OpenLink action to KeyValue

type Message

type Message struct {
	Name       string  `json:"name,omitempty"`
	Sender     User    `json:"sender,omitempty"`
	CreateTime string  `json:"createTime,omitempty"`
	Text       string  `json:"text,omitempty"`
	Thread     *Thread `json:"thread,omitempty"`
	Cards      []*Card `json:"cards,omitempty"`
}

Message struct

func NewMessage

func NewMessage() *Message

NewMessage message with builder functions

func (*Message) InThread

func (m *Message) InThread(name string) *Message

InThread defines the thread a message should be posted in

func (*Message) WithCard

func (m *Message) WithCard(c *Card) *Message

WithCard adds a new card to Message

func (*Message) WithSender

func (m *Message) WithSender(u User) *Message

WithSender adds a User to Message

func (*Message) WithText

func (m *Message) WithText(t string) *Message

WithText adds text to function

type OnClick

type OnClick struct {
	Action   *FormAction `json:"action,omitempty"`
	OpenLink *OpenLink   `json:"openLink,omitempty"`
}

OnClick struct

type OpenLink

type OpenLink struct {
	URL string `json:"url,omitempty"`
}

OpenLink struct

type Section

type Section struct {
	Header  string    `json:"header,omitempty"`
	Widgets []*Widget `json:"widgets,omitempty"`
}

Section struct

func NewSection

func NewSection(header string) *Section

NewSection for being used in Card

func (*Section) WithWidget

func (s *Section) WithWidget(w *Widget) *Section

WithWidget adds a new Widget to Section

type TextButton

type TextButton struct {
	Text    string   `json:"text,omitempty"`
	OnClick *OnClick `json:"onClick,omitempty"`
}

TextButton struct

type TextParagraph

type TextParagraph struct {
	Text string `json:"text"`
}

TextParagraph struct

type Thread

type Thread struct {
	Name string `json:"name,omitempty"`
}

Thread struct

type User

type User struct {
	Type        string `json:"type"`
	Name        string `json:"name"`
	DisplayName string `json:"displayName"`
	AvatarURL   string `json:"avatarUrl"`
	Email       string `json:"email"`
}

User struct

type Widget

type Widget struct {
	TextParagraph *TextParagraph `json:"textParagraph,omitempty"`
	KeyValue      *KeyValue      `json:"keyValue,omitempty"`
	Buttons       []*Button      `json:"buttons,omitempty"`
	Image         *Image         `json:"image,omitempty"`
}

Widget struct

func NewWidget

func NewWidget() *Widget

NewWidget which may **either** contain TextParagraph, KeyValue or Buttons

func (*Widget) WithButton

func (w *Widget) WithButton(b *Button) *Widget

WithButton adds new Button to Widget

func (*Widget) WithImage

func (w *Widget) WithImage(i *Image) *Widget

WithImage adds new Image to Widget

func (*Widget) WithKeyValue

func (w *Widget) WithKeyValue(kv *KeyValue) *Widget

WithKeyValue adds KeyValue object to widget

func (*Widget) WithTextParagraph

func (w *Widget) WithTextParagraph(t string) *Widget

WithTextParagraph adds text to widget