Skip to main content

​
Overview

GOWA WhatsApp API provides comprehensive message sending capabilities including text messages with mentions, replies to specific messages, and message forwarding.

​
Text Messages

​
Basic Text Message

Send a simple text message to a WhatsApp number: 
curl -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "phone": "[email protected]",
    "message": "Hello from GOWA API!"
  }'
Phone numbers must be in international format without the + prefix. Use 628xxx instead of 08xxx for Indonesian numbers.

​
Reply to Message

Reply to a specific message using its message ID: 
{
  "phone": "[email protected]",
  "message": "Thanks for your message!",
  "reply_message_id": "3EB089B9D6ADD58153C561"
}
The API automatically fetches the original message from storage and includes proper reply context.

​
Forward Message

Mark a message as forwarded: 
{
  "phone": "[email protected]",
  "message": "Forwarded content",
  "is_forwarded": true
}
Forwarded messages display the forwarding indicator in WhatsApp client.

​
Mentions

GOWA supports two types of mentions:

​
Standard Mentions

Mention users by including @phone in the message text: 
{
  "phone": "[email protected]",
  "message": "Hello @628974812345, how are you?"
}
The API automatically parses phone numbers after @ and creates mention context.

​
Ghost Mentions

Mention users without showing @phone in the message text: 
{
  "phone": "[email protected]",
  "message": "Important announcement for the team",
  "mentions": ["628974812345", "628974812346"]
}

const response = await fetch('http://localhost:3000/send/message', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Device-Id': '[email protected]'
  },
  body: JSON.stringify({
    phone: '[email protected]',
    message: 'Team update',
    mentions: ['628974812345', '628974812346']
  })
});

​
Mention Everyone (@everyone)

Mention all participants in a group using the special @everyone keyword: 
{
  "phone": "[email protected]",
  "message": "Emergency meeting at 3 PM!",
  "mentions": ["@everyone"]
}
The @everyone mention only works in groups. The API automatically retrieves all group participants and mentions them.

​
Disappearing Messages

Send messages that auto-delete after a specified duration: 
{
  "phone": "[email protected]",
  "message": "This message will disappear in 24 hours",
  "duration": 86400
}
​
duration
integer
Duration in seconds. Valid values:
  • 0 — No expiry (disabled)
  • 86400 — 24 hours
  • 604800 — 7 days
  • 7776000 — 90 days

​
Other Message Types

​
Send Contact

Share a contact card: 
{
  "phone": "[email protected]",
  "contact_name": "John Doe",
  "contact_phone": "6289685024992"
}

​
Send Location

Share geographical coordinates: 
{
  "phone": "[email protected]",
  "latitude": "-7.797068",
  "longitude": "110.370529"
}
Send a URL with rich link preview: 
{
  "phone": "[email protected]",
  "link": "https://example.com",
  "caption": "Check out this website"
}
The API automatically fetches Open Graph metadata (title, description, image) from the URL.

​
Send Poll

Create a poll with multiple options: 
{
  "phone": "[email protected]",
  "question": "What's your favorite programming language?",
  "options": ["Python", "JavaScript", "Go", "Rust"],
  "max_answer": 1
}
​
max_answer
integer
Maximum number of answers a participant can select (1 to number of options).

​
Response Format

Successful message send returns: 
{
  "status": 200,
  "code": "SUCCESS",
  "message": "Message sent to [email protected] (server timestamp: 2024-03-04T10:30:00Z)",
  "results": {
    "message_id": "3EB0C127D7BACC83D6A1"
  }
}

​
Common Patterns

​
Combining Features

You can combine reply, mentions, and forwarding: 
{
  "phone": "[email protected]",
  "message": "Everyone please read this",
  "reply_message_id": "3EB089B9D6ADD58153C561",
  "mentions": ["@everyone"],
  "is_forwarded": true,
  "duration": 604800
}

​
Validation Rules

1

Phone Number Format

Must be in international format (no leading 0). Example: 628xxx not 08xxx.
2

Message Length

WhatsApp supports up to 65,536 characters per message.
3

Mention Format

  • Text mentions: @628974812345 (phone number only, no spaces)
  • Ghost mentions: Array of phone numbers without @ prefix
  • Special keyword: "@everyone" for group-wide mentions

​
Error Handling

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "phone number must be in international format (should not start with 0)"
}
Solution: Use 62xxx instead of 08xxx for Indonesian numbers.
If the reply_message_id doesn’t exist in storage, the API logs a warning and sends the message without reply context.Best Practice: Store message IDs from webhook events for reliable replies.
{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "duration must be one of: 0, 86400, 604800, 7776000"
}
Solution: Use only WhatsApp’s standard disappearing message durations.

​
Best Practices

Store Message IDs

Save message IDs from webhook events to enable reliable reply functionality.

Validate Phone Numbers

Always validate phone numbers are in international format before sending.

Handle Mentions Carefully

Use @everyone sparingly in large groups to avoid notification spam.

Test Disappearing Messages

Verify disappearing message behavior in test chats before production use.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us