Messaging & Communication Tools - GOWA - Go WhatsApp Web Multi-Device API

Overview

Messaging tools allow AI agents to send various types of content to WhatsApp contacts and groups. All messaging tools support forwarding and reply features.

Before using messaging tools, ensure you are authenticated and connected to WhatsApp.

whatsapp_send_text

Send a text message to a WhatsApp contact or group. Supports ghost mentions (mention users without showing @phone in message text).

Parameters

Parameter	Type	Required	Description
`phone`	string	Yes	Phone number or group ID (e.g., `628123456789` or `[email protected]`)
`message`	string	Yes	The text message to send
`is_forwarded`	boolean	No	Whether this message is being forwarded (default: `false`)
`reply_message_id`	string	No	Message ID to reply to (optional)
`mentions`	array	No	Phone numbers or JIDs to mention (ghost mentions). Use `"@everyone"` to mention all group participants

Ghost Mentions

Ghost mentions allow you to notify users without showing @phone in the message text:

{
  "phone": "[email protected]",
  "message": "Hello everyone, please read this announcement",
  "mentions": ["628123456789", "628987654321"]
}

The message displays normally, but the specified users receive a mention notification.

Mention Everyone

Use the special keyword @everyone to mention all group participants:

{
  "phone": "[email protected]",
  "message": "Important: Meeting at 3 PM",
  "mentions": ["@everyone"]
}

Returns

{
  "message_id": "3EB0C767E8D4B2A9E4C3"
}

Fallback text: "Message sent successfully with ID 3EB0C767E8D4B2A9E4C3"

Example Usage

Simple Message
Reply to Message
Mention Everyone

Send a WhatsApp message to 628123456789 saying "Hello from AI!"

Reply to message 3EB0C767E8D4B2A9E4C3 in chat 628123456789 with "Thanks for the update"

Send a message to group [email protected] saying "Meeting starts now" and mention everyone

Implementation Reference

Source: src/ui/mcp/send.go:33-109

whatsapp_send_contact

Send a contact card to a WhatsApp contact or group.

Parameters

Parameter	Type	Required	Description
`phone`	string	Yes	Recipient phone number or group ID
`contact_name`	string	Yes	Name of the contact to send
`contact_phone`	string	Yes	Phone number of the contact to send
`is_forwarded`	boolean	No	Whether this is a forwarded contact (default: `false`)

Returns

{
  "message_id": "3EB0C767E8D4B2A9E4C4"
}

Fallback text: "Contact sent successfully with ID 3EB0C767E8D4B2A9E4C4"

Example Usage

Send contact card for "John Doe" (+1234567890) to 628123456789

Implementation Reference

Source: src/ui/mcp/send.go:111-174

whatsapp_send_link

Send a link with caption to a WhatsApp contact or group.

Parameters

Parameter	Type	Required	Description
`phone`	string	Yes	Recipient phone number or group ID
`link`	string	Yes	URL link to send
`caption`	string	Yes	Caption or description for the link
`is_forwarded`	boolean	No	Whether this is a forwarded link (default: `false`)

Returns

{
  "message_id": "3EB0C767E8D4B2A9E4C5"
}

Fallback text: "Link sent successfully with ID 3EB0C767E8D4B2A9E4C5"

Example Usage

AI Assistant
Direct MCP

Send link https://example.com to 628123456789 with caption "Check this out!"

{
  "name": "whatsapp_send_link",
  "arguments": {
    "phone": "628123456789",
    "link": "https://example.com",
    "caption": "Interesting article"
  }
}

Implementation Reference

Source: src/ui/mcp/send.go:176-239

whatsapp_send_location

Send location coordinates to a WhatsApp contact or group.

Parameters

Parameter	Type	Required	Description
`phone`	string	Yes	Recipient phone number or group ID
`latitude`	string	Yes	Latitude coordinate (as string, e.g., `"-6.200000"`)
`longitude`	string	Yes	Longitude coordinate (as string, e.g., `"106.816666"`)
`is_forwarded`	boolean	No	Whether this is a forwarded location (default: `false`)

Returns

{
  "message_id": "3EB0C767E8D4B2A9E4C6"
}

Fallback text: "Location sent successfully with ID 3EB0C767E8D4B2A9E4C6"

Example Usage

Send location -6.200000, 106.816666 to 628123456789

Coordinates must be provided as strings, not numbers. This is a quirk of the underlying WhatsApp protocol implementation.

Implementation Reference

Source: src/ui/mcp/send.go:241-304

whatsapp_send_image

Send an image to a WhatsApp contact or group.

Parameters

Parameter	Type	Required	Description
`phone`	string	Yes	Recipient phone number or group ID
`image_url`	string	Yes	URL of the image to send (HTTPS recommended)
`caption`	string	No	Caption or description for the image
`view_once`	boolean	No	Whether this image should be viewed only once (default: `false`)
`compress`	boolean	No	Whether to compress the image (default: `true`)
`is_forwarded`	boolean	No	Whether this is a forwarded image (default: `false`)

Image Compression

When compress: true (default):

Images are compressed to reduce file size
Quality is optimized for WhatsApp delivery
Faster upload and download for recipients

When compress: false:

Original image quality is preserved
Larger file size
May take longer to send/receive

View Once

When view_once: true:

Image is deleted from chat after recipient views it
Cannot be saved, forwarded, or screenshot (WhatsApp enforces this)
Useful for sensitive images

Returns

{
  "message_id": "3EB0C767E8D4B2A9E4C7"
}

Fallback text: "Image sent successfully with ID 3EB0C767E8D4B2A9E4C7"

Example Usage

Simple Image
With Caption
View Once

Send image https://example.com/photo.jpg to 628123456789

Send image https://example.com/photo.jpg to 628123456789 with caption "Beautiful sunset"

Send view-once image https://example.com/sensitive.jpg to 628123456789

Implementation Reference

Source: src/ui/mcp/send.go:306-389

whatsapp_send_sticker

Send a sticker to a WhatsApp contact or group. Images are automatically converted to WebP sticker format.

Parameters

Parameter	Type	Required	Description
`phone`	string	Yes	Recipient phone number or group ID
`sticker_url`	string	Yes	URL of the image to convert to sticker
`is_forwarded`	boolean	No	Whether this is a forwarded sticker

Supported Image Formats

GOWA automatically converts the following formats to WebP stickers:

JPG / JPEG
PNG (transparency preserved)
WebP (static)
GIF (converted to static WebP)

Animated Stickers

Animated WebP stickers are supported but must meet WhatsApp’s requirements:

Exactly 512x512 pixels
Under 500KB file size
Maximum 10 seconds duration

If your animated sticker doesn’t meet these requirements, WhatsApp will reject it. Use a tool like ezgif.com to resize before sending.

Returns

{
  "message_id": "3EB0C767E8D4B2A9E4C8"
}

Fallback text: "Sticker sent successfully with ID 3EB0C767E8D4B2A9E4C8"

Example Usage

From Image URL
Animated Sticker

Send sticker from https://example.com/image.png to 628123456789

Send animated sticker from https://example.com/animated.webp to 628123456789

Conversion Process

Download image from sticker_url
Resize to 512x512 pixels
Convert to WebP format
Send as WhatsApp sticker

Implementation Reference

Source: src/ui/mcp/send.go:391-444

Common Parameters

Phone Number Format

All messaging tools accept phone parameter in these formats:

Format	Example	Description
Raw number	`628123456789`	Preferred for individual chats
JID	`[email protected]`	WhatsApp JID format
Group JID	`[email protected]`	Group chat identifier

You don’t need to include the @s.whatsapp.net suffix for individual numbers. GOWA will add it automatically.

Forward Flag

All messaging tools support the is_forwarded boolean:

{
  "is_forwarded": true
}

When true, the message displays with a “Forwarded” label in WhatsApp.

Error Handling

Common Errors

Error	Cause	Solution
`phone must be a string`	Missing or invalid phone parameter	Provide valid phone number
`message must be a string`	Missing or invalid message parameter	Provide message text
`not logged in`	WhatsApp session not authenticated	Login using `whatsapp_login_qr`
`recipient not found`	Invalid phone number or group ID	Verify the phone number exists
`media download failed`	Invalid URL or network error	Check URL is accessible

Best Practices

Check connection first: Call whatsapp_connection_status before sending messages
Validate phone numbers: Ensure phone numbers are in correct format
Use ghost mentions: For group notifications, use mentions array instead of @phone in text
Compress large images: Enable compression for faster delivery
Handle errors gracefully: Implement retry logic for network failures
Respect rate limits: WhatsApp may rate-limit excessive messaging

Rate Limiting

WhatsApp enforces rate limits on message sending:

Individual chats: ~20 messages per minute
Group chats: ~10 messages per minute
Media: Slower rate limits apply

Exceeding these limits may result in temporary bans. Implement delays between messages for bulk operations.

Overview

Available Tools

​Overview

​whatsapp_send_text

​Parameters

​Ghost Mentions

​Mention Everyone

​Returns

​Example Usage

​Implementation Reference

​whatsapp_send_contact

​Parameters

​Returns

​Example Usage

​Implementation Reference

​whatsapp_send_link

​Parameters

​Returns

​Example Usage

​Implementation Reference

​whatsapp_send_location

​Parameters

​Returns

​Example Usage

​Implementation Reference

​whatsapp_send_image

​Parameters

​Image Compression

​View Once

​Returns

​Example Usage

​Implementation Reference

​whatsapp_send_sticker

​Parameters

​Supported Image Formats

​Animated Stickers

​Returns

​Example Usage

​Conversion Process

​Implementation Reference

​Common Parameters

​Phone Number Format

​Forward Flag

​Error Handling

​Common Errors

​Best Practices

​Rate Limiting

​Next Steps

Contacts & Chats

Group Management

Build docs developers (and LLMs) love

Overview

whatsapp_send_text

Parameters

Ghost Mentions

Mention Everyone

Returns

Example Usage

Implementation Reference

whatsapp_send_contact

Parameters

Returns

Example Usage

Implementation Reference

whatsapp_send_link

Parameters

Returns

Example Usage

Implementation Reference

whatsapp_send_location

Parameters

Returns

Example Usage

Implementation Reference

whatsapp_send_image

Parameters

Image Compression

View Once

Returns

Example Usage

Implementation Reference

whatsapp_send_sticker

Parameters

Supported Image Formats

Animated Stickers

Returns

Example Usage

Conversion Process

Implementation Reference

Common Parameters

Phone Number Format

Forward Flag

Error Handling

Common Errors

Best Practices

Rate Limiting

Next Steps