whatsapp

Documentation

Overview

Package whatsapp sends approved WhatsApp Business Platform templates through Meta's Cloud API. It keeps delivery explicit and never persists credentials or message parameters.

Index

• Variables
• type Client
  • func New(options Options) (Client, error)
• type Message
  • func NewAuthenticationMessage(recipient, template, language, code string) *Message
  • func NewMessage() *Message
  • func (m *Message) Components(components ...TemplateComponent) *Message
  • func (m *Message) Template(name, language string) *Message
  • func (m *Message) To(recipient string) *Message
• type Options
• type TemplateComponent
• type TemplateParameter
  • func (p TemplateParameter) MarshalJSON() ([]byte, error)

Variables

var (
	// ErrUnknownDriver means Options.Driver is not supported.
	ErrUnknownDriver = errors.New("whatsapp: unknown driver")
	// ErrInvalidRecipient means the destination is not an E.164 phone number.
	ErrInvalidRecipient = errors.New("whatsapp: recipient must be an E.164 phone number")
	// ErrTemplateRequired means a message was sent without an approved template.
	ErrTemplateRequired = errors.New("whatsapp: template name and language are required")
	// ErrDeliveryFailed hides Cloud API response bodies from callers and logs.
	ErrDeliveryFailed = errors.New("whatsapp: Cloud API delivery failed")
)

Types

type Client

type Client interface {
	// Send validates and delivers one approved template message.
	Send(context.Context, *Message) error
	// Close releases client resources; current drivers have no persistent resources.
	Close() error
}

Client sends WhatsApp template messages.

func New

func New(options Options) (Client, error)

New creates a configured WhatsApp client.

type Message

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

Message is an outbound, approved WhatsApp template message.

func NewAuthenticationMessage

func NewAuthenticationMessage(recipient, template, language, code string) *Message

NewAuthenticationMessage builds an AUTHENTICATION template message using a text body parameter for the one-time code. The template must already be approved in the sender's WhatsApp Business Account.

func NewMessage

func NewMessage() *Message

NewMessage creates an empty message builder.

func (*Message) Components

func (m *Message) Components(components ...TemplateComponent) *Message

Components replaces the message's template components.

func (*Message) Template

func (m *Message) Template(name, language string) *Message

Template selects an approved WhatsApp template and its language code.

func (*Message) To

func (m *Message) To(recipient string) *Message

To sets the destination to an E.164 phone number. A leading + is accepted.

type Options

type Options struct {
	// Driver selects log (default) or cloud delivery.
	Driver string
	// AccessToken authenticates Cloud API requests and must never be logged.
	AccessToken string
	// PhoneNumberID identifies the configured Meta sender, not its display number.
	PhoneNumberID string
	// APIVersion selects the explicit Meta Graph API version.
	APIVersion string
	// Timeout limits one outbound Cloud API request.
	Timeout time.Duration
	// Logger receives redacted log-driver delivery metadata.
	Logger *slog.Logger
	// APIBaseURL defaults to Meta's Graph API. It is useful for an approved
	// proxy or isolated integration tests; applications normally leave it empty.
	APIBaseURL string
}

Options configures a WhatsApp client. Driver is "log" by default or "cloud" for Meta's WhatsApp Cloud API.

type TemplateComponent

type TemplateComponent struct {
	// Type selects the approved template component, such as body or button.
	Type string `json:"type"`
	// SubType refines a button component when Meta requires it.
	SubType string `json:"sub_type,omitempty"`
	// Index identifies the button position when Meta requires it.
	Index string `json:"index,omitempty"`
	// Parameters are supplied in the order required by the approved template.
	Parameters []TemplateParameter `json:"parameters,omitempty"`
}

TemplateComponent describes one component in an approved template. Type is usually "header", "body", or "button". SubType and Index are used for button components when required by Meta.

type TemplateParameter

type TemplateParameter struct {
	// Type is the Meta parameter type, such as text, payload, or currency.
	Type string `json:"type"`
	// Text is the scalar value for a text parameter.
	Text string `json:"text,omitempty"`
	// Payload is the scalar value for a button payload parameter.
	Payload string `json:"payload,omitempty"`
	// Data holds the exact nested value for a non-scalar parameter type.
	Data any `json:"-"`
}

TemplateParameter is one WhatsApp template parameter. Type is normally "text" or "payload". For another Cloud API parameter type (such as "currency", "image", or "document"), Data is encoded under the same key as Type and can hold the exact approved-template value.

func (TemplateParameter) MarshalJSON

func (p TemplateParameter) MarshalJSON() ([]byte, error)

MarshalJSON matches Meta's dynamic template-parameter shape. Text and payload are common scalar forms; other parameter types carry their value in a property named after Type.