Enviar encuesta

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

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

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

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

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

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

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

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

string

requerido

Nombre de la instancia (p. ej., $Instance_Name).

Cabeceras

string

requerido

TokenAccount o TokenInstance.

string

requerido

application/json

Cuerpo de la solicitud

string

requerido

Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

string

requerido

Pregunta mostrada en la parte superior de la encuesta.

string[]

requerido

Lista de opciones. Mínimo 2, máximo 12 (límite de WhatsApp). Las cadenas duplicadas son aceptadas pero no recomendadas.

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.

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.

string

ID del mensaje a responder. El mensaje original debe pertenecer a la misma instancia y estar guardado en la base de datos.

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

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

HTTP	Status interno	Mensaje
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`

Envoltorio de error:

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

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Enviar encuesta

Descripción

Ejemplos

Encuesta simple (elección única)

Encuesta de elección múltiple

Encuesta como respuesta a un mensaje

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores

​Descripción

​Ejemplos

​Encuesta simple (elección única)

​Encuesta de elección múltiple

​Encuesta como respuesta a un mensaje

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

Descripción

Ejemplos

Encuesta simple (elección única)

Encuesta de elección múltiple

Encuesta como respuesta a un mensaje

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores