GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.
Go botgogolanggolang-whatsappgolang-whatsapp-apirestrest-apiwhatsappwhatsapp-apiwhatsapp-api-gowhatsapp-multi-devicewhatsapp-web-multi-device
package utils
import (
"cmp"
"encoding/json"
"fmt"
"strings"
"unicode/utf8"
"go.mau.fi/whatsmeow/proto/waE2E"
)
// WhatsApp Business / Cloud API senders put their text in template, buttons,
// interactive, list, product and order messages instead of Conversation or
// ExtendedTextMessage. The Build*Payload helpers expose them to webhooks as
// plain structs (not protos, so they survive a JSON round-trip), and
// extractBusinessMessageText renders the same data as the text used for the
// webhook body, stored message content and Chatwoot.
type BusinessButton struct {
Type string `json:"type"` // quick_reply, url, call, copy, or the native-flow name
Text string `json:"text,omitempty"`
ID string `json:"id,omitempty"`
URL string `json:"url,omitempty"`
Phone string `json:"phone_number,omitempty"`
Code string `json:"code,omitempty"`
Rows []BusinessButtonRow `json:"rows,omitempty"` // single_select options
}
type BusinessButtonRow struct {
ID string `json:"id"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
}
// BusinessMessage is a template or buttons message for webhooks.
type BusinessMessage struct {
Title string `json:"title,omitempty"`
Subtitle string `json:"subtitle,omitempty"`
HeaderType string `json:"header_type,omitempty"` // image, video, document, location, product
Body string `json:"body,omitempty"`
Footer string `json:"footer,omitempty"`
TemplateID string `json:"template_id,omitempty"`
Buttons []BusinessButton `json:"buttons,omitempty"`
Cards []BusinessMessage `json:"cards,omitempty"`
}
// BusinessProduct is a ProductMessage for webhooks. Prices are in WhatsApp's
// unit (amount x 1000).
type BusinessProduct struct {
ProductID string `json:"product_id,omitempty"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
CurrencyCode string `json:"currency_code,omitempty"`
PriceAmount1000 int64 `json:"price_amount_1000,omitempty"`
SalePriceAmount1000 int64 `json:"sale_price_amount_1000,omitempty"`
RetailerID string `json:"retailer_id,omitempty"`
URL string `json:"url,omitempty"`
CatalogTitle string `json:"catalog_title,omitempty"`
Body string `json:"body,omitempty"`
Footer string `json:"footer,omitempty"`
BusinessOwnerJID string `json:"business_owner_jid,omitempty"`
}
// BusinessSelection is a tap on a list row, button, template quick reply or
// native-flow button. SelectedID matches the row or button id of the original
// message.
type BusinessSelection struct {
Kind string `json:"kind"` // list, buttons, template, interactive
Text string `json:"text,omitempty"`
Description string `json:"description,omitempty"`
SelectedID string `json:"selected_id,omitempty"`
}
// templateMessage returns the template carried by msg. Legacy senders wrap
// it in a HighlyStructuredMessage; only the hydrated form carries text.
func templateMessage(msg *waE2E.Message) *waE2E.TemplateMessage {
return cmp.Or(msg.GetTemplateMessage(), msg.GetHighlyStructuredMessage().GetHydratedHsm())
}
// BuildTemplatePayload returns the template (or hydrated HSM) in msg as a
// webhook struct, or nil.
func BuildTemplatePayload(msg *waE2E.Message) *BusinessMessage {
tm := templateMessage(msg)
if tm == nil {
return nil
}
hydrated := cmp.Or(tm.GetHydratedTemplate(), tm.GetHydratedFourRowTemplate())
templateID := cmp.Or(tm.GetTemplateID(), hydrated.GetTemplateID())
if im := tm.GetInteractiveMessageTemplate(); im != nil {
out := interactiveAsBusinessMessage(im)
out.TemplateID = templateID
return out
}
if hydrated != nil {
out := &BusinessMessage{
Title: hydrated.GetHydratedTitleText(),
HeaderType: templateHeaderType(hydrated),
Body: hydrated.GetHydratedContentText(),
Footer: hydrated.GetHydratedFooterText(),
TemplateID: templateID,
}
for _, button := range hydrated.GetHydratedButtons() {
if b, ok := hydratedTemplateButton(button); ok {
out.Buttons = append(out.Buttons, b)
}
}
return out
}
// A non-hydrated four-row template only has HSM element names.
if templateID != "" {
return &BusinessMessage{TemplateID: templateID}
}
return nil
}
func templateHeaderType(t *waE2E.TemplateMessage_HydratedFourRowTemplate) string {
switch {
case t.GetImageMessage() != nil:
return "image"
case t.GetVideoMessage() != nil:
return "video"
case t.GetDocumentMessage() != nil:
return "document"
case t.GetLocationMessage() != nil:
return "location"
}
return ""
}
func hydratedTemplateButton(button *waE2E.HydratedTemplateButton) (BusinessButton, bool) {
switch {
case button.GetQuickReplyButton() != nil:
quick := button.GetQuickReplyButton()
return BusinessButton{Type: "quick_reply", Text: quick.GetDisplayText(), ID: quick.GetID()}, true
case button.GetUrlButton() != nil:
link := button.GetUrlButton()
return BusinessButton{Type: "url", Text: link.GetDisplayText(), URL: link.GetURL()}, true
case button.GetCallButton() != nil:
call := button.GetCallButton()
return BusinessButton{Type: "call", Text: call.GetDisplayText(), Phone: call.GetPhoneNumber()}, true
}
return BusinessButton{}, false
}
// BuildButtonsPayload returns the ButtonsMessage in msg as a webhook struct,
// or nil.
func BuildButtonsPayload(msg *waE2E.Message) *BusinessMessage {
bm := msg.GetButtonsMessage()
if bm == nil {
// Cloud API reply buttons, CTA and single-select arrive as a top-level
// InteractiveMessage. Without this branch they reached webhooks only as the
// text summary, and a client could not offer the buttons back.
if im := msg.GetInteractiveMessage(); im != nil {
if out := interactiveAsBusinessMessage(im); len(out.Buttons) > 0 || len(out.Cards) > 0 {
return out
}
}
return nil
}
out := &BusinessMessage{
Title: bm.GetText(),
Body: bm.GetContentText(),
Footer: bm.GetFooterText(),
}
switch {
case bm.GetImageMessage() != nil:
out.HeaderType = "image"
case bm.GetVideoMessage() != nil:
out.HeaderType = "video"
case bm.GetDocumentMessage() != nil:
out.HeaderType = "document"
case bm.GetLocationMessage() != nil:
out.HeaderType = "location"
}
for _, button := range bm.GetButtons() {
if info := button.GetNativeFlowInfo(); info != nil {
out.Buttons = append(out.Buttons, nativeFlowAsButton(info.GetName(), info.GetParamsJSON(), button.GetButtonID()))
continue
}
out.Buttons = append(out.Buttons, BusinessButton{
Type: "quick_reply",
Text: button.GetButtonText().GetDisplayText(),
ID: button.GetButtonID(),
})
}
return out
}
// interactiveAsBusinessMessage maps an InteractiveMessage — top-level or wrapped
// in a template — onto the same shape. Carousel cards are mapped recursively.
func interactiveAsBusinessMessage(im *waE2E.InteractiveMessage) *BusinessMessage {
header := im.GetHeader()
out := &BusinessMessage{
Title: header.GetTitle(),
Subtitle: header.GetSubtitle(),
HeaderType: interactiveHeaderType(header),
Body: im.GetBody().GetText(),
Footer: im.GetFooter().GetText(),
}
for _, button := range im.GetNativeFlowMessage().GetButtons() {
out.Buttons = append(out.Buttons, nativeFlowAsButton(button.GetName(), button.GetButtonParamsJSON(), ""))
}
for _, card := range im.GetCarouselMessage().GetCards() {
out.Cards = append(out.Cards, *interactiveAsBusinessMessage(card))
}
return out
}
func interactiveHeaderType(h *waE2E.InteractiveMessage_Header) string {
switch {
case h.GetImageMessage() != nil:
return "image"
case h.GetVideoMessage() != nil:
return "video"
case h.GetDocumentMessage() != nil:
return "document"
case h.GetLocationMessage() != nil:
return "location"
case h.GetProductMessage() != nil:
return "product"
}
return ""
}
func nativeFlowAsButton(name, paramsJSON, fallbackID string) BusinessButton {
var params nativeFlowButtonParams
_ = json.Unmarshal([]byte(paramsJSON), ¶ms)
text := cmp.Or(params.DisplayText, params.Title)
switch name {
case "cta_url":
return BusinessButton{Type: "url", Text: text, URL: params.URL}
case "cta_call":
return BusinessButton{Type: "call", Text: text, Phone: params.PhoneNumber}
case "cta_copy":
return BusinessButton{Type: "copy", Text: text, Code: params.Copy}
}
button := BusinessButton{Type: name, Text: text, ID: cmp.Or(params.ID, fallbackID)}
for _, section := range params.Sections {
for _, row := range section.Rows {
button.Rows = append(button.Rows, BusinessButtonRow{ID: row.ID, Title: row.Title, Description: row.Description})
}
}
return button
}
// BuildProductPayload returns the ProductMessage in msg as a webhook struct,
// or nil.
func BuildProductPayload(msg *waE2E.Message) *BusinessProduct {
pm := msg.GetProductMessage()
if pm == nil {
return nil
}
product := pm.GetProduct()
return &BusinessProduct{
ProductID: product.GetProductID(),
Title: product.GetTitle(),
Description: product.GetDescription(),
CurrencyCode: product.GetCurrencyCode(),
PriceAmount1000: product.GetPriceAmount1000(),
SalePriceAmount1000: product.GetSalePriceAmount1000(),
RetailerID: product.GetRetailerID(),
URL: product.GetURL(),
CatalogTitle: pm.GetCatalog().GetTitle(),
Body: pm.GetBody(),
Footer: pm.GetFooter(),
BusinessOwnerJID: pm.GetBusinessOwnerJID(),
}
}
// BuildSelectionPayload returns the list, buttons, template or native-flow
// reply in msg, or nil.
func BuildSelectionPayload(msg *waE2E.Message) *BusinessSelection {
switch {
case msg.GetListResponseMessage() != nil:
reply := msg.GetListResponseMessage()
return &BusinessSelection{
Kind: "list",
Text: reply.GetTitle(),
Description: reply.GetDescription(),
SelectedID: reply.GetSingleSelectReply().GetSelectedRowID(),
}
case msg.GetButtonsResponseMessage() != nil:
reply := msg.GetButtonsResponseMessage()
return &BusinessSelection{Kind: "buttons", Text: reply.GetSelectedDisplayText(), SelectedID: reply.GetSelectedButtonID()}
case msg.GetTemplateButtonReplyMessage() != nil:
reply := msg.GetTemplateButtonReplyMessage()
return &BusinessSelection{Kind: "template", Text: reply.GetSelectedDisplayText(), SelectedID: reply.GetSelectedID()}
case msg.GetInteractiveResponseMessage() != nil:
reply := msg.GetInteractiveResponseMessage()
var params nativeFlowButtonParams
_ = json.Unmarshal([]byte(reply.GetNativeFlowResponseMessage().GetParamsJSON()), ¶ms)
return &BusinessSelection{Kind: "interactive", Text: reply.GetBody().GetText(), SelectedID: params.ID}
}
return nil
}
// extractBusinessMessageText renders a business message, or a reply to one,
// as plain text. Messages without any text get a placeholder so they still
// show up in the chat instead of being skipped by storage.
func extractBusinessMessageText(msg *waE2E.Message) string {
if tm := templateMessage(msg); tm != nil {
if im := tm.GetInteractiveMessageTemplate(); im != nil {
return FormatInteractiveMessageSummary(im)
}
return cmp.Or(businessMessageLines(BuildTemplatePayload(msg)), "Template message")
}
if im := msg.GetInteractiveMessage(); im != nil {
return FormatInteractiveMessageSummary(im)
}
if buttons := BuildButtonsPayload(msg); buttons != nil {
return cmp.Or(businessMessageLines(buttons), "Buttons message")
}
if list := msg.GetListMessage(); list != nil {
title := list.GetTitle()
if title != "" {
title = "List: " + title
}
rendered := &BusinessMessage{Title: title, Body: list.GetDescription(), Footer: list.GetFooterText()}
for _, section := range list.GetSections() {
for _, row := range section.GetRows() {
rendered.Buttons = append(rendered.Buttons, BusinessButton{Text: row.GetTitle()})
}
}
return cmp.Or(businessMessageLines(rendered), "List message")
}
if product := BuildProductPayload(msg); product != nil {
line := "Product"
if product.Title != "" {
line += ": " + product.Title
}
if price := cmp.Or(product.SalePriceAmount1000, product.PriceAmount1000); price > 0 && product.CurrencyCode != "" {
line += fmt.Sprintf(" (%s %.2f)", product.CurrencyCode, float64(price)/1000)
}
return joinNonEmptyLines(line, product.Body, product.Footer)
}
if order := msg.GetOrderMessage(); order != nil {
title := order.GetOrderTitle()
if title != "" {
title = "Order: " + title
}
return cmp.Or(joinNonEmptyLines(title, order.GetMessage()), "Order message")
}
if selection := BuildSelectionPayload(msg); selection != nil {
text := cmp.Or(selection.Text, selection.Description)
// Recent clients send list and native-flow replies with only the id.
if text == "" && selection.SelectedID != "" {
text = "Selected option " + selection.SelectedID
}
return cmp.Or(text, "Selection message")
}
return ""
}
// businessMessageLines renders the rows, then one line per button: the same
// 🔗/📞/📋 lines as FormatInteractiveMessageSummary, other buttons as [label].
func businessMessageLines(message *BusinessMessage) string {
if message == nil {
return ""
}
parts := []string{message.Title, message.Body, message.Footer}
for _, button := range message.Buttons {
switch {
case button.Type == "url" && button.URL != "":
parts = append(parts, fmt.Sprintf("🔗 %s: %s", cmp.Or(button.Text, "Link"), button.URL))
case button.Type == "call" && button.Phone != "":
parts = append(parts, fmt.Sprintf("📞 %s: %s", cmp.Or(button.Text, "Call"), button.Phone))
case button.Type == "copy" && button.Code != "":
parts = append(parts, fmt.Sprintf("📋 %s: %s", cmp.Or(button.Text, "Copy code"), button.Code))
case button.Text != "" || button.Type != "":
parts = append(parts, fmt.Sprintf("[%s]", cmp.Or(button.Text, button.Type)))
}
}
return joinNonEmptyLines(parts...)
}
func joinNonEmptyLines(values ...string) string {
var lines []string
for _, value := range values {
if value != "" {
lines = append(lines, value)
}
}
return strings.Join(lines, "\n")
}
// FormatInteractiveMessageSummary renders an InteractiveMessage (business/
// Cloud API messages with native buttons: cta_url, cta_call, single/multi
// select, etc.) as plain text, since neither chat storage nor Chatwoot has a
// native concept of a WhatsApp interactive button. Buttons are described in
// buttonParamsJSON as a per-button-type JSON blob (undocumented,
// reverse-engineered from traffic), so only the fields relevant to rendering
// are decoded and anything unrecognized still shows the button's raw name.
const (
// interactiveSummaryMaxDepth stops nested carousels from walking a compact
// message forever. Real carousels are one level deep.
interactiveSummaryMaxDepth = 5
// interactiveSummaryMaxBytes caps the rendered summary so a wide or deep
// carousel cannot multiply a leaf into an unbounded allocation.
interactiveSummaryMaxBytes = 16 * 1024
)
func FormatInteractiveMessageSummary(im *waE2E.InteractiveMessage) string {
var b strings.Builder
writeInteractiveSummary(&b, im, 0, "")
if b.Len() == 0 {
return "Interactive message"
}
return b.String()
}
// writeInteractiveSummary appends into one builder. Nested card text is written
// once, with the "Card N: " prefix on its first line, instead of being copied
// into a new string at every ancestor.
func writeInteractiveSummary(b *strings.Builder, im *waE2E.InteractiveMessage, depth int, firstPrefix string) {
if im == nil || depth >= interactiveSummaryMaxDepth || b.Len() >= interactiveSummaryMaxBytes {
return
}
first := true
writePart := func(text string) {
if text == "" || b.Len() >= interactiveSummaryMaxBytes {
return
}
if first {
first = false
appendBoundedSummary(b, firstPrefix)
appendBoundedSummary(b, text)
return
}
appendBoundedSummary(b, "\n")
appendBoundedSummary(b, text)
}
if header := im.GetHeader(); header != nil {
writePart(header.GetTitle())
writePart(header.GetSubtitle())
// ExtractMediaCaption only handles top-level Get*Message() cases, not
// InteractiveMessage.Header — surface header captions here, since
// collectInteractiveMedia forwards the file itself but nothing else
// carries the caption text.
writePart(interactiveHeaderMediaCaption(header))
}
if body := im.GetBody(); body != nil {
writePart(body.GetText())
}
if footer := im.GetFooter(); footer != nil {
writePart(footer.GetText())
}
for _, button := range im.GetNativeFlowMessage().GetButtons() {
if b.Len() >= interactiveSummaryMaxBytes {
break
}
writePart(formatNativeFlowButton(button))
}
// Carousels put their CTA/quick-reply buttons on each card rather than on
// the top-level NativeFlowMessage, so the loop above sees none of them —
// summarize each card (itself a full InteractiveMessage) separately.
carousel := im.GetCarouselMessage()
if carousel == nil {
return
}
for i, card := range carousel.GetCards() {
if b.Len() >= interactiveSummaryMaxBytes || !interactiveSummaryHasContent(card, depth+1) {
continue
}
cardPrefix := fmt.Sprintf("Card %d: ", i+1)
if first {
first = false
writeInteractiveSummary(b, card, depth+1, firstPrefix+cardPrefix)
continue
}
appendBoundedSummary(b, "\n")
writeInteractiveSummary(b, card, depth+1, cardPrefix)
}
}
func interactiveSummaryHasContent(im *waE2E.InteractiveMessage, depth int) bool {
if im == nil || depth >= interactiveSummaryMaxDepth {
return false
}
if header := im.GetHeader(); header != nil {
if header.GetTitle() != "" || header.GetSubtitle() != "" || interactiveHeaderMediaCaption(header) != "" {
return true
}
}
if im.GetBody().GetText() != "" || im.GetFooter().GetText() != "" {
return true
}
// formatNativeFlowButton renders every non-nil button, so checking for one
// avoids parsing its params here.
for _, button := range im.GetNativeFlowMessage().GetButtons() {
if button != nil {
return true
}
}
if carousel := im.GetCarouselMessage(); carousel != nil {
for _, card := range carousel.GetCards() {
if interactiveSummaryHasContent(card, depth+1) {
return true
}
}
}
return false
}
func appendBoundedSummary(b *strings.Builder, text string) {
if text == "" || b.Len() >= interactiveSummaryMaxBytes {
return
}
remain := interactiveSummaryMaxBytes - b.Len()
if len(text) > remain {
// Back the cut up to a rune start so a multi-byte rune is not split.
// An invalid byte earlier in text does not move the cut.
cut := remain
for i := 0; i < utf8.UTFMax-1 && cut > 0 && !utf8.RuneStart(text[cut]); i++ {
cut--
}
text = text[:cut]
}
b.WriteString(text)
}
// interactiveHeaderMediaCaption returns the caption on whichever media type
// (if any) an InteractiveMessage header carries. Mirrors ExtractMediaCaption's
// per-type checks, scoped to the Header oneof instead of top-level Get*Message().
func interactiveHeaderMediaCaption(header *waE2E.InteractiveMessage_Header) string {
if header == nil {
return ""
}
if img := header.GetImageMessage(); img != nil {
return img.GetCaption()
}
if vid := header.GetVideoMessage(); vid != nil {
return vid.GetCaption()
}
if doc := header.GetDocumentMessage(); doc != nil {
return doc.GetCaption()
}
return ""
}
// nativeFlowButtonParams covers the fields used by the button types rendered
// specially (cta_url, cta_call, cta_copy), plus the id and single_select rows
// that nativeFlowAsButton exposes to webhooks. Other button names (e.g.
// review_and_pay) fall through to displaying the raw button name, since their
// params carry structured payment data that doesn't reduce to a single line.
type nativeFlowButtonParams struct {
DisplayText string `json:"display_text"`
URL string `json:"url"`
PhoneNumber string `json:"phone_number"`
Copy string `json:"copy_code"`
ID string `json:"id"`
Sections []struct {
Rows []struct {
ID string `json:"id"`
Title string `json:"title"`
Description string `json:"description"`
} `json:"rows"`
} `json:"sections"`
// Title is the visible label field used by picker-style buttons (e.g.
// single_select's {"title":...,"sections":...}), which don't set
// display_text at all.
Title string `json:"title"`
}
func formatNativeFlowButton(button *waE2E.InteractiveMessage_NativeFlowMessage_NativeFlowButton) string {
if button == nil {
return ""
}
name := button.GetName()
var params nativeFlowButtonParams
_ = json.Unmarshal([]byte(button.GetButtonParamsJSON()), ¶ms)
switch name {
case "cta_url":
label := params.DisplayText
if label == "" {
label = "Link"
}
if params.URL != "" {
return fmt.Sprintf("🔗 %s: %s", label, params.URL)
}
case "cta_call":
label := params.DisplayText
if label == "" {
label = "Call"
}
if params.PhoneNumber != "" {
return fmt.Sprintf("📞 %s: %s", label, params.PhoneNumber)
}
case "cta_copy":
label := params.DisplayText
if label == "" {
label = "Copy code"
}
if params.Copy != "" {
return fmt.Sprintf("📋 %s: %s", label, params.Copy)
}
}
label := params.DisplayText
if label == "" {
label = params.Title
}
if label != "" {
return fmt.Sprintf("[%s] %s", name, label)
}
return fmt.Sprintf("[%s]", name)
}