A highly configurable golang client for Whatsapp Cloud API

[!IMPORTANT]
This is the third-party library and not the official one. Not affiliated nor maintained by Meta.

Supported API

Initial Steps

Start by reading the official WhatsApp Cloud API Get Started Guide then go to Get Started Guide for initial steps in setting up your developing environment.

[!NOTE] You will find BaseClient and Client. Client provides a stateful approach, reusing the same configuration across multiple requests until manually refreshed, making it ideal for long-running services where consistency and thread safety are required. BaseClient is stateless, reloading the configuration on each request, making it more flexible for dynamic environments like multi-tenancy, where different configurations may be needed for each request.

Usage

Install the library by running

go get github.com/piusalfred/whatsapp

[!NOTE] The webhooks and messaging clients are separated to allow for different configurations and use cases. The webhooks client is designed to handle incoming notifications, while the messaging client is focused on sending messages.

package main

import (
	"context"
	"fmt"
	"net/http"
	"os"

	"github.com/piusalfred/whatsapp/config"
	"github.com/piusalfred/whatsapp/message"
	whttp "github.com/piusalfred/whatsapp/pkg/http"
)

const recipient = "XXXXXXXXXXXXX" // Placeholder for recipient number

func main() {
	ctx := context.Background()

	coreClient := whttp.NewSender[message.Message]()
	coreClient.SetHTTPClient(http.DefaultClient)

	reader := config.ReaderFunc(func(ctx context.Context) (*config.Config, error) {
		// TODO: Replace with your config reader implementation
		conf := &config.Config{
			BaseURL:           "",
			APIVersion:        "",
			AccessToken:       "",
			PhoneNumberID:     "",
			BusinessAccountID: "",
			AppSecret:         "",
			AppID:             "",
			SecureRequests:    false,
		}

		return conf, nil
	})

	baseClient, err := message.NewBaseClient(coreClient, reader)
	if err != nil {
		fmt.Printf("error creating base client: %v\n", err)
		os.Exit(1)
	}

	initTmpl := message.WithTemplateMessage(&message.Template{
		Name: "hello_world",
		Language: &message.TemplateLanguage{
			Code: "en_US",
		},
	})

	initTmplMessage, err := message.New(recipient, initTmpl)
	if err != nil {
		fmt.Printf("error creating initial template message: %v\n", err)
		os.Exit(1)
	}

	response, err := baseClient.SendMessage(ctx, initTmplMessage)
	if err != nil {
		fmt.Printf("error sending initial template message: %v\n", err)
		os.Exit(1)
	}

	fmt.Printf("response: %+v\n", response)
}

See more in examples and docs

Testing

There is provision of mocks that may come handy in testing.

Extras

The extras package contains some useful utilities for working with this library. It is experimental and may change in future releases.

OpenTelemetry Adapter provides OpenTelemetry instrumentation for tracing and monitoring sending and receiving whatsapp messages.
Model Context Protocol a simple implementation of the Model Context Protocol (MCP) server for sending whatapp messages.

Development

After making some changes run make all to format and test the code. You can also run make help to see other available commands

Whatsapp

Install / Use

README

whatsapp