Enviar Enquete

POST

api

message

poll

:instance

Enviar Enquete

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

const options = {
  method: 'POST',
  headers: {token: '<token>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    number: '<string>',
    question: '<string>',
    options: ['<string>'],
    maxAnswer: 123,
    delay: 123,
    replyTo: '<string>',
    replyPrivate: true,
    source: '<string>'
  })
};

fetch('https://api.example.com/api/message/poll/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/message/poll/:instance"

payload = {
    "number": "<string>",
    "question": "<string>",
    "options": ["<string>"],
    "maxAnswer": 123,
    "delay": 123,
    "replyTo": "<string>",
    "replyPrivate": True,
    "source": "<string>"
}
headers = {
    "token": "<token>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não

Descrição

Envia uma enquete a um contato 1-a-1, grupo (@g.us) ou canal (@newsletter). Suporta de 2 a 12 opções (limite do WhatsApp). O campo maxAnswer controla quantas opções o usuário pode marcar: 1 (padrão) = escolha única; > 1 = múltipla escolha. Se maxAnswer for omitido, inválido (< 1) ou maior que len(options), o servidor normaliza automaticamente para 1 ou para o total de opções, respectivamente. Suporta delay, replyTo e replyPrivate.

Exemplos

Enquete simples (escolha única)

Cria uma enquete com três opções (09h, 14h, 16h) e maxAnswer implícito em 1, o respondente só pode marcar uma alternativa.

curl -X POST "https://ryzeapi.cloud/api/message/poll/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":   "5511999999999",
    "question": "Qual horário você prefere para a reunião?",
    "options":  ["09h", "14h", "16h"]
  }'

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: "Qual horário você prefere para a reunião?",
    options:  ["09h", "14h", "16h"]
  })
});

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": "Qual horário você prefere para a reunião?",
        "options":  ["09h", "14h", "16h"]
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "number":   "5511999999999",
        "question": "Qual horário você prefere para a reunião?",
        "options":  ["09h", "14h", "16h"]
    }`)
    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)
}

Enquete de múltipla escolha

maxAnswer: 3 permite que o respondente marque até três opções.

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":  "Quais linguagens você usa no dia a dia?",
    "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:  "Quais linguagens você usa no dia a dia?",
    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":  "Quais linguagens você usa no dia a dia?",
        "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":  "Quais linguagens você usa no dia a dia?",
        "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)
}

Enquete como resposta a uma mensagem

Cita uma mensagem existente via replyTo. A mensagem original precisa pertencer à mesma instância.

curl -X POST "https://ryzeapi.cloud/api/message/poll/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":   "5511999999999",
    "question": "Confirma o evento na data X?",
    "options":  ["Sim, confirmo", "Não posso", "Talvez"],
    "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: "Confirma o evento na data X?",
    options:  ["Sim, confirmo", "Não posso", "Talvez"],
    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": "Confirma o evento na data X?",
        "options":  ["Sim, confirmo", "Não posso", "Talvez"],
        "replyTo":  "3EB08FCF27E532F1B0F5",
        "delay":    2
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "number":   "5511999999999",
        "question": "Confirma o evento na data X?",
        "options":  ["Sim, confirmo", "Não posso", "Talvez"],
        "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)
}

Resposta de sucesso

O content retornado pré-formata a pergunta junto das opções numeradas (1. ... 2. ...), é a representação textual usada para indexar a enquete no histórico. O messageId é o que você precisa guardar para correlacionar votos via webhook.

200 OK

{
  "success": true,
  "message": "Poll sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1D3D3",
    "direction":   "sent",
    "messageType": "poll",
    "content":     "Qual horário você prefere para a reunião?\n\nOpções:\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": "minha-instancia"
    }
  }
}

Respostas dos participantes não chegam síncronamente nesta resposta, elas trafegam como eventos poll-update no webhook/WebSocket configurado, referenciando o messageId da enquete.

Parâmetros de rota

string

obrigatório

Nome da instância (ex.: $Instance_Name).

Headers

string

obrigatório

TokenAccount ou TokenInstance.

string

obrigatório

application/json

Request body

string

obrigatório

Destino: telefone (5511999999999) ou JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

string

obrigatório

Pergunta exibida no topo da enquete.

string[]

obrigatório

Lista de opções. Mínimo 2, máximo 12 (limite do WhatsApp). Strings duplicadas são aceitas, mas não recomendadas.

int

padrão:"1"

Número máximo de opções que o respondente pode marcar. 1 = escolha única; > 1 = múltipla escolha. Valores < 1 são normalizados para 1; valores maiores que len(options) são reduzidos ao tamanho da lista.

int

padrão:"0"

Tempo em segundos para aguardar antes de enviar. Durante o intervalo, o servidor envia o indicador de “digitando…” ao destinatário e dispara o “paused” antes do envio real.

string

ID da mensagem a ser citada (reply). A mensagem original precisa pertencer à mesma instância e ter sido salva no banco.

boolean

padrão:"false"

Quando true e replyTo aponta para uma mensagem originária de um grupo, a enquete é redirecionada para o privado do autor original (mantendo a citação).

string

padrão:"api"

Identificador de origem para rastreabilidade (ex.: crm, bot-suporte, n8n). Salvo no registro da mensagem e propagado para webhooks.

Notas

delay é em segundos (não milissegundos).
O WhatsApp aceita de 2 a 12 opções por enquete. Mais que isso é truncado pelo cliente do destinatário.
maxAnswer é normalizado pelo servidor: < 1 vira 1, e qualquer valor maior que len(options) cai para len(options).
Os votos não voltam nesta chamada, assine os eventos do webhook/WebSocket para receber poll-update quando alguém responder.
Em canais (@newsletter), enquetes podem ter comportamento limitado dependendo das permissões do canal.

Erros

HTTP	Status interno	Mensagem
400	,	`Instance name is required`
400	,	`Invalid request body: <detalhe>`
400	,	`Number is required`
400	,	`Question is required`
400	,	`At least 2 options are required`
400	`invalid_number`	`Invalid phone number format: <detalhe>`
404	,	`Instance not found`
500	`send_failed`	`Failed to send poll: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envelope de erro:

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

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Descrição

Exemplos

Enquete simples (escolha única)

Enquete de múltipla escolha

Enquete como resposta a uma mensagem

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros

​Descrição

​Exemplos

​Enquete simples (escolha única)

​Enquete de múltipla escolha

​Enquete como resposta a uma mensagem

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Notas

​Erros

Descrição

Exemplos

Enquete simples (escolha única)

Enquete de múltipla escolha

Enquete como resposta a uma mensagem

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros