package module
v0.0.0-...-0ec8307 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Mar 29, 2023 License: AGPL-3.0 Imports: 17 Imported by: 0




View Source
const (
	// The default host part for user JIDs on WhatsApp.
	DefaultUserServer = types.DefaultUserServer

	// The default host part for group JIDs on WhatsApp.
	DefaultGroupServer = types.GroupServer


This section is empty.


func GenerateMessageID

func GenerateMessageID() string

GenerateMessageID returns a valid, pseudo-random message ID for use in outgoing messages. This function will panic if there is no entropy available for random ID generation.


type Attachment

type Attachment struct {
	MIME     string // The MIME type for attachment.
	Filename string // The recommended file name for this attachment. May be an auto-generated name.
	Caption  string // The user-provided caption, provided alongside this attachment.
	Data     []byte // The raw binary data for this attachment. Mutually exclusive with [.URL].
	URL      string // The URL to download attachment data from. Mutually exclusive with [.Data].

A Attachment represents additional binary data (e.g. images, videos, documents) provided alongside a message, for display or storage on the recepient client.

type Avatar

type Avatar struct {
	ID  string // The unique ID for this avatar, used for persistent caching.
	URL string // The HTTP URL over which this avatar might be retrieved. Can change for the same ID.

A Avatar represents a small image representing a Contact or Group.

type Call

type Call struct {
	State     CallState
	JID       string
	Timestamp int64

A Call represents an incoming or outgoing voice/video call made over WhatsApp. Full support for calls is currently not implemented, and this structure contains the bare minimum data required for notifying on missed calls.

type CallState

type CallState int

CallState represents the state of the call to synchronize with.

const (
	CallMissed CallState = 1 + iota

The call states handled by the overarching session event handler.

type ChatState

type ChatState struct {
	Kind     ChatStateKind
	JID      string
	GroupJID string

A ChatState represents the activity of a contact within a certain discussion, for instance, whether the contact is currently composing a message. This is separate to the concept of a Presence, which is the contact's general state across all discussions.

type ChatStateKind

type ChatStateKind int

ChatStateKind represents the different kinds of chat-states possible in WhatsApp.

const (
	ChatStateComposing ChatStateKind = 1 + iota

The chat states handled by the overarching session event handler.

type Contact

type Contact struct {
	JID    string // The WhatsApp JID for this contact.
	Name   string // The user-set, human-readable name for this contact.
	Avatar Avatar // The profile picture for this contact.

A Contact represents any entity that be communicated with directly in WhatsApp. This typically represents people, but may represent a business or bot as well, but not a group-chat.

type ErrorLevel

type ErrorLevel int

A ErrorLevel is a value representing the severity of a log message being handled.

const (
	LevelError ErrorLevel = 1 + iota

The log levels handled by the overarching Session logger.

type EventKind

type EventKind int

EventKind represents all event types recognized by the Python session adapter, as emitted by the Go session adapter.

const (
	EventUnknown EventKind = iota

The event types handled by the overarching session adapter handler.

type EventPayload

type EventPayload struct {
	QRCode       string
	PairDeviceID string
	ConnectedJID string
	Contact      Contact
	Presence     Presence
	Message      Message
	ChatState    ChatState
	Receipt      Receipt
	Group        Group
	Call         Call

EventPayload represents the collected payloads for all event types handled by the overarching session adapter handler. Only specific fields will be populated in events emitted by internal handlers, see documentation for specific types for more information.

type Gateway

type Gateway struct {
	DBPath        string // The filesystem path for the client database.
	Name          string // The name to display when linking devices on WhatsApp.
	SkipVerifyTLS bool   // Whether or not our internal HTTP client will skip TLS certificate verification.
	// contains filtered or unexported fields

A Gateway represents a persistent process for establishing individual sessions between linked devices and WhatsApp.

func NewGateway

func NewGateway() *Gateway

NewGateway returns a new, un-initialized Gateway. This function should always be followed by calls to Gateway.Init, assuming a valid [Gateway.DBPath] is set.

func (*Gateway) CleanupSession

func (w *Gateway) CleanupSession(device LinkedDevice) error

CleanupSession will remove all invalid and obsolete references to the given device, and should be used when pairing a new device or unregistering from the Gateway.

func (*Gateway) Init

func (w *Gateway) Init() error

Init performs initialization procedures for the Gateway, and is expected to be run before any calls to [Gateway.Session].

func (*Gateway) NewSession

func (w *Gateway) NewSession(device LinkedDevice) *Session

NewSession returns a new for the LinkedDevice given. If the linked device does not have a valid ID, a pair operation will be required, as described in Session.Login.

func (*Gateway) SetLogHandler

func (w *Gateway) SetLogHandler(h HandleLogFunc)

SetLogHandler specifies the log handling function to use for all Gateway and Session operations.

type Group

type Group struct {
	JID          string             // The WhatsApp JID for this group.
	Name         string             // The user-defined, human-readable name for this group.
	Subject      GroupSubject       // The longer-form, user-defined description for this group.
	Nickname     string             // Our own nickname in this group-chat.
	Participants []GroupParticipant // The list of participant contacts for this group, including ourselves.

A Group represents a named, many-to-many chat space which may be joined or left at will. All fields apart from the group JID, are considered to be optional, and may not be set in cases where group information is being updated against previous assumed state. Groups in WhatsApp are generally invited to out-of-band with respect to overarching adaptor; see the documentation for Session.GetGroups for more information.

type GroupAffiliation

type GroupAffiliation int

GroupAffiliation represents the set of privilidges given to a specific participant in a group.

const (
	GroupAffiliationNone  GroupAffiliation = iota // None, or normal member group affiliation.
	GroupAffiliationAdmin                         // Can perform some management operations.
	GroupAffiliationOwner                         // Can manage group fully, including destroying the group.

type GroupParticipant

type GroupParticipant struct {
	JID         string                 // The WhatsApp JID for this participant.
	Affiliation GroupAffiliation       // The set of priviledges given to this specific participant.
	Action      GroupParticipantAction // The specific action to take for this participant; typically to add.

A GroupParticipant represents a contact who is currently joined in a given group. Participants in WhatsApp can always be derived back to their individual Contact; there are no anonymous groups in WhatsApp.

type GroupParticipantAction

type GroupParticipantAction int

GroupParticipantAction represents the distinct set of actions that can be taken when encountering a group participant, typically to add or remove.

const (
	GroupParticipantActionAdd    GroupParticipantAction = iota // Default action; add participant to list.
	GroupParticipantActionUpdate                               // Update existing participant information.
	GroupParticipantActionRemove                               // Remove participant from list, if existing.

type GroupSubject

type GroupSubject struct {
	Subject  string // The user-defined group description.
	SetAt    int64  // The exact time this group description was set at, as a timestamp.
	SetByJID string // The JID of the user that set the subject.

A GroupSubject represents the user-defined group description and attached metadata thereof, for a given Group.

type HandleEventFunc

type HandleEventFunc func(EventKind, *EventPayload)

HandleEventFunc represents a handler for incoming events sent to the Python Session, accepting an event type and payload. Note that this is distinct to the [Session.handleEvent] function, which may emit events into the Python Session event handler but which otherwise does not process across Python/Go boundaries.

type HandleLogFunc

type HandleLogFunc func(ErrorLevel, string)

HandleLogFunc is the signature for the overarching Gateway log handling function.

func (HandleLogFunc) Debugf

func (h HandleLogFunc) Debugf(msg string, args ...interface{})

Debugf handles the given message as representing an internal-only debug message.

func (HandleLogFunc) Errorf

func (h HandleLogFunc) Errorf(msg string, args ...interface{})

Errorf handles the given message as representing a (typically) fatal error.

func (HandleLogFunc) Infof

func (h HandleLogFunc) Infof(msg string, args ...interface{})

Infof handles the given message as representing an informational notice.

func (HandleLogFunc) Sub

Sub is a no-op and will return the receiver itself.

func (HandleLogFunc) Warnf

func (h HandleLogFunc) Warnf(msg string, args ...interface{})

Warn handles the given message as representing a non-fatal error or warning thereof.

type LinkedDevice

type LinkedDevice struct {
	// ID is an opaque string identifying this LinkedDevice to the Session. Noted that this string
	// is currently equivalent to a password, and needs to be protected accordingly.
	ID string

A LinkedDevice represents a unique pairing session between the gateway and WhatsApp. It is not unique to the underlying "main" device (or phone number), as multiple linked devices may be paired with any main device.

func (LinkedDevice) JID

func (d LinkedDevice) JID() types.JID

JID returns the WhatsApp JID corresponding to the LinkedDevice ID. Empty or invalid device IDs may return invalid JIDs, and this function does not handle errors.

type Message

type Message struct {
	Kind        MessageKind  // The concrete message kind being sent or received.
	ID          string       // The unique message ID, used for referring to a specific Message instance.
	JID         string       // The JID this message concerns, semantics can change based on IsCarbon.
	GroupJID    string       // The JID of the group-chat this message was sent in, if any.
	OriginJID   string       // For reactions and replies in groups, the JID of the original user.
	Body        string       // The plain-text message body. For attachment messages, this can be a caption.
	Timestamp   int64        // The Unix timestamp denoting when this message was created.
	IsCarbon    bool         // Whether or not this message concerns the gateway user themselves.
	ReplyID     string       // The unique message ID this message is in reply to, if any.
	ReplyBody   string       // The full body of the message this message is in reply to, if any.
	Attachments []Attachment // The list of file (image, video, etc.) attachments contained in this message.
	Preview     Preview      // A short description for the URL provided in the message body, if any.

A Message represents one of many kinds of bidirectional communication payloads, for example, a text message, a file (image, video) attachment, an emoji reaction, etc. Messages of different kinds are denoted as such, and re-use fields where the semantics overlap.

type MessageKind

type MessageKind int

MessageKind represents all concrete message types (plain-text messages, edit messages, reactions) recognized by the Python session adapter.

const (
	MessagePlain MessageKind = 1 + iota

The message types handled by the overarching session event handler.

type Presence

type Presence struct {
	JID      string
	Away     bool
	LastSeen int64

Precence represents a contact's general state of activity, and is periodically updated as contacts start or stop paying attention to their client of choice.

type Preview

type Preview struct {
	URL         string // The original (or canonical) URL this preview was generated for.
	Title       string // The short title for the URL preview.
	Description string // The (optional) long-form description for the URL preview.
	ImageData   []byte // The raw binary data for the image associated with the URL. Mutally exclusive with [.ImageURL].
	ImageURL    string // The URL to download an image associated with the URL. Mutually exclusive with [.ImageData].

A Preview represents a short description for a URL provided in a message body, as usually derived from the content of the page pointed at.

type Receipt

type Receipt struct {
	Kind       ReceiptKind // The distinct kind of receipt presented.
	MessageIDs []string    // The list of message IDs to mark for receipt.
	JID        string
	GroupJID   string
	Timestamp  int64
	IsCarbon   bool

A Receipt represents a notice of delivery or presentation for Message instances sent or received. Receipts can be delivered for many messages at once, but are generally all delivered under one specific state at a time.

type ReceiptKind

type ReceiptKind int

ReceiptKind represents the different types of delivery receipts possible in WhatsApp.

const (
	ReceiptDelivered ReceiptKind = 1 + iota

The delivery receipts handled by the overarching session event handler.

type Session

type Session struct {
	// contains filtered or unexported fields

A Session represents a connection (active or not) between a linked device and WhatsApp. Active sessions need to be established by logging in, after which incoming events will be forwarded to the adapter event handler, and outgoing events will be forwarded to WhatsApp.

func (*Session) Disconnect

func (s *Session) Disconnect() error

Disconnects detaches the current connection to WhatsApp without removing any linked device state.

func (*Session) GetAvatar

func (s *Session) GetAvatar(resourceID, avatarID string) (Avatar, error)

GetAvatar fetches a profile picture for the Contact or Group JID given. If a non-empty `avatarID` is also given, GetAvatar will return an empty Avatar instance with no error if the remote state for the given ID has not changed.

func (*Session) GetContacts

func (s *Session) GetContacts(refresh bool) ([]Contact, error)

GetContacts subscribes to the WhatsApp roster currently stored in the Session's internal state. If `refresh` is `true`, FetchRoster will pull application state from the remote service and synchronize any contacts found with the adapter.

func (*Session) GetGroups

func (s *Session) GetGroups() ([]Group, error)

GetGroups returns a list of all group-chats currently joined in WhatsApp, along with additional information on present participants.

func (*Session) Login

func (s *Session) Login() error

Login attempts to authenticate the given Session, either by re-using the LinkedDevice attached or by initiating a pairing session for a new linked device. Callers are expected to have set an event handler in order to receive any incoming events from the underlying WhatsApp session.

func (*Session) Logout

func (s *Session) Logout() error

Logout disconnects and removes the current linked device locally and initiates a logout remotely.

func (*Session) SendChatState

func (s *Session) SendChatState(state ChatState) error

SendChatState sends the given chat state notification (e.g. composing message) to WhatsApp for the contact specified within.

func (*Session) SendMessage

func (s *Session) SendMessage(message Message) error

SendMessage processes the given Message and sends a WhatsApp message for the kind and contact JID specified within. In general, different message kinds require different fields to be set; see the documentation for the Message type for more information.

func (*Session) SendReceipt

func (s *Session) SendReceipt(receipt Receipt) error

SendReceipt sends a read receipt to WhatsApp for the message IDs specified within.

func (*Session) SetEventHandler

func (s *Session) SetEventHandler(h HandleEventFunc)

SetEventHandler assigns the given handler function for propagating internal events into the Python gateway. Note that the event handler function is not entirely safe to use directly, and all calls should instead be made via the [propagateEvent] function.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL