cloud

Documentation

Overview

Package cloud is the Meta Cloud API flavor of botbooter's WhatsApp adapter. It receives messages from the Meta WhatsApp Business Cloud API over an inbound webhook and sends replies back through the Cloud API. It implements core.Adapter. (The whatsmeow-backed WhatsApp Web flavor lives in the sibling internal/whatsapp/whatsmeow package.)

Unlike the dial-out adapters (Slack, Discord), the Cloud API delivers inbound messages as HTTP webhook callbacks, so this adapter runs its own HTTP server: Connect binds a listener and serves until the run context is canceled, and Disconnect shuts the server down. Bind a local Addr, put a TLS-terminating reverse proxy in front, and register the public HTTPS URL in Meta's webhook settings.

Index

• Variables
• func Addr(b *core.Bot) string
• func New(cfg Config) (*core.Bot, error)
• type Config
• type Media
• type Message
  • func RawMessage(m *core.Message) (*Message, bool)
  • func RawReaction(r *core.Reaction) (*Message, bool)
• type ReactionInfo

Variables

var ErrMissingConfig = errors.New("whatsapp: missing required config field")

ErrMissingConfig is returned by New when a required Config field is empty.

Functions

func Addr

func Addr(b *core.Bot) string

Addr returns the address the bot's webhook listener is bound to (host:port), or "" if b is not a WhatsApp bot or is not currently connected. It lets a caller that passed cfg.Addr ":0" discover the OS-assigned port.

func New

func New(cfg Config) (*core.Bot, error)

New creates a WhatsApp bot backed by the Meta Cloud API. It returns ErrMissingConfig if a required credential is absent, and otherwise applies defaults for Path, GraphVersion and HTTPClient. The webhook server is not started until the bot connects.

Types

type Config

type Config struct {
	// Token is the Cloud API access token sent as a Bearer credential on
	// outbound calls. Prefer a long-lived system-user token; short-lived user
	// tokens expire in ~24h, after which Send fails.
	Token string
	// PhoneNumberID is the WhatsApp Business phone-number id that outbound
	// messages are sent from; it forms the Graph API send path.
	PhoneNumberID string
	// AppSecret verifies the X-Hub-Signature-256 HMAC on inbound webhook
	// requests. Required: without it the endpoint would accept spoofed payloads.
	AppSecret string
	// VerifyToken is the shared secret Meta echoes during the GET webhook
	// verification handshake; the adapter accepts the subscription only on match.
	VerifyToken string
	// Addr is the local TCP address the webhook server binds, e.g. ":8080". A
	// bare port ("8080") is accepted as shorthand for ":8080".
	Addr string
	// Path is the webhook route the server handles; defaults to the adapter's
	// standard path when empty.
	Path string
	// GraphVersion overrides the Meta Graph API version in outbound URLs;
	// defaults to a pinned version when empty.
	GraphVersion string
	// HTTPClient overrides the client used for outbound Cloud API calls; a
	// default client with a 30s timeout is used when nil.
	HTTPClient *http.Client
}

Config configures a WhatsApp Cloud API bot.

type Media

type Media struct {
	ID       string
	MimeType string
	Filename string
}

Media is a media object attached to a WhatsApp message. The Cloud API delivers media by ID, not URL: resolve the bytes with GET /{ID} using your access token.

type Message

type Message struct {
	From       string
	ID         string
	Type       string
	Text       string
	AuthorName string
	Timestamp  time.Time
	Media      *Media
	Reaction   *ReactionInfo
	Raw        json.RawMessage
}

Message is the parsed payload of a WhatsApp Cloud API webhook message. AuthorName and Timestamp are enriched, not lifted from Raw: AuthorName is correlated from the webhook's sibling contacts list and Timestamp is parsed from the message's unix-seconds field. Raw holds the original message JSON for callers that need more.

func RawMessage

func RawMessage(m *core.Message) (*Message, bool)

RawMessage returns the parsed WhatsApp message carried on m, reporting whether m originated from WhatsApp.

func RawReaction

func RawReaction(r *core.Reaction) (*Message, bool)

RawReaction returns the parsed WhatsApp reaction message carried on r, reporting whether r originated from a WhatsApp reaction. The reacted message's id and emoji are on the returned Message's Reaction field.

type ReactionInfo

type ReactionInfo struct {
	MessageID string
	Emoji     string
}

ReactionInfo is set on a Message of Type "reaction": the id of the message the user reacted to and the emoji. Emoji is empty when the reaction was removed.