client

Documentation

Overview

This package provides a client for sending messages via Threema.Gateway.

Index

• Constants
• Variables
• type Client
• type E2EClient
  • func NewE2EClient(id ThreemaID, apiSecret string, privKey PrivateKey) (*E2EClient, error)
  • func (c *E2EClient) GetCapabilities(id ThreemaID) ([]string, error)
  • func (c *E2EClient) GetRemainingCredits() (int, error)
  • func (c *E2EClient) LookupIDByEmailHash(address string) (ThreemaID, error)
  • func (c *E2EClient) LookupIDByPhoneHash(phoneNumber string) (ThreemaID, error)
  • func (c *E2EClient) LookupPublicKeyByID(requestedID ThreemaID) (PublicKey, error)
  • func (c *E2EClient) SendTextMessage(to ThreemaID, msg string) error
  • func (c *E2EClient) SendTextMessageToEmail(address string, msg string) error
  • func (c *E2EClient) SendTextMessageToPhone(phone string, msg string) error
  • func (c *E2EClient) SetClient(httpClient *http.Client)
• type MessageType
• type Nonce
• type PrivateKey
• type PublicKey
• type SimpleClient
  • func NewSimpleClient(id ThreemaID, apiSecret string) (*SimpleClient, error)
  • func (c *SimpleClient) GetCapabilities(id ThreemaID) ([]string, error)
  • func (c *SimpleClient) GetRemainingCredits() (int, error)
  • func (c *SimpleClient) LookupIDByEmailHash(address string) (ThreemaID, error)
  • func (c *SimpleClient) LookupIDByPhoneHash(phoneNumber string) (ThreemaID, error)
  • func (c *SimpleClient) SendTextMessage(to ThreemaID, msg string) error
  • func (c *SimpleClient) SendTextMessageToEmail(address string, msg string) error
  • func (c *SimpleClient) SendTextMessageToPhone(phone string, msg string) error
  • func (c *SimpleClient) SetClient(httpClient *http.Client)
• type ThreemaID

Constants

const (
	DefaultThreemaGatewayURL = "https://msgapi.threema.ch"
	MaxTextMessageBytes      = 3500
)

const (
	TextMessage     MessageType = 0x01 // Content: UTF-8 encoded string
	ImageMessage                = 0x02 // Unsupported, TODO
	FileMessage                 = 0x17 // Unsupported, TODO
	DeliveryReceipt             = 0x80 // Unsupported, TODO
)

Variables

var (
	// Caller errors
	ErrInvalidPhoneNumber = errors.New("invalid phone number, must consist of at most 15 digits")
	ErrIDLength           = errors.New("id must be exactly 8 bytes long")

	// API errors
	ErrInvalidRequest = errors.New("invalid recipient or identity not set up for chosen mode (simple/e2e)")
	ErrMissingBlob    = errors.New("missing parameters or blob is empty")
	ErrCredentials    = errors.New("wrong id or secret for API")
	ErrOutOfCredits   = errors.New("out of credits")
	ErrNotFound       = errors.New("id not found")
	ErrMessageTooLong = errors.New("message too long")
	ErrBlobTooLarge   = errors.New("blob too large")
	ErrTemporary      = errors.New("temporary API failure")
	ErrUnknown        = errors.New("unknown API error")
)

Types

type Client

type Client interface {
	// Fetches the remaining credits for the ID associated with the Client.
	GetRemainingCredits() (int, error)

	LookupIDByPhoneHash(phoneNumber string) (ThreemaID, error)
	LookupIDByEmailHash(address string) (ThreemaID, error)

	SendTextMessage(id ThreemaID, apiSecret string) error
	SendTextMessageToPhone(phone string, apiSecret string) error
	SendTextMessageToEmail(address string, apiSecret string) error
}

type E2EClient

type E2EClient struct {
	// contains filtered or unexported fields
}

An E2EClient has a private key to sign and encrypt messages with.

func NewE2EClient

func NewE2EClient(id ThreemaID, apiSecret string, privKey PrivateKey) (*E2EClient, error)

func (*E2EClient) GetCapabilities

func (c *E2EClient) GetCapabilities(id ThreemaID) ([]string, error)

Returns the capabilities of the given ID. As of 01/2021, there are five supported capabilities:

• text
• image
• video
• audio
• file

func (*E2EClient) GetRemainingCredits

func (c *E2EClient) GetRemainingCredits() (int, error)

func (*E2EClient) LookupIDByEmailHash

func (c *E2EClient) LookupIDByEmailHash(address string) (ThreemaID, error)

Looks up the Threema ID of the given e-mail address by its hash. The e-mail must be passed in plaintext, it will be normalized and hashed as necessary.

Returns ErrNotFound if the given address is unknown.

func (*E2EClient) LookupIDByPhoneHash

func (c *E2EClient) LookupIDByPhoneHash(phoneNumber string) (ThreemaID, error)

Looks up the Threema ID of the given phone number by hash. Phone number must be passed in E.164 format. It will be normalized and hashed as neceassary

Returns ErrNotFound if the given phone number is unknown.

func (*E2EClient) LookupPublicKeyByID

func (c *E2EClient) LookupPublicKeyByID(requestedID ThreemaID) (PublicKey, error)

Looks up the public key associated with the corresponding ID.

Updates the client's cache on successful lookup.

func (*E2EClient) SendTextMessage

func (c *E2EClient) SendTextMessage(to ThreemaID, msg string) error

Send a message to the given Threema ID.

The public key of the recipient is cached for up to `maxCacheEntryAge`, so multiple invocations of SendTextMessage re-use existing public keys.

The message is encrypted before sending.

func (*E2EClient) SendTextMessageToEmail

func (c *E2EClient) SendTextMessageToEmail(address string, msg string) error

Send a message to account associated with the given email address.

E-Mail->ID translations are not cached, so specifying recipients by Threema ID is preferred.

The message is encrypted before sending.

func (*E2EClient) SendTextMessageToPhone

func (c *E2EClient) SendTextMessageToPhone(phone string, msg string) error

Send a message to the account associated with the given phone number, passed in E.164 format.

Phone->ID translations are not cached, so specifying recipients by Threema ID is preferred.

The message is encrypted before sending.

func (*E2EClient) SetClient

func (c *E2EClient) SetClient(httpClient *http.Client)

Set the http.Client to be used

type MessageType

type MessageType = byte

type Nonce

type Nonce = [24]byte

type PrivateKey

type PrivateKey = [32]byte

type PublicKey

type PublicKey = [32]byte

type SimpleClient

type SimpleClient struct {
	// contains filtered or unexported fields
}

A simple client has no private key. It can only send text messages, which are encrypted using a key held by Threema.

func NewSimpleClient

func NewSimpleClient(id ThreemaID, apiSecret string) (*SimpleClient, error)

func (*SimpleClient) GetCapabilities

func (c *SimpleClient) GetCapabilities(id ThreemaID) ([]string, error)

Returns the capabilities of the given ID. As of 01/2021, there are five supported capabilities:

• text
• image
• video
• audio
• file

func (*SimpleClient) GetRemainingCredits

func (c *SimpleClient) GetRemainingCredits() (int, error)

func (*SimpleClient) LookupIDByEmailHash

func (c *SimpleClient) LookupIDByEmailHash(address string) (ThreemaID, error)

Looks up the Threema ID of the given e-mail address by its hash. The e-mail must be passed in plaintext, it will be normalized and hashed as necessary.

Returns ErrNotFound if the given address is unknown.

func (*SimpleClient) LookupIDByPhoneHash

func (c *SimpleClient) LookupIDByPhoneHash(phoneNumber string) (ThreemaID, error)

Looks up the Threema ID of the given phone number by hash. Phone number must be passed in E.164 format. It will be normalized and hashed as neceassary

Returns ErrNotFound if the given phone number is unknown.

func (*SimpleClient) SendTextMessage

func (c *SimpleClient) SendTextMessage(to ThreemaID, msg string) error

Send a message to the given Threema ID.

The message is sent in plaintext and encrypted at the Threema servers.

func (*SimpleClient) SendTextMessageToEmail

func (c *SimpleClient) SendTextMessageToEmail(address string, msg string) error

Send a message to account associated with the given email address.

The message is sent in plaintext and encrypted at the Threema servers.

func (*SimpleClient) SendTextMessageToPhone

func (c *SimpleClient) SendTextMessageToPhone(phone string, msg string) error

Send a message to the given phone number, passed in E.164 format.

The message is sent in plaintext and encrypted at the Threema servers.

func (*SimpleClient) SetClient

func (c *SimpleClient) SetClient(httpClient *http.Client)

Set the http.Client to be used

type ThreemaID

type ThreemaID = string