whatsapp

README

whatsapp

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

• Message
  • Text
  • Media
  • Templates
  • Interactive Messages
  • Replies and Reactions
• QR Code Management
• Phone Number Management
  • Get Phone Number Information
  • Update Phone Number
• Media Management
• Webhooks
• User Management
  • Block Users
  • Unblock Users
  • Get Blocked Users
• Conversation Automation
• File Uploads
• Call Settings

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

Links

• Get Started Guide
• Postman Collection
• Webhooks Get Started
• Messages Documentation
• Phone Numbers Documentation
• Whatsapp Flows
• Whatsapp Flows Guide
• Flows Reference
• QR Codes Documentation
• Flows Best Practices
• FlowJSON
• Error Codes
• Application Dashboard
• Webhooks for Whatsapp Business Account
• Webhooks Notification Payload Reference
• System Users (Important in Tokens Management)
• Install Apps, Generate, Refresh, and Revoke Tokens
• Create, Retrieve and Update a System User
• Access Token Debugger
• Securing Requests
• Analytics
• Conversational Components
• Graph API Reference
• Flows Webhooks
• Whatsapp Business Platform Documentation
• Flow Encryption
• Whatsapp Business Account Graph API Reference
• Webhooks Override
• Calling API Settings

Documentation

Index

• Constants
• func IsCorrectAPIVersion(apiVersion string) bool
• type Error
  • func (e Error) Error() string

Examples

• IsCorrectAPIVersion

Constants

const (
	BaseURL                   = "https://graph.facebook.com"
	LowestSupportedAPIVersion = "v20.0" // This is the lowest version of the API that is supported
	MessageProduct            = "whatsapp"
)

Functions

func IsCorrectAPIVersion

func IsCorrectAPIVersion(apiVersion string) bool

IsCorrectAPIVersion checks if the provided API version string is valid and supported. The version string should be in the format "v<major_version>.<minor_version>". It returns true if the major version is 16 or higher, otherwise false.

Example

package main

import (
	"fmt"

	"github.com/piusalfred/whatsapp"
)

func main() {
	fmt.Println(whatsapp.IsCorrectAPIVersion("v20.1"))    // true
	fmt.Println(whatsapp.IsCorrectAPIVersion("v21.0"))    // true
	fmt.Println(whatsapp.IsCorrectAPIVersion("v15.9"))    // false
	fmt.Println(whatsapp.IsCorrectAPIVersion("v100.0"))   // true
	fmt.Println(whatsapp.IsCorrectAPIVersion("v0.0"))     // false
	fmt.Println(whatsapp.IsCorrectAPIVersion("v0.hello")) // false
	fmt.Println(whatsapp.IsCorrectAPIVersion("vhi.1"))    // false
	fmt.Println(whatsapp.IsCorrectAPIVersion("v20.0"))    // true
	fmt.Println(whatsapp.IsCorrectAPIVersion("20.1"))     // false

}

Output:
true
true
false
true
false
false
false
true
false

Types

type Error

type Error string

func (Error) Error

func (e Error) Error() string