Send Poll

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"]
  }'

await fetch(`https://ryzeapi.cloud/api/message/poll/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:   "5511999999999",
    question: "Which time works best for the meeting?",
    options:  ["9am", "2pm", "4pm"]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/poll/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":   "5511999999999",
        "question": "Which time works best for the meeting?",
        "options":  ["9am", "2pm", "4pm"]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":   "5511999999999",
        "question": "Which time works best for the meeting?",
        "options":  ["9am", "2pm", "4pm"]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/poll/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch(`https://ryzeapi.cloud/api/message/poll/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:    "120363406289005073@g.us",
    question:  "Which languages do you use day-to-day?",
    options:   ["Go", "Python", "JavaScript", "TypeScript", "Rust", "Java"],
    maxAnswer: 3
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/poll/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":    "120363406289005073@g.us",
        "question":  "Which languages do you use day-to-day?",
        "options":   ["Go", "Python", "JavaScript", "TypeScript", "Rust", "Java"],
        "maxAnswer": 3
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":    "120363406289005073@g.us",
        "question":  "Which languages do you use day-to-day?",
        "options":   ["Go", "Python", "JavaScript", "TypeScript", "Rust", "Java"],
        "maxAnswer": 3
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/poll/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch(`https://ryzeapi.cloud/api/message/poll/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:   "5511999999999",
    question: "Are you confirming the event on date X?",
    options:  ["Yes, confirmed", "Can't make it", "Maybe"],
    replyTo:  "3EB08FCF27E532F1B0F5",
    delay:    2
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/poll/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":   "5511999999999",
        "question": "Are you confirming the event on date X?",
        "options":  ["Yes, confirmed", "Can't make it", "Maybe"],
        "replyTo":  "3EB08FCF27E532F1B0F5",
        "delay":    2
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":   "5511999999999",
        "question": "Are you confirming the event on date X?",
        "options":  ["Yes, confirmed", "Can't make it", "Maybe"],
        "replyTo":  "3EB08FCF27E532F1B0F5",
        "delay":    2
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/poll/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

string

required

Instance name (e.g., $Instance_Name).

Headers

string

required

TokenAccount or TokenInstance.

string

required

application/json

Request body

string

required

Destination: phone (5511999999999) or JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

string

required

Question shown at the top of the poll.

string[]

required

List of options. Minimum 2, maximum 12 (WhatsApp limit). Duplicate strings are accepted but not recommended.

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.

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.

string

ID of the message to reply to. The original message must belong to the same instance and be saved in the database.

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).

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

HTTP	Internal status	Message
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`
400	`invalid_number`	`Invalid phone number format: <detail>`
404	,	`Instance not found`
500	`send_failed`	`Failed to send poll: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Error envelope:

{
  "success": false,
  "error": { "message": "At least 2 options are required" }
}

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

Simple poll (single choice)

Multiple-choice poll

Poll as a reply to a message

Success response

Path parameters

Headers

Request body

Notes

Errors

​Description

​Examples

​Simple poll (single choice)

​Multiple-choice poll

​Poll as a reply to a message

​Success response

​Path parameters

​Headers

​Request body

​Notes

​Errors

Description

Examples

Simple poll (single choice)

Multiple-choice poll

Poll as a reply to a message

Success response

Path parameters

Headers

Request body

Notes

Errors