whatsmeow

package module
v1.9.3 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2022 License: MPL-2.0 Imports: 46 Imported by: 1

README

whatsmeow

Go Reference

whatsmeow is a Go library for the WhatsApp web multidevice API.

Discussion

Matrix room: #whatsmeow:maunium.net

For questions about the WhatsApp protocol (like how to send a specific type of message), you can also use the WhatsApp protocol Q&A section on GitHub discussions.

Usage

The godoc includes docs for all methods and event types. There's also a simple example at the top.

Also see mdtest for a CLI tool you can easily try out whatsmeow with.

Features

Most core features are already present:

  • Sending messages to private chats and groups (both text and media)
  • Receiving all messages
  • Managing groups and receiving group change events
  • Joining via invite messages, using and creating invite links
  • Sending and receiving typing notifications
  • Sending and receiving delivery and read receipts
  • Reading app state (contact list, chat pin/mute status, etc)
  • Sending and handling retry receipts if message decryption fails
  • Sending status messages (experimental, may not work for large contact lists)

Things that are not yet implemented:

  • Writing app state (contact list, chat pin/mute status, etc)
  • Sending broadcast list messages (this is not supported on WhatsApp web either)
  • Calls

Documentation

Overview

Package whatsmeow implements a client for interacting with the WhatsApp web multidevice API.

Example 
package main

import (
	"context"
	"fmt"
	"os"
	"os/signal"
	"syscall"

	"github.com/pfthink/whatsmeow"
	"github.com/pfthink/whatsmeow/store/sqlstore"
	"github.com/pfthink/whatsmeow/types/events"
	waLog "github.com/pfthink/whatsmeow/util/log"
)

func eventHandler(evt interface{}) {
	switch v := evt.(type) {
	case *events.Message:
		fmt.Println("Received a message!", v.Message.GetConversation())
	}
}

func main() {
	dbLog := waLog.Stdout("Database", "DEBUG", true)
	// Make sure you add appropriate DB connector imports, e.g. github.com/mattn/go-sqlite3 for SQLite
	container, err := sqlstore.New("sqlite3", "file:examplestore.db?_foreign_keys=on", dbLog)
	if err != nil {
		panic(err)
	}
	// If you want multiple sessions, remember their JIDs and use .GetDevice(jid) or .GetAllDevices() instead.
	deviceStore, err := container.GetFirstDevice()
	if err != nil {
		panic(err)
	}
	clientLog := waLog.Stdout("Client", "DEBUG", true)
	client := whatsmeow.NewClient(deviceStore, clientLog)
	client.AddEventHandler(eventHandler)

	if client.Store.ID == nil {
		// No ID stored, new login
		qrChan, _ := client.GetQRChannel(context.Background())
		err = client.Connect()
		if err != nil {
			panic(err)
		}
		for evt := range qrChan {
			if evt.Event == "code" {
				// Render the QR code here
				// e.g. qrterminal.GenerateHalfBlock(evt.Code, qrterminal.L, os.Stdout)
				// or just manually `echo 2@... | qrencode -t ansiutf8` in a terminal
				fmt.Println("QR code:", evt.Code)
			} else {
				fmt.Println("Login event:", evt.Event)
			}
		}
	} else {
		// Already logged in, just connect
		err = client.Connect()
		if err != nil {
			panic(err)
		}
	}

	// Listen to Ctrl+C (you can also do something else that prevents the program from exiting)
	c := make(chan os.Signal)
	signal.Notify(c, os.Interrupt, syscall.SIGTERM)
	<-c

	client.Disconnect()
}

Output:

Index

Examples

Constants

View Source 
const (
	// WantedPreKeyCount is the number of prekeys that the client should upload to the WhatsApp servers in a single batch.
	WantedPreKeyCount = 50
	// MinPreKeyCount is the number of prekeys when the client will upload a new batch of prekeys to the WhatsApp servers.
	MinPreKeyCount = 5
)
View Source 
const (
	DisappearingTimerOff     = time.Duration(0)
	DisappearingTimer24Hours = 24 * time.Hour
	DisappearingTimer7Days   = 7 * 24 * time.Hour
	DisappearingTimer90Days  = 90 * 24 * time.Hour
)
View Source 
const BusinessMessageLinkDirectPrefix = "https://api.whatsapp.com/message/"
View Source 
const BusinessMessageLinkPrefix = "https://wa.me/message/"
View Source 
const CheckUpdateURL = "https://web.whatsapp.com/check-update"

CheckUpdateURL is the base URL to check for WhatsApp web updates.

View Source 
const InviteLinkPrefix = "https://chat.whatsapp.com/"
View Source 
const NoiseHandshakeResponseTimeout = 20 * time.Second

Variables

View Source 
var (
	ErrNoSession    = errors.New("can't encrypt message for device: no signal session established")
	ErrIQTimedOut   = errors.New("info query timed out")
	ErrNotConnected = errors.New("websocket not connected")
	ErrNotLoggedIn  = errors.New("the store doesn't contain a device JID")

	ErrAlreadyConnected = errors.New("websocket is already connected")

	ErrQRAlreadyConnected = errors.New("GetQRChannel must be called before connecting")
	ErrQRStoreContainsID  = errors.New("GetQRChannel can only be called when there's no user ID in the client's Store")

	ErrNoPushName = errors.New("can't send presence without PushName set")
)

Miscellaneous errors

