sigma

README

sigma

A stable Golang API for MacOS Messages app.

---

I built sigma mostly for myself to be able to send and receive messages from Linux. It is purely a Go library to abstract any future breakages Apple might make and provide a simple and consistent API.

Usage

Sigma by itself is probably not very useful to you unless you want to build your own frontend. Instead, see one of the pre-built frontends:

• Sigma-Web
• Sigma-matrix (I'll get around to building this one day)

To write your own frontend see GoDoc here. Note: Sigma is still in very early development and the API may change, but probably won't.

Requirements

The sigma package requires an Apple computer running MacOS 10.12 or later with Messages signed into an iMessage account to work.

If you want to develop a frontend without this requirement you can use the mock.NewClient which returns the same Client interface that sigma.NewClient returns.

Alternatives

• bboyairwreck/PieMessage

Todo

• Look into better display name handling if a contact exists in address book
• Create matrix bridge

Documentation

Index

• type Chat
• type Client
  • func NewClient() (Client, error)
• type Message
• type MessageFilter

Types

type Chat

type Chat struct {
	ID           int       `json:"id"`
	DisplayName  string    `json:"displayName"`
	LastActivity time.Time `json:"lastActivity"`
}

Chat represents an active conversation with another user

type Client

type Client interface {
	// Chats returns a list of chat threads
	Chats() ([]Chat, error)

	// Messages returns a list of messages for a given chat id
	Messages(chatID int, filter MessageFilter) ([]Message, error)

	// SendMessage sends the given string message to the specified chat id
	SendMessage(chatID int, message string) error

	// SendMedia sends a new empty message with arbitrary data as an attachment to
	// a given chat id
	//
	// `name` is used for the file name that will used on disk which is visible if
	// the sender or receiver choose to save the image
	//
	// Due to current limitations the name will be prefixed with a random id
	SendMedia(chatID int, name string, data io.Reader) error

	// Attachments returns an array of file paths of attachments on the
	// specified message id
	Attachments(messageID int) ([]string, error)

	// Close destructs the client
	Close()
}

Client interface represents a sigma client (either real or mock)

func NewClient

func NewClient() (Client, error)

NewClient creates a new sigma client This function can only be called on MacOS with an iMessage account attached to the Messages app

type Message

type Message struct {
	ID        int       `json:"id"`
	Delivered bool      `json:"delivered"`
	FromMe    bool      `json:"fromMe"`
	Text      string    `json:"text"`
	Time      time.Time `json:"time"`
}

Message represents a single message in a chat

type MessageFilter

type MessageFilter struct {
	AfterID  int //(optional) get messages after the specified message id
	BeforeID int // (optional) get messages before the specified message id
	Limit    int // the maximum number of messages to return
}

MessageFilter is used to help paginate message results