Skip to main content
POST
/
api
/
message
/
poll
/
:instance
Send Poll
curl --request POST \
  --url https://api.example.com/api/message/poll/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "question": "<string>",
  "options": [
    "<string>"
  ],
  "maxAnswer": 123,
  "delay": 123,
  "replyTo": "<string>",
  "replyPrivate": true,
  "source": "<string>"
}
'
Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

​
Description

Sends a poll to a 1-to-1 contact, group (@g.us) or newsletter (@newsletter). Supports 2 to 12 options (WhatsApp limit). The maxAnswer field controls how many options the user can select: 1 (default) = single choice; > 1 = multiple choice. If maxAnswer is omitted, invalid (< 1) or larger than len(options), the server normalizes it automatically to 1 or to the total number of options, respectively. Supports delay, replyTo and replyPrivate.

​
Examples

​
Simple poll (single choice)

Creates a poll with three options (9am, 2pm, 4pm) and maxAnswer implicitly set to 1, the respondent can only pick one. 
curl -X POST "https://ryzeapi.cloud/api/message/poll/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":   "5511999999999",
    "question": "Which time works best for the meeting?",
    "options":  ["9am", "2pm", "4pm"]
  }'

​
Multiple-choice poll

maxAnswer: 3 lets the respondent pick up to three options. 
curl -X POST "https://ryzeapi.cloud/api/message/poll/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":    "120363406289005073@g.us",
    "question":  "Which languages do you use day-to-day?",
    "options":   ["Go", "Python", "JavaScript", "TypeScript", "Rust", "Java"],
    "maxAnswer": 3
  }'

​
Poll as a reply to a message

Quotes an existing message via replyTo. The original message must belong to the same instance. 
curl -X POST "https://ryzeapi.cloud/api/message/poll/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":   "5511999999999",
    "question": "Are you confirming the event on date X?",
    "options":  ["Yes, confirmed", "Can't make it", "Maybe"],
    "replyTo":  "3EB08FCF27E532F1B0F5",
    "delay":    2
  }'

​
Success response

The returned content pre-formats the question alongside the numbered options (1. ... 2. ...), it’s the textual representation used to index the poll in the history. The messageId is what you need to keep around to correlate votes received via webhook.
200 OK
{
  "success": true,
  "message": "Poll sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1D3D3",
    "direction":   "sent",
    "messageType": "poll",
    "content":     "Which time works best for the meeting?\n\nOptions:\n1. 14:00\n2. 15:00\n3. 16:00\n",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "my-instance"
    }
  }
}
Participant responses don’t arrive synchronously in this response, they flow as poll-update events on the configured webhook/WebSocket, referencing the poll’s messageId.

​
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).
​
question
string
required
Question shown at the top of the poll.
​
options
string[]
required
List of options. Minimum 2, maximum 12 (WhatsApp limit). Duplicate strings are accepted but not recommended.
​
maxAnswer
int
default:"1"
Maximum number of options the respondent can select. 1 = single choice; > 1 = multiple choice. Values < 1 are normalized to 1; values larger than len(options) are clamped to the list size.
​
delay
int
default:"0"
Time in seconds to wait before sending. During the interval, the server shows the “typing…” indicator to the recipient and triggers “paused” before the actual send.
​
replyTo
string
ID of the message to reply to. The original message must belong to the same instance and be saved in the database.
​
replyPrivate
boolean
default:"false"
When true and replyTo points to a message originating from a group, the poll is redirected to the private chat of the original author (keeping the quote).
​
source
string
default:"api"
Origin identifier for traceability (e.g., crm, support-bot, n8n). Saved on the message record and propagated to webhooks.

​
Notes

  • delay is in seconds (not milliseconds).
  • WhatsApp accepts 2 to 12 options per poll. Anything more is truncated by the recipient’s client.
  • maxAnswer is normalized by the server: < 1 becomes 1, and any value larger than len(options) falls back to len(options).
  • Votes don’t come back in this call, subscribe to webhook/WebSocket events to receive poll-update when someone votes.
  • On newsletters (@newsletter), polls may have limited behavior depending on channel permissions.

​
Errors

HTTPInternal statusMessage
400,Instance name is required
400,Invalid request body: <detail>
400,Number is required
400,Question is required
400,At least 2 options are required
400invalid_numberInvalid phone number format: <detail>
404,Instance not found
500send_failedFailed to send poll: <reason>
503disconnectedInstance is not connected to WhatsApp
Error envelope: 
{
  "success": false,
  "error": { "message": "At least 2 options are required" }
}