View Source 
var (
	// ErrProfilePictureUnauthorized is returned by GetProfilePictureInfo when trying to get the profile picture of a user
	// whose privacy settings prevent you from seeing their profile picture (status code 401).
	ErrProfilePictureUnauthorized = errors.New("the user has hidden their profile picture from you")
	// ErrGroupInviteLinkUnauthorized is returned by GetGroupInviteLink if you don't have the permission to get the link (status code 401).
	ErrGroupInviteLinkUnauthorized = errors.New("you don't have the permission to get the group's invite link")
	// ErrNotInGroup is returned by group info getting methods if you're not in the group (status code 403).
	ErrNotInGroup = errors.New("you're not participating in that group")
	// ErrGroupNotFound is returned by group info getting methods if the group doesn't exist (status code 404).
	ErrGroupNotFound = errors.New("that group does not exist")
	// ErrInviteLinkInvalid is returned by methods that use group invite links if the invite link is malformed.
	ErrInviteLinkInvalid = errors.New("that group invite link is not valid")
	// ErrInviteLinkRevoked is returned by methods that use group invite links if the invite link was valid, but has been revoked and can no longer be used.
	ErrInviteLinkRevoked = errors.New("that group invite link has been revoked")
	// ErrBusinessMessageLinkNotFound is returned by ResolveBusinessMessageLink if the link doesn't exist or has been revoked.
	ErrBusinessMessageLinkNotFound = errors.New("that business message link does not exist or has been revoked")
	// ErrInvalidImageFormat is returned by SetGroupPhoto if the given photo is not in the correct format.
	ErrInvalidImageFormat = errors.New("the given data is not a valid image")
	// ErrMediaNotAvailableOnPhone is returned by DecryptMediaRetryNotification if the given event contains error code 2.
	ErrMediaNotAvailableOnPhone = errors.New("media no longer available on phone")
	// ErrUnknownMediaRetryError is returned by DecryptMediaRetryNotification if the given event contains an unknown error code.
	ErrUnknownMediaRetryError = errors.New("unknown media retry error")
	// ErrInvalidDisappearingTimer is returned by SetDisappearingTimer if the given timer is not one of the allowed values.
	ErrInvalidDisappearingTimer = errors.New("invalid disappearing timer provided")
)
View Source 
var (
	ErrBroadcastListUnsupported = errors.New("sending to non-status broadcast lists is not yet supported")
	ErrUnknownServer            = errors.New("can't send message to unknown server")
	ErrRecipientADJID           = errors.New("message recipient must be normal (non-AD) JID")
)

Some errors that Client.SendMessage can return

View Source 
var (
	ErrMediaDownloadFailedWith404 = errors.New("download failed with status code 404")
	ErrMediaDownloadFailedWith410 = errors.New("download failed with status code 410")
	ErrNoURLPresent               = errors.New("no url present")
	ErrFileLengthMismatch         = errors.New("file length does not match")
	ErrTooShortFile               = errors.New("file too short")
	ErrInvalidMediaHMAC           = errors.New("invalid media hmac")
	ErrInvalidMediaEncSHA256      = errors.New("hash of media ciphertext doesn't match")
	ErrInvalidMediaSHA256         = errors.New("hash of media plaintext doesn't match")
	ErrUnknownMediaType           = errors.New("unknown media type")
	ErrNothingDownloadableFound   = errors.New("didn't find any attachments in message")
)

Some errors that Client.Download can return

View Source 
var (
	ErrIQBadRequest    error = &IQError{Code: 400, Text: "bad-request"}
	ErrIQNotAuthorized error = &IQError{Code: 401, Text: "not-authorized"}
	ErrIQForbidden     error = &IQError{Code: 403, Text: "forbidden"}
	ErrIQNotFound      error = &IQError{Code: 404, Text: "item-not-found"}
	ErrIQNotAcceptable error = &IQError{Code: 406, Text: "not-acceptable"}
	ErrIQGone          error = &IQError{Code: 410, Text: "gone"}
)

Common errors returned by info queries for use with errors.Is

View Source 
var (
	// KeepAliveResponseDeadline specifies the duration to wait for a response to websocket keepalive pings.
	KeepAliveResponseDeadline = 10 * time.Second
	// KeepAliveIntervalMin specifies the minimum interval for websocket keepalive pings.
	KeepAliveIntervalMin = 20 * time.Second
	// KeepAliveIntervalMax specifies the maximum interval for websocket keepalive pings.
	KeepAliveIntervalMax = 30 * time.Second
)
View Source 
var (
	// QRChannelSuccess is emitted from GetQRChannel when the pairing is successful.
	QRChannelSuccess = QRChannelItem{Event: "success"}
	// QRChannelTimeout is emitted from GetQRChannel if the socket gets disconnected by the server before the pairing is successful.
	QRChannelTimeout = QRChannelItem{Event: "timeout"}
	// QRChannelErrUnexpectedEvent is emitted from GetQRChannel if an unexpected connection event is received,
	// as that likely means that the pairing has already happened before the channel was set up.
	QRChannelErrUnexpectedEvent = QRChannelItem{Event: "err-unexpected-state"}
	// QRChannelClientOutdated is emitted from GetQRChannel if events.ClientOutdated is received.
	QRChannelClientOutdated = QRChannelItem{Event: "err-client-outdated"}
	// QRChannelScannedWithoutMultidevice is emitted from GetQRChannel if events.QRScannedWithoutMultidevice is received.
	QRChannelScannedWithoutMultidevice = QRChannelItem{Event: "err-scanned-without-multidevice"}
)
View Source 
var DefaultStatusPrivacy = []types.StatusPrivacy{{
	Type:      types.StatusPrivacyTypeContacts,
	IsDefault: true,
}}
View Source 
var ErrIQDisconnected = &DisconnectedError{Action: "info query"}

Functions

func DecryptMediaRetryNotification 

func DecryptMediaRetryNotification(evt *events.MediaRetry, mediaKey []byte) (*waProto.MediaRetryNotification, error)

DecryptMediaRetryNotification decrypts a media retry notification using the media key. See Client.SendMediaRetryReceipt for more info on how to use this.

func GenerateMessageID 

func GenerateMessageID() types.MessageID

GenerateMessageID generates a random string that can be used as a message ID on WhatsApp. 

msgID := whatsmeow.GenerateMessageID()
cli.SendMessage(targetJID, msgID, &waProto.Message{...})

func ParseDisappearingTimerString 

func ParseDisappearingTimerString(val string) (time.Duration, bool)

ParseDisappearingTimerString parses common human-readable disappearing message timer strings into Duration values. If the string doesn't look like one of the allowed values (0, 24h, 7d, 90d), the second return value is false.

Types

type CheckUpdateResponse 

type CheckUpdateResponse struct {
	IsBroken       bool
	IsBelowSoft    bool
	IsBelowHard    bool
	CurrentVersion string

	ParsedVersion store.WAVersionContainer `json:"-"`
}

CheckUpdateResponse is the data returned by CheckUpdate.

func CheckUpdate 

func CheckUpdate(httpClient *http.Client) (respData CheckUpdateResponse, err error)

CheckUpdate asks the WhatsApp servers if there is an update available.

type Client 

type Client struct {
	Store *store.Device
	Log   waLog.Logger

	EnableAutoReconnect   bool
	LastSuccessfulConnect time.Time
	AutoReconnectErrors   int

	// EmitAppStateEventsOnFullSync can be set to true if you want to get app state events emitted
	// even when re-syncing the whole state.
	EmitAppStateEventsOnFullSync bool

	// GetMessageForRetry is used to find the source message for handling retry receipts
	// when the message is not found in the recently sent message cache.
	GetMessageForRetry func(requester, to types.JID, id types.MessageID) *waProto.Message
	// PreRetryCallback is called before a retry receipt is accepted.
	// If it returns false, the accepting will be cancelled and the retry receipt will be ignored.
	PreRetryCallback func(receipt *events.Receipt, id types.MessageID, retryCount int, msg *waProto.Message) bool

	// Should untrusted identity errors be handled automatically? If true, the stored identity and existing signal
	// sessions will be removed on untrusted identity errors, and an events.IdentityChange will be dispatched.
	// If false, decrypting a message from untrusted devices will fail.
	AutoTrustIdentity bool

	BizType string
	// contains filtered or unexported fields
}

Client contains everything necessary to connect to and interact with the WhatsApp web API.

func NewClient 

func NewClient(deviceStore *store.Device, log waLog.Logger) *Client

NewClient initializes a new WhatsApp web client.

The logger can be nil, it will default to a no-op logger.

The device store must be set. A default SQL-backed implementation is available in the store/sqlstore package. 

container, err := sqlstore.New("sqlite3", "file:yoursqlitefile.db?_foreign_keys=on", nil)
if err != nil {
    panic(err)
}
// If you want multiple sessions, remember their JIDs and use .GetDevice(jid) or .GetAllDevices() instead.
deviceStore, err := container.GetFirstDevice()
if err != nil {
    panic(err)
}
client := whatsmeow.NewClient(deviceStore, nil)

func (*Client) AddEventHandler 

func (cli *Client) AddEventHandler(handler EventHandler, newCli *Client) uint32

AddEventHandler registers a new function to receive all events emitted by this client.

The returned integer is the event handler ID, which can be passed to RemoveEventHandler to remove it.

All registered event handlers will receive all events. You should use a type switch statement to filter the events you want: 

func myEventHandler(evt interface{}) {
    switch v := evt.(type) {
    case *events.Message:
        fmt.Println("Received a message!")
    case *events.Receipt:
        fmt.Println("Received a receipt!")
    }
}

If you want to access the Client instance inside the event handler, the recommended way is to wrap the whole handler in another struct: 

type MyClient struct {
    WAClient *whatsmeow.Client
    eventHandlerID uint32
}

func (mycli *MyClient) register() {
    mycli.eventHandlerID = mycli.WAClient.AddEventHandler(mycli.myEventHandler)
}

func (mycli *MyClient) myEventHandler(evt interface{}) {
     // Handle event and access mycli.WAClient
}

func (*Client) CheckUpdate 

func (cli *Client) CheckUpdate() (respData CheckUpdateResponse, err error)

CheckUpdate asks the WhatsApp servers if there is an update available (using the HTTP client and proxy settings of this whatsmeow Client instance).

func (*Client) Connect 

func (cli *Client) Connect() error

Connect connects the client to the WhatsApp web websocket. After connection, it will either authenticate if there's data in the device store, or emit a QREvent to set up a new link.

func (*Client) CreateGroup 

func (cli *Client) CreateGroup(name string, participants []types.JID) (*types.GroupInfo, error)

CreateGroup creates a group on WhatsApp with the given name and participants.

You don't need to include your own JID in the participants array, the WhatsApp servers will add it implicitly.

func (*Client) DangerousInternals deprecated 

func (cli *Client) DangerousInternals() *DangerousInternalClient

DangerousInternals allows access to some unexported methods in Client.

Deprecated: dangerous

func (*Client) Disconnect 

