Saltar al contenido principal
POST
/
api
/
message
/
poll
/
:instance
Enviar encuesta
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 o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no

​
Descripción

Envía una encuesta a un contacto 1-a-1, grupo (@g.us) o newsletter (@newsletter). Soporta de 2 a 12 opciones (límite de WhatsApp). El campo maxAnswer controla cuántas opciones puede seleccionar el usuario: 1 (default) = elección única; > 1 = elección múltiple. Si maxAnswer se omite, es inválido (< 1) o mayor que len(options), el servidor lo normaliza automáticamente a 1 o al número total de opciones, respectivamente. Soporta delay, replyTo y replyPrivate.

​
Ejemplos

​
Encuesta simple (elección única)

Crea una encuesta con tres opciones (9am, 2pm, 4pm) y maxAnswer establecido implícitamente en 1, el respondente solo puede elegir una. 
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"]
  }'

​
Encuesta de elección múltiple

maxAnswer: 3 permite que el respondente elija hasta tres opciones. 
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
  }'

​
Encuesta como respuesta a un mensaje

Cita un mensaje existente vía replyTo. El mensaje original debe pertenecer a la misma instancia. 
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
  }'

​
Respuesta exitosa

El content retornado preformatea la pregunta junto con las opciones numeradas (1. ... 2. ...), es la representación textual usada para indexar la encuesta en el historial. El messageId es lo que necesitas mantener para correlacionar los votos recibidos vía 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"
    }
  }
}
Las respuestas de los participantes no llegan sincrónicamente en esta respuesta, fluyen como eventos poll-update en el webhook/WebSocket configurado, referenciando el messageId de la encuesta.

​
Parámetros de ruta

​
instance
string
requerido
Nombre de la instancia (p. ej., $Instance_Name).

​
Cabeceras

​
token
string
requerido
TokenAccount o TokenInstance.
​
Content-Type
string
requerido
application/json

​
Cuerpo de la solicitud

​
number
string
requerido
Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
question
string
requerido
Pregunta mostrada en la parte superior de la encuesta.
​
options
string[]
requerido
Lista de opciones. Mínimo 2, máximo 12 (límite de WhatsApp). Las cadenas duplicadas son aceptadas pero no recomendadas.
​
maxAnswer
int
predeterminado:"1"
Número máximo de opciones que el respondente puede seleccionar. 1 = elección única; > 1 = elección múltiple. Los valores < 1 se normalizan a 1; los valores mayores que len(options) se limitan al tamaño de la lista.
​
delay
int
predeterminado:"0"
Tiempo en segundos a esperar antes de enviar. Durante el intervalo, el servidor muestra el indicador “escribiendo…” al destinatario y dispara “pausado” antes del envío real.
​
replyTo
string
ID del mensaje a responder. El mensaje original debe pertenecer a la misma instancia y estar guardado en la base de datos.
​
replyPrivate
boolean
predeterminado:"false"
Cuando es true y replyTo apunta a un mensaje originado en un grupo, la encuesta se redirige al chat privado del autor original (manteniendo la cita).
​
source
string
predeterminado:"api"
Identificador de origen para trazabilidad (p. ej., crm, support-bot, n8n). Guardado en el registro del mensaje y propagado a los webhooks.

​
Notas

  • delay es en segundos (no milisegundos).
  • WhatsApp acepta de 2 a 12 opciones por encuesta. Cualquier cantidad mayor es truncada por el cliente del destinatario.
  • maxAnswer es normalizado por el servidor: < 1 se convierte en 1, y cualquier valor mayor que len(options) cae a len(options).
  • Los votos no regresan en esta llamada, suscríbete a eventos de webhook/WebSocket para recibir poll-update cuando alguien vote.
  • En newsletters (@newsletter), las encuestas pueden tener comportamiento limitado dependiendo de los permisos del canal.

​
Errores

HTTPStatus internoMensaje
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
Envoltorio de error: 
{
  "success": false,
  "error": { "message": "At least 2 options are required" }
}