Skip to main content
POST
/
api
/
message
/
text
/
:instance
Send Text
curl --request POST \
  --url https://api.example.com/api/message/text/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "message": "<string>",
  "delay": 123,
  "linkPreview": true,
  "replyTo": "<string>",
  "replyPrivate": true,
  "mention": [
    "<string>"
  ],
  "mentionAll": true,
  "source": "<string>"
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

​
Description

Sends a text message to a 1-on-1 contact, group (@g.us) or channel (@newsletter). Supports replyTo (quote by ID), replyPrivate (reply privately to a group message), mention / mentionAll (group chats only), linkPreview and delay (in seconds) to simulate real typing. It is the most-used endpoint and serves as a “Hello World” to validate that the instance is connected.

​
Examples

​
Minimum

Sends a text message with the minimum payload (number + message). No delay, no preview, no quoting, useful as a “Hello World” to validate that the instance is connected. 
curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":  "5511999999999",
    "message": "Hello! This is a test of RyzeAPI."
  }'
Sends a “typing…” indicator for 3 seconds and then sends the message with a preview of the detected URL. 
curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "message":     "Check this out: https://ryzeapi.cloud",
    "delay":       3,
    "linkPreview": true
  }'

​
As a reply

Quotes an existing message (replyTo receives the messageId of the original). The original message must belong to the same instance and have been saved in the database (any message that flows through webhook/send is saved automatically). 
curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":  "5511999999999",
    "message": "Yes, confirmed!",
    "replyTo": "3EB08FCF27E532F1B0F5"
  }'

​
As a private reply (from a group)

When someone sends a message in a group and you want to reply privately to that person (without sending the reply back to the group), use replyPrivate: true. The number should point to the JID of the group where the original message was sent, the server extracts the original author and redirects the reply to their private chat, keeping the quote. 
curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":       "120363406289005073@g.us",
    "message":      "Replying to you privately so we don't clutter the group.",
    "replyTo":      "3EB08FCF27E532F1B0F5",
    "replyPrivate": true
  }'

​
With member mention(s) (group)

Adds visible mentions with @5511... in the message body and lists the numbers in the mention array. The text and the array must be consistent, WhatsApp only turns into a clickable link what is in mention. 
curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":  "120363406289005073@g.us",
    "message": "Heads up @5511888888888 and @5511777777777, meeting at 2pm.",
    "mention": ["5511888888888", "5511777777777"]
  }'

​
Hidden mention (group)

Pings every member of the group without listing @s in the text, using mentionAll: true. The displayed text stays clean, but the participants receive the mention notification. Useful for silent announcements. To mention specific people in a hidden way, just use mention: ["..."] without placing @number in the text, they will also receive the notification without appearing tagged. 
curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":     "120363406289005073@g.us",
    "message":    "General notice: meeting confirmed for tomorrow at 2pm.",
    "mentionAll": true
  }'

​
Success response

The response includes the messageId (use it in replyTo to quote this message in future sends), direction: "outgoing" and the chat/sender markers. The mentions and replyTo fields only appear when applicable, and chat.groupName is included in group messages.
200 OK
{
  "success": true,
  "message": "Message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "outgoing",
    "messageType": "text",
    "content":     "Hello! This is a test of RyzeAPI.",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    },
    "mentions": {
      "mentionedUsers": ["5511888888888"],
      "mentionAll":     false,
      "totalMentions":  1
    },
    "replyTo": {
      "messageId": "3EB08FCF27E532F1A1A1",
      "content":   "Are we good for tomorrow?"
    }
  }
}

​
Path parameters

​
instance
string
required
Instance name (e.g., $Instance_Name).

​
Headers

​
token
string
required
TokenAccount or TokenInstance.
​
Content-Type
string
required
application/json

​
Request body

​
number
string
required
Destination: phone (5511999999999) or JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
message
string
required
Body text. Cannot be empty.
​
delay
int
default:"0"
Time in seconds to wait before sending. During the interval, the server sends the “typing…” indicator to the recipient and fires “paused” before the actual send.
​
linkPreview
boolean
default:"false"
When true, the server extracts the first URL from message, fetches Open Graph metadata (title, description, thumbnail) and sends the message as ExtendedTextMessage with the preview card embedded. When false or omitted, the URL appears as plain text.
​
replyTo
string
ID of the message to be quoted (reply). The original message must belong to the same instance and have been saved in the database. Possible errors: reply_message_not_found, reply_message_instance_mismatch.
​
replyPrivate
boolean
default:"false"
When true and replyTo points to a message originating from a group, the reply is redirected to the original author’s private chat (keeping the quote). Useful for answering questions individually without cluttering the group. Ignored if the original message is not from a group.
​
mention
string[]
List of numbers (or JIDs) to mention. Group chats only (@g.us). Limit of 10 mentions per message; excess numbers are ignored with a warning. To appear as a clickable link, include @5511... in message. Without that, they become hidden mentions (notify only).
​
mentionAll
boolean
default:"false"
When true, mentions every group member (except the instance itself). Equivalent to @everyone. The server queries the participants list and injects each JID into the context’s MentionedJID, without changing the displayed text. Group chats only.
​
source
string
default:"api"
Origin identifier for traceability (e.g., crm, bot-suporte, n8n). Saved on the message record in the database and propagated to webhooks. When omitted, defaults to "api".

​
Notes

  • delay is in seconds (unlike many APIs that use ms). A value of 3 = 3 seconds of “typing”.
  • In groups, text with @5511... alone does not become clickable, it is the mention array that WhatsApp processes. Keep both consistent.
  • mention and mentionAll are exclusive to groups. If sent to a DM/channel, the response is 400 Mentions are only supported in group chats.
  • For BR numbers (starting with 55), the service automatically tries variations with and without the 9th digit, avoiding the long-standing inconsistency in older area codes.
  • linkPreview requires that the server be able to fetch the URL’s Open Graph metadata; sites with bot blocking may fall back to plain text without a visible error.
  • Messages sent via replyPrivate: true appear in the recipient’s private chat with the card of the quoted group message, they can see which conversation it came from.

​
Errors

HTTPInternal statusMessage
400—Instance name is required
400—Invalid request body: <detail>
400—Number is required
400—Message is required
400invalid_numberInvalid phone number format: <detail>
400mentions_not_supportedMentions are only supported in group chats
400reply_message_not_foundOriginal message not found (ID: ...)
400reply_message_instance_mismatchOriginal message does not belong to this instance
400private_reply_failed(reason for the private redirection error)
404—Instance not found
500send_failedFailed to send message: <reason>
503disconnectedInstance is not connected to WhatsApp
Error envelope: 
{
  "success": false,
  "error": { "message": "Message is required" }
}