func (cli *Client) Disconnect()

Disconnect disconnects from the WhatsApp web websocket.

This will not emit any events, the Disconnected event is only used when the connection is closed by the server or a network error.

func (*Client) Download 

func (cli *Client) Download(msg DownloadableMessage) ([]byte, error)

Download downloads the attachment from the given protobuf message.

The attachment is a specific part of a Message protobuf struct, not the message itself, e.g. 

var msg *waProto.Message
...
imageData, err := cli.Download(msg.GetImageMessage())

You can also use DownloadAny to download the first non-nil sub-message.

func (*Client) DownloadAny 

func (cli *Client) DownloadAny(msg *waProto.Message) (data []byte, err error)

DownloadAny loops through the downloadable parts of the given message and downloads the first non-nil item.

func (*Client) DownloadMediaWithPath 

func (cli *Client) DownloadMediaWithPath(directPath string, encFileHash, fileHash, mediaKey []byte, fileLength int, mediaType MediaType, mmsType string) (data []byte, err error)

DownloadMediaWithPath downloads an attachment by manually specifying the path and encryption details.

func (*Client) DownloadThumbnail 

func (cli *Client) DownloadThumbnail(msg DownloadableThumbnail) ([]byte, error)

DownloadThumbnail downloads a thumbnail from a message.

This is primarily intended for downloading link preview thumbnails, which are in ExtendedTextMessage: 

var msg *waProto.Message
...
thumbnailImageBytes, err := cli.DownloadThumbnail(msg.GetExtendedTextMessage())

func (*Client) FetchAppState 

func (cli *Client) FetchAppState(name appstate.WAPatchName, fullSync, onlyIfNotSynced bool) error

FetchAppState fetches updates to the given type of app state. If fullSync is true, the current cached state will be removed and all app state patches will be re-fetched from the server.

func (*Client) GetGroupInfo 

func (cli *Client) GetGroupInfo(jid types.JID) (*types.GroupInfo, error)

GetGroupInfo requests basic info about a group chat from the WhatsApp servers.

func (*Client) GetGroupInfoFromInvite 

func (cli *Client) GetGroupInfoFromInvite(jid, inviter types.JID, code string, expiration int64) (*types.GroupInfo, error)

GetGroupInfoFromInvite gets the group info from an invite message.

Note that this is specifically for invite messages, not invite links. Use GetGroupInfoFromLink for resolving chat.whatsapp.com links. 

func (cli *Client) GetGroupInfoFromLink(code string) (*types.GroupInfo, error)

GetGroupInfoFromLink resolves the given invite link and asks the WhatsApp servers for info about the group. This will not cause the user to join the group. 

func (cli *Client) GetGroupInviteLink(jid types.JID, reset bool) (string, error)

GetGroupInviteLink requests the invite link to the group from the WhatsApp servers.

If reset is true, then the old invite link will be revoked and a new one generated.

func (*Client) GetJoinedGroups 

func (cli *Client) GetJoinedGroups() ([]*types.GroupInfo, error)

GetJoinedGroups returns the list of groups the user is participating in.

func (*Client) GetPrivacySettings 

func (cli *Client) GetPrivacySettings() (settings types.PrivacySettings)

GetPrivacySettings will get the user's privacy settings. If an error occurs while fetching them, the error will be logged, but the method will just return an empty struct.

func (*Client) GetProfilePictureInfo 

func (cli *Client) GetProfilePictureInfo(jid types.JID, preview bool) (*types.ProfilePictureInfo, error)

GetProfilePictureInfo gets the URL where you can download a WhatsApp user's profile picture or group's photo. If the user or group doesn't have a profile picture, this returns nil with no error.

func (*Client) GetQRChannel 

func (cli *Client) GetQRChannel(ctx context.Context) (<-chan QRChannelItem, error)

GetQRChannel returns a channel that automatically outputs a new QR code when the previous one expires.

This must be called *before* Connect(). It will then listen to all the relevant events from the client.

The last value to be emitted will be a special string, either "success", "timeout" or "err-already-have-id", depending on the result of the pairing. The channel will be closed immediately after one of those.

func (*Client) GetStatusPrivacy 

func (cli *Client) GetStatusPrivacy() ([]types.StatusPrivacy, error)

GetStatusPrivacy gets the user's status privacy settings (who to send status broadcasts to).

There can be multiple different stored settings, the first one is always the default.

func (*Client) GetUserDevices 

func (cli *Client) GetUserDevices(jids []types.JID) ([]types.JID, error)

GetUserDevices gets the list of devices that the given user has. The input should be a list of regular JIDs, and the output will be a list of AD JIDs. The local device will not be included in the output even if the user's JID is included in the input. All other devices will be included.

func (*Client) GetUserInfo 

func (cli *Client) GetUserInfo(jids []types.JID) (map[types.JID]types.UserInfo, error)

GetUserInfo gets basic user info (avatar, status, verified business name, device list).

func (*Client) IsConnected 

func (cli *Client) IsConnected() bool

IsConnected checks if the client is connected to the WhatsApp web websocket. Note that this doesn't check if the client is authenticated. See the IsLoggedIn field for that.

func (*Client) IsLoggedIn 

func (cli *Client) IsLoggedIn() bool

IsLoggedIn returns true after the client is successfully connected and authenticated on WhatsApp.

func (*Client) IsOnWhatsApp 

func (cli *Client) IsOnWhatsApp(phones []string) ([]types.IsOnWhatsAppResponse, error)

