Skip to main content
Send a text message to a WhatsApp number or group. Supports replies, forwarding, disappearing messages, and mentions.
This endpoint supports both regular text messages and advanced features like ghost mentions and @everyone mentions for groups.

​
Endpoint

POST /send/message

​
Headers

​
X-Device-Id
string
Device identifier for multi-device support. Required when multiple devices are registered. If only one device is registered, it will be used as the default. Can also be provided as device_id query parameter.

​
Request Body

​
phone
string
required
Phone number with country code and WhatsApp suffix.Format: {country_code}{phone_number}@s.whatsapp.netExample: [email protected]
​
message
string
required
The text message content to send.Example: "Hello, how are you?"
​
reply_message_id
string
Message ID to reply to. Use this to create a quoted reply to a previous message.Example: "3EB089B9D6ADD58153C561"
​
is_forwarded
boolean
default:false
Mark the message as forwarded. When set to true, the message will display a “Forwarded” label.
​
duration
integer
Disappearing message duration in seconds. The message will automatically delete after this duration.Common values:
  • 86400 - 24 hours
  • 604800 - 7 days
  • 7776000 - 90 days
Example: 3600 (1 hour)
​
mentions
array
List of phone numbers to mention (ghost mentions - no @ required in message text). Use special keyword "@everyone" to mention all group participants.Format: Array of phone numbers (without country code prefix or @s.whatsapp.net suffix)Examples:
  • ["628123456789", "628987654321"] - Mention specific users
  • ["@everyone"] - Mention all group members
Ghost mentions allow you to mention users without including ”@” in the message text. The mentioned users will still receive a notification.

​
Response

​
code
string
Response status code. Returns "SUCCESS" on successful message send.
​
message
string
Human-readable response message.
​
results
object
​
message_id
string
Unique identifier for the sent message. Use this ID for message operations like revoke, react, or delete.Example: "3EB0B430B6F8F1D0E053AC120E0A9E5C"
​
status
string
Detailed status message about the send operation.

​
Code Examples

curl -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: my-device" \
  -d '{
    "phone": "[email protected]",
    "message": "Hello! This is a test message."
  }'

​
Response Example

{
  "code": "SUCCESS",
  "message": "Success",
  "results": {
    "message_id": "3EB0B430B6F8F1D0E053AC120E0A9E5C",
    "status": "Message sent successfully"
  }
}

​
Error Responses

​
400
Bad Request
Invalid request parameters. Check that phone number format is correct and required fields are provided.
​
500
Internal Server Error
Server error or device not connected. Ensure the device is logged in and connected to WhatsApp.

​
Features

​
Ghost Mentions

Ghost mentions allow you to notify specific users without displaying the ”@” symbol in the message text: 
{
  "phone": "[email protected]",
  "message": "Hey team, please check the latest update!",
  "mentions": ["628123456789", "628987654321"]
}
The mentioned users will receive a notification, but the message text appears normal without @ symbols.

​
@everyone Mention

Mention all participants in a group chat: 
{
  "phone": "[email protected]",
  "message": "Important: Meeting at 3 PM today!",
  "mentions": ["@everyone"]
}
All group members will receive a notification for this message.

​
Disappearing Messages

Send messages that automatically delete after a specified duration: 
{
  "phone": "[email protected]",
  "message": "Sensitive information here",
  "duration": 86400
}
Common duration values:
  • 24 hours: 86400 seconds
  • 7 days: 604800 seconds
  • 90 days: 7776000 seconds
Disappearing messages require both sender and recipient to have this feature supported in their WhatsApp client.

​
Best Practices

  1. Phone Number Format: Always include the country code and @s.whatsapp.net suffix for individual chats, or @g.us for groups.
  2. Message Length: WhatsApp supports messages up to 65,536 characters, but keep messages concise for better user experience.
  3. Rate Limiting: Implement rate limiting to avoid being flagged for spam. WhatsApp may temporarily ban accounts sending too many messages.
  4. Error Handling: Always check the response status and implement retry logic for failed messages.
  5. Mentions: Use ghost mentions sparingly. Overusing mentions can annoy users and may be considered spam.

Build docs developers (and LLMs) love

Get started for freeTalk to us