IsOnWhatsApp checks if the given phone numbers are registered on WhatsApp. The phone numbers should be in international format, including the `+` prefix.

func (*Client) JoinGroupWithInvite 

func (cli *Client) JoinGroupWithInvite(jid, inviter types.JID, code string, expiration int64) error

JoinGroupWithInvite joins a group using an invite message.

Note that this is specifically for invite messages, not invite links. Use JoinGroupWithLink for joining with chat.whatsapp.com links. 

func (cli *Client) JoinGroupWithLink(code string) (types.JID, error)

JoinGroupWithLink joins the group using the given invite link.

func (*Client) LeaveGroup 

func (cli *Client) LeaveGroup(jid types.JID) error

LeaveGroup leaves the specified group on WhatsApp.

func (*Client) Logout 

func (cli *Client) Logout() error

Logout sends a request to unlink the device, then disconnects from the websocket and deletes the local device store.

If the logout request fails, the disconnection and local data deletion will not happen either. If an error is returned, but you want to force disconnect/clear data, call Client.Disconnect() and Client.Store.Delete() manually.

Note that this will not emit any events. The LoggedOut event is only used for external logouts (triggered by the user from the main device or by WhatsApp servers).

func (*Client) MarkRead 

func (cli *Client) MarkRead(ids []types.MessageID, timestamp time.Time, chat, sender types.JID) error

MarkRead sends a read receipt for the given message IDs including the given timestamp as the read at time.

The first JID parameter (chat) must always be set to the chat ID (user ID in DMs and group ID in group chats). The second JID parameter (sender) must be set in group chats and must be the user ID who sent the message.

func (*Client) ParseWebMessage 

func (cli *Client) ParseWebMessage(chatJID types.JID, webMsg *waProto.WebMessageInfo) (*events.Message, error)

ParseWebMessage parses a WebMessageInfo object into *events.Message to match what real-time messages have.

The chat JID can be found in the Conversation data: 

chatJID, err := types.ParseJID(conv.GetId())
for _, historyMsg := range conv.GetMessages() {
  evt, err := cli.ParseWebMessage(chatJID, historyMsg.GetMessage())
  yourNormalEventHandler(evt)
}

func (*Client) RemoveEventHandler 

func (cli *Client) RemoveEventHandler(id uint32) bool

RemoveEventHandler removes a previously registered event handler function. If the function with the given ID is found, this returns true.

N.B. Do not run this directly from an event handler. That would cause a deadlock because the event dispatcher holds a read lock on the event handler list, and this method wants a write lock on the same list. Instead run it in a goroutine: 

func (mycli *MyClient) myEventHandler(evt interface{}) {
    if noLongerWantEvents {
        go mycli.WAClient.RemoveEventHandler(mycli.eventHandlerID)
    }
}

func (*Client) RemoveEventHandlers 

func (cli *Client) RemoveEventHandlers()

RemoveEventHandlers removes all event handlers that have been registered with AddEventHandler 

func (cli *Client) ResolveBusinessMessageLink(code string) (*types.BusinessMessageLinkTarget, error)

ResolveBusinessMessageLink resolves a business message short link and returns the target JID, business name and text to prefill in the input field (if any).

The links look like https://wa.me/message/<code> or https://api.whatsapp.com/message/<code>. You can either provide the full link, or just the <code> part.

func (*Client) RevokeMessage 

func (cli *Client) RevokeMessage(chat types.JID, id types.MessageID) (time.Time, error)

RevokeMessage deletes the given message from everyone in the chat. You can only revoke your own messages, and if the message is too old, then other users will ignore the deletion.

This method will wait for the server to acknowledge the revocation message before returning. The return value is the timestamp of the message from the server.

func (*Client) SendChatPresence 

func (cli *Client) SendChatPresence(jid types.JID, state types.ChatPresence, media types.ChatPresenceMedia) error

SendChatPresence updates the user's typing status in a specific chat.

The media parameter can be set to indicate the user is recording media (like a voice message) rather than typing a text message.

func (*Client) SendMediaRetryReceipt 

func (cli *Client) SendMediaRetryReceipt(message *types.MessageInfo, mediaKey []byte) error

SendMediaRetryReceipt sends a request to the phone to re-upload the media in a message.

This is mostly relevant when handling history syncs and getting a 404 or 410 error downloading media. Rough example on how to use it (will not work out of the box, you must adjust it depending on what you need exactly): 

var mediaRetryCache map[types.MessageID]*waProto.ImageMessage

evt, err := cli.ParseWebMessage(chatJID, historyMsg.GetMessage())
imageMsg := evt.Message.GetImageMessage() // replace this with the part of the message you want to download
data, err := cli.Download(imageMsg)
if errors.Is(err, whatsmeow.ErrMediaDownloadFailedWith404) || errors.Is(err, whatsmeow.ErrMediaDownloadFailedWith410) {
  err = cli.SendMediaRetryReceipt(&evt.Info, imageMsg.GetMediaKey())
  // You need to store the event data somewhere as it's necessary for handling the retry response.
  mediaRetryCache[evt.Info.ID] = imageMsg
}

The response will come as an *events.MediaRetry. The response will then have to be decrypted using DecryptMediaRetryNotification and the same media key passed here. If the media retry was successful, the decrypted notification should contain an updated DirectPath, which can be used to download the file. 

func eventHandler(rawEvt interface{}) {
  switch evt := rawEvt.(type) {
  case *events.MediaRetry:
    imageMsg := mediaRetryCache[evt.MessageID]
    retryData, err := whatsmeow.DecryptMediaRetryNotification(evt, imageMsg.GetMediaKey())
    if err != nil || retryData.GetResult != waProto.MediaRetryNotification_SUCCESS {
      return
    }
    // Use the new path to download the attachment
    imageMsg.DirectPath = retryData.DirectPath
    data, err := cli.Download(imageMsg)
    // Alternatively, you can use cli.DownloadMediaWithPath and provide the individual fields manually.
  }
}

func (*Client) SendMessage 

func (cli *Client) SendMessage(to types.JID, id types.MessageID, message *waProto.Message) (time.Time, error)

SendMessage sends the given message.

If the message ID is not provided, a random message ID will be generated.

This method will wait for the server to acknowledge the message before returning. The return value is the timestamp of the message from the server.

The message itself can contain anything you want (within the protobuf schema). e.g. for a simple text message, use the Conversation field: 

cli.SendMessage(targetJID, "", &waProto.Message{
    Conversation: proto.String("Hello, World!"),
})

Things like replies, mentioning users and the "forwarded" flag are stored in ContextInfo, which can be put in ExtendedTextMessage and any of the media message types.

For uploading and sending media/attachments, see the Upload method.

For other message types, you'll have to figure it out yourself. Looking at the protobuf schema in binary/proto/def.proto may be useful to find out all the allowed fields.

func (*Client) SendPresence 

func (cli *Client) SendPresence(state types.Presence) error

SendPresence updates the user's presence status on WhatsApp.

You should call this at least once after connecting so that the server has your pushname. Otherwise, other users will see "-" as the name.

func (*Client) SetDisappearingTimer 

func (cli *Client) SetDisappearingTimer(chat types.JID, timer time.Duration) (err error)

SetDisappearingTimer sets the disappearing timer in a chat. Both private chats and groups are supported, but they're set with different methods.

Note that while this function allows passing non-standard durations, official WhatsApp apps will ignore those, and in groups the server will just reject the change. You can use the DisappearingTimer<Duration> constants for convenience.

In groups, the server will echo the change as a notification, so it'll show up as a *events.GroupInfo update.

func (*Client) SetForceActiveDeliveryReceipts 

func (cli *Client) SetForceActiveDeliveryReceipts(active bool)

SetForceActiveDeliveryReceipts will force the client to send normal delivery receipts (which will show up as the two gray ticks on WhatsApp), even if the client isn't marked as online.

By default, clients that haven't been marked as online will send delivery receipts with type="inactive", which is transmitted to the sender, but not rendered in the official WhatsApp apps. This is consistent with how WhatsApp web works when it's not in the foreground.

To mark the client as online, use 

cli.SendPresence(types.PresenceAvailable)

Note that if you turn this off (i.e. call SetForceActiveDeliveryReceipts(false)), receipts will act like the client is offline until SendPresence is called again.

func (*Client) SetGroupAnnounce 

func (cli *Client) SetGroupAnnounce(jid types.JID, announce bool) error

SetGroupAnnounce changes whether the group is in announce mode (i.e. whether only admins can send messages).

func (*Client) SetGroupLocked 

func (cli *Client) SetGroupLocked(jid types.JID, locked bool) error

SetGroupLocked changes whether the group is locked (i.e. whether only admins can modify group info).

func (*Client) SetGroupName 

func (cli *Client) SetGroupName(jid types.JID, name string) error

SetGroupName updates the name (subject) of the given group on WhatsApp.

func (*Client) SetGroupPhoto 

func (cli *Client) SetGroupPhoto(jid types.JID, avatar []byte) (string, error)

SetGroupPhoto updates the group picture/icon of the given group on WhatsApp. The avatar should be a JPEG photo, other formats may be rejected with ErrInvalidImageFormat. The bytes can be nil to remove the photo. Returns the new picture ID.

func (*Client) SetGroupTopic 

func (cli *Client) SetGroupTopic(jid types.JID, previousID, newID, topic string) error

SetGroupTopic updates the topic (description) of the given group on WhatsApp.

The previousID and newID fields are optional. If the previous ID is not specified, this will automatically fetch the current group info to find the previous topic ID. If the new ID is not specified, one will be generated with GenerateMessageID().

func (*Client) SetPassive 

func (cli *Client) SetPassive(passive bool) error

SetPassive tells the WhatsApp server whether this device is passive or not.

This seems to mostly affect whether the device receives certain events. By default, whatsmeow will automatically do SetPassive(false) after connecting.

func (*Client) SetProxy 

func (cli *Client) SetProxy(proxy socket.Proxy)

SetProxy sets the proxy to use for WhatsApp web websocket connections and media uploads/downloads.

Must be called before Connect() to take effect in the websocket connection. If you want to change the proxy after connecting, you must call Disconnect() and then Connect() again manually.

By default, the client will find the proxy from the https_proxy environment variable like Go's net/http does.

To disable reading proxy info from environment variables, explicitly set the proxy to nil: 

cli.SetProxy(nil)

To use a different proxy for the websocket and media, pass a function that checks the request path or headers: 

cli.SetProxy(func(r *http.Request) (*url.URL, error) {
    if r.URL.Host == "web.whatsapp.com" && r.URL.Path == "/ws/chat" {
        return websocketProxyURL, nil
    } else {
        return mediaProxyURL, nil
    }
})

func (*Client) SetProxyAddress 

func (cli *Client) SetProxyAddress(addr string) error

SetProxyAddress is a helper method that parses a URL string and calls SetProxy.

Returns an error if url.Parse fails to parse the given address.

func (*Client) SubscribePresence 

func (cli *Client) SubscribePresence(jid types.JID) error

SubscribePresence asks the WhatsApp servers to send presence updates of a specific user to this client.

After subscribing to this event, you should start receiving *events.Presence for that user in normal event handlers.

Also, it seems that the WhatsApp servers require you to be online to receive presence status from other users, so you should mark yourself as online before trying to use this function: 

cli.SendPresence(types.PresenceAvailable)

func (*Client) TryFetchPrivacySettings 

func (cli *Client) TryFetchPrivacySettings(ignoreCache bool) (*types.PrivacySettings, error)

TryFetchPrivacySettings will fetch the user's privacy settings, either from the in-memory cache or from the server.

func (*Client) UpdateGroupParticipants 

func (cli *Client) UpdateGroupParticipants(jid types.JID, participantChanges map[types.JID]ParticipantChange) (*waBinary.Node, error)

UpdateGroupParticipants can be used to add, remove, promote and demote members in a WhatsApp group.

func (*Client) Upload 

func (cli *Client) Upload(ctx context.Context, plaintext []byte, appInfo MediaType) (resp UploadResponse, err error)

Upload uploads the given attachment to WhatsApp servers.

You should copy the fields in the response to the corresponding fields in a protobuf message.

For example, to send an image: 

resp, err := cli.Upload(context.Background(), yourImageBytes, whatsmeow.MediaImage)
// handle error

imageMsg := &waProto.ImageMessage{
    Caption:  proto.String("Hello, world!"),
    Mimetype: proto.String("image/png"), // replace this with the actual mime type
    // you can also optionally add other fields like ContextInfo and JpegThumbnail here

    Url:           &resp.URL,
    DirectPath:    &resp.DirectPath,
    MediaKey:      resp.MediaKey,
    FileEncSha256: resp.FileEncSHA256,
    FileSha256:    resp.FileSha256,
    FileLength:    &resp.FileLength,
}
_, err = cli.SendMessage(targetJID, "", &waProto.Message{
    ImageMessage: imageMsg,
})
// handle error again

The same applies to the other message types like DocumentMessage, just replace the struct type and Message field name.

func (*Client) WaitForConnection 

func (cli *Client) WaitForConnection(timeout time.Duration) bool

type DangerousInfoQuery 

type DangerousInfoQuery = infoQuery

type DangerousInfoQueryType 

type DangerousInfoQueryType = infoQueryType

type DangerousInternalClient 

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

func (*DangerousInternalClient) CancelResponse 

func (int *DangerousInternalClient) CancelResponse(reqID string, ch chan *waBinary.Node)

func (*DangerousInternalClient) GetServerPreKeyCount 

func (int *DangerousInternalClient) GetServerPreKeyCount() (int, error)

func (*DangerousInternalClient) QueryMediaConn 

func (int *DangerousInternalClient) QueryMediaConn() (*MediaConn, error)

func (*DangerousInternalClient) RefreshMediaConn 

func (int *DangerousInternalClient) RefreshMediaConn(force bool) (*MediaConn, error)

func (*DangerousInternalClient) RequestAppStateKeys 

func (int *DangerousInternalClient) RequestAppStateKeys(keyIDs [][]byte)

func (*DangerousInternalClient) SendIQ 

func (int *DangerousInternalClient) SendIQ(query DangerousInfoQuery) (*waBinary.Node, error)

func (*DangerousInternalClient) SendIQAsync 

func (int *DangerousInternalClient) SendIQAsync(query DangerousInfoQuery) (<-chan *waBinary.Node, error)

func (*DangerousInternalClient) SendNode 

func (int *DangerousInternalClient) SendNode(node waBinary.Node) error

func (*DangerousInternalClient) SendRetryReceipt 

func (int *DangerousInternalClient) SendRetryReceipt(node *waBinary.Node, forceIncludeIdentity bool)

func (*DangerousInternalClient) WaitResponse 

func (int *DangerousInternalClient) WaitResponse(reqID string) chan *waBinary.Node

type DisconnectedError 

type DisconnectedError struct {
	Action string
	Node   *waBinary.Node
}

DisconnectedError is returned if the websocket disconnects before an info query or other request gets a response.

func (*DisconnectedError) Error 

func (err *DisconnectedError) Error() string

func (*DisconnectedError) Is 

func (err *DisconnectedError) Is(other error) bool

type DownloadableMessage 

type DownloadableMessage interface {
	proto.Message
	GetDirectPath() string
	GetMediaKey() []byte
	GetFileSha256() []byte
	GetFileEncSha256() []byte
}

DownloadableMessage represents a protobuf message that contains attachment info.

All of the downloadable messages inside a Message struct implement this interface (ImageMessage, VideoMessage, AudioMessage, DocumentMessage, StickerMessage).

type DownloadableThumbnail 

type DownloadableThumbnail interface {
	proto.Message
	GetThumbnailDirectPath() string
	GetThumbnailSha256() []byte
	GetThumbnailEncSha256() []byte
	GetMediaKey() []byte
}

DownloadableThumbnail represents a protobuf message that contains a thumbnail attachment.

This is primarily meant for link preview thumbnails in ExtendedTextMessage.

type ElementMissingError 

type ElementMissingError struct {
	Tag string
	In  string
}

ElementMissingError is returned by various functions that parse XML elements when a required element is missing.

func (*ElementMissingError) Error 

func (eme *ElementMissingError) Error() string

type EventHandler 

type EventHandler func(evt interface{}, newCli *Client)

EventHandler is a function that can handle events from WhatsApp.

type IQError 

type IQError struct {
	Code      int
	Text      string
	ErrorNode *waBinary.Node
	RawNode   *waBinary.Node
}

IQError is a generic error container for info queries

func (*IQError) Error 

func (iqe *IQError) Error() string

func (*IQError) Is 

func (iqe *IQError) Is(other error) bool

type MediaConn 

type MediaConn struct {
	Auth       string
	AuthTTL    int
	TTL        int
	MaxBuckets int
	FetchedAt  time.Time
	Hosts      []MediaConnHost
}

MediaConn contains a list of WhatsApp servers from which attachments can be downloaded from.

func (*MediaConn) Expiry 

func (mc *MediaConn) Expiry() time.Time

Expiry returns the time when the MediaConn expires.

type MediaConnHost 

type MediaConnHost struct {
	Hostname string
}

MediaConnHost represents a single host to download media from.

type MediaType 

type MediaType string

MediaType represents a type of uploaded file on WhatsApp. The value is the key which is used as a part of generating the encryption keys. 

const (
	MediaImage    MediaType = "WhatsApp Image Keys"
	MediaVideo    MediaType = "WhatsApp Video Keys"
	MediaAudio    MediaType = "WhatsApp Audio Keys"
	MediaDocument MediaType = "WhatsApp Document Keys"
	MediaHistory  MediaType = "WhatsApp History Keys"
	MediaAppState MediaType = "WhatsApp App State Keys"

	MediaLinkThumbnail MediaType = "WhatsApp Link Thumbnail Keys"
)

The known media types

func GetMediaType 

func GetMediaType(msg DownloadableMessage) MediaType

GetMediaType returns the MediaType value corresponding to the given protobuf message.

type ParticipantChange 

type ParticipantChange string
const (
	ParticipantChangeAdd     ParticipantChange = "add"
	ParticipantChangeRemove  ParticipantChange = "remove"
	ParticipantChangePromote ParticipantChange = "promote"
	ParticipantChangeDemote  ParticipantChange = "demote"
)

type QRChannelItem 

type QRChannelItem struct {
	// The type of event, "code" for new QR codes.
	// For non-code/error events, you can just compare the whole item to the event variables (like QRChannelSuccess).
	Event string
	// If the item is a pair error, then this field contains the error message.
	Error error
	// If the item is a new code, then this field contains the raw data.
	Code string
	// The timeout after which the next code will be sent down the channel.
	Timeout time.Duration
}

type RecentMessage 

type RecentMessage struct {
	Proto     *waProto.Message
	Timestamp time.Time
}

RecentMessage contains the info needed to re-send a message when another device fails to decrypt it.

type UploadResponse 

type UploadResponse struct {
	URL        string `json:"url"`
	DirectPath string `json:"direct_path"`

	MediaKey      []byte `json:"-"`
	FileEncSHA256 []byte `json:"-"`
	FileSHA256    []byte `json:"-"`
	FileLength    uint64 `json:"-"`
}

UploadResponse contains the data from the attachment upload, which can be put into a message to send the attachment.

Source Files

View all Source files

Directories

Path Synopsis
Package appstate implements encoding and decoding WhatsApp's app state patches.
 Package appstate implements encoding and decoding WhatsApp's app state patches.
lthash
Package lthash implements a summation based hash algorithm that maintains the integrity of a piece of data over a series of mutations.
 Package lthash implements a summation based hash algorithm that maintains the integrity of a piece of data over a series of mutations.
Package binary implements encoding and decoding documents in WhatsApp's binary XML format.
 Package binary implements encoding and decoding documents in WhatsApp's binary XML format.
proto
Package proto contains the compiled protobuf structs from WhatsApp's protobuf schema.
 Package proto contains the compiled protobuf structs from WhatsApp's protobuf schema.
token
Package token contains maps of predefined tokens that WhatsApp's binary XML encoding uses to save bytes when sending commonly used strings.
 Package token contains maps of predefined tokens that WhatsApp's binary XML encoding uses to save bytes when sending commonly used strings.
mdtest module
Package socket implements a subset of the Noise protocol framework on top of websockets as used by WhatsApp.
 Package socket implements a subset of the Noise protocol framework on top of websockets as used by WhatsApp.
Package store contains interfaces for storing data needed for WhatsApp multidevice.
 Package store contains interfaces for storing data needed for WhatsApp multidevice.
sqlstore
Package sqlstore contains an SQL-backed implementation of the interfaces in the store package.
 Package sqlstore contains an SQL-backed implementation of the interfaces in the store package.
Package types contains various structs and other types used by whatsmeow.
 Package types contains various structs and other types used by whatsmeow.
events
Package events contains all the events that whatsmeow.Client emits to functions registered with AddEventHandler.
 Package events contains all the events that whatsmeow.Client emits to functions registered with AddEventHandler.
util
cbcutil
CBC describes a block cipher mode.
 CBC describes a block cipher mode.
hkdfutil
Package hkdfutil contains a simple wrapper for golang.org/x/crypto/hkdf that reads a specified number of bytes.
 Package hkdfutil contains a simple wrapper for golang.org/x/crypto/hkdf that reads a specified number of bytes.
keys
Package keys contains a utility struct for elliptic curve keypairs.
 Package keys contains a utility struct for elliptic curve keypairs.
log
Package waLog contains a simple logger interface used by the other whatsmeow packages.
 Package waLog contains a simple logger interface used by the other whatsmeow packages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.