Send Poll

Send an interactive poll (vote) to a WhatsApp number or group. Recipients can select one or multiple options based on the poll configuration.

Polls are interactive messages that allow recipients to vote on options. They’re perfect for gathering opinions, making group decisions, or conducting quick surveys.

Endpoint

POST /send/poll

Headers

X-Device-Id

string

Device identifier for multi-device support. Required when multiple devices are registered.

Content-Type

string

required

Must be application/json.

Request Body

phone

string

required

Phone number with country code and WhatsApp suffix.Format: {country_code}{phone_number}@s.whatsapp.netExample: [email protected]

question

string

required

The poll question. This is the main text that recipients will see.Example: "Siapa Nama Avatar The Last Air Bender?"Recommendations:

Keep questions clear and concise
Use proper grammar and punctuation
Make the question specific and unambiguous

options

array

required

Array of poll options. Recipients will choose from these options.Type: Array of stringsRequirements:

Minimum: 2 options
Maximum: 12 options
Each option should be distinct

Example: ["Zuko", "Aang", "Katara"]

max_answer

integer

required

Maximum number of options a recipient can select.Range: 1 to number of optionsExamples:

1 - Single choice poll (radio button)
2 - Can select up to 2 options
3+ - Multiple choice poll (checkboxes)

Set to 1 for single-choice polls (most common use case).

duration

integer

Disappearing message duration in seconds (optional).Common values:

86400 - 24 hours
604800 - 7 days
7776000 - 90 days

If the poll message disappears, all votes will be lost.

Response

code

string

Response status code. Returns "SUCCESS" on successful send.

message

string

Human-readable response message.

results

object

message_id

string

Unique identifier for the sent message.Example: "3EB0B430B6F8F1D0E053AC120E0A9E5C"

status

string

Detailed status message.

Code Examples

curl -X POST http://localhost:3000/send/poll \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: my-device" \
  -d '{
    "phone": "[email protected]",
    "question": "What is your favorite programming language?",
    "options": ["JavaScript", "Python", "Go", "Rust"],
    "max_answer": 1
  }'

Response Example

{
  "code": "SUCCESS",
  "message": "Success",
  "results": {
    "message_id": "3EB0B430B6F8F1D0E053AC120E0A9E5C",
    "status": "Poll sent successfully"
  }
}

Poll Types

Single Choice Poll (max_answer: 1)

Most common poll type. Recipients can select only one option. Use cases:

Simple yes/no questions
Rating surveys
Single preference selection
Quiz questions with one correct answer

Example:

{
  "question": "What time should we meet?",
  "options": ["9:00 AM", "10:00 AM", "11:00 AM"],
  "max_answer": 1
}

Multiple Choice Poll (max_answer: 2+)

Recipients can select multiple options up to the specified limit. Use cases:

Scheduling (select all available days)
Feature requests (top 3 features)
Interest surveys (select all that apply)
Group decision making

Example:

{
  "question": "What features do you want most? (Pick top 3)",
  "options": ["Dark Mode", "Export PDF", "Mobile App", "API Access", "Integrations"],
  "max_answer": 3
}

Use Cases

Group Decision Making

Get team consensus on important decisions:

curl -X POST http://localhost:3000/send/poll \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "[email protected]",
    "question": "Which project should we prioritize next quarter?",
    "options": [
      "Mobile App Redesign",
      "API v2 Development",
      "Performance Optimization",
      "New Feature X"
    ],
    "max_answer": 1
  }'

Event Planning

Coordinate schedules and gather RSVPs:

curl -X POST http://localhost:3000/send/poll \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "[email protected]",
    "question": "Team dinner next week - which days work for you?",
    "options": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "max_answer": 5
  }'

Customer Feedback

Collect product feedback and satisfaction ratings:

curl -X POST http://localhost:3000/send/poll \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "[email protected]",
    "question": "How satisfied are you with our product?",
    "options": [
      "Very Satisfied 😍",
      "Satisfied 😊",
      "Neutral 😐",
      "Dissatisfied 🙁",
      "Very Dissatisfied 😡"
    ],
    "max_answer": 1
  }'

Quick Surveys

Conduct market research or user preferences:

curl -X POST http://localhost:3000/send/poll \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "[email protected]",
    "question": "What type of content do you want to see more of?",
    "options": [
      "Tutorials",
      "Case Studies",
      "Product Updates",
      "Industry News",
      "Behind the Scenes"
    ],
    "max_answer": 2
  }'

Educational Quizzes

Create interactive learning experiences:

curl -X POST http://localhost:3000/send/poll \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "[email protected]",
    "question": "Quiz: What is the capital of France?",
    "options": ["London", "Paris", "Berlin", "Madrid"],
    "max_answer": 1
  }'

Best Practices

Clear Questions
- Be specific and unambiguous
- Use proper grammar
- Keep questions concise
- Avoid double-barreled questions
Well-Defined Options
- Make options mutually exclusive
- Use parallel structure
- Keep option text brief
- Order logically (alphabetically, chronologically, etc.)
Appropriate max_answer
- Use 1 for most polls (single choice)
- Use 2-3 for “select top X” scenarios
- Use options.length for “select all that apply”
Use Emojis
- Make options more engaging
- Improve visual scanning
- Add personality to polls
- Don’t overuse
Context Matters
- Explain why you’re polling
- Provide deadline if applicable
- Share results after poll closes
- Thank participants
Timing
- Send during active hours
- Give enough time to respond
- Consider time zones for global teams
- Don’t rush decision-making polls

Poll Limitations

Be aware of these WhatsApp poll limitations.

Option Limit: Maximum 12 options per poll
Minimum Options: At least 2 options required
Text Only: Options cannot include images or links
No Editing: Cannot modify poll after sending
View Results: Creator can see who voted for what
Anonymous Voting: Not available (votes are attributed)
No Poll Closing: Polls stay open indefinitely
Group Only Features: Some features only work in groups

Poll Results

WhatsApp shows poll results in real-time:

Vote Count: Number of votes per option
Voter List: See who voted for each option
Percentage: Percentage of participants who voted
Your Vote: Highlighted option(s) you selected
Real-time Updates: Results update as people vote

Poll creators and participants can see detailed voting results, including who voted for which options. Voting is not anonymous.

Common Poll Templates

Meeting Scheduling

{
  "question": "Best time for weekly team sync?",
  "options": ["9 AM", "10 AM", "2 PM", "3 PM", "4 PM"],
  "max_answer": 1
}

Lunch Decision

{
  "question": "What should we order for lunch?",
  "options": ["Pizza 🍕", "Sushi 🍣", "Burgers 🍔", "Salad 🥗"],
  "max_answer": 1
}

Feature Prioritization

{
  "question": "Top 3 features you need most?",
  "options": ["Feature A", "Feature B", "Feature C", "Feature D", "Feature E"],
  "max_answer": 3
}

NPS Survey

{
  "question": "How likely are you to recommend us? (0-10)",
  "options": ["0-2", "3-4", "5-6", "7-8", "9-10"],
  "max_answer": 1
}

Error Responses

400

Bad Request

Common causes:

Invalid phone number format
Missing required fields (question, options, max_answer)
Invalid options array (empty, too few, too many)
max_answer exceeds number of options
max_answer less than 1

500

Internal Server Error

Common causes:

Device not connected
Network connectivity issues
WhatsApp service temporarily unavailable

Troubleshooting

Poll Not Sending

Verify all required fields are provided
Check options array has 2-12 items
Ensure max_answer is valid (1 to options.length)
Verify phone number format is correct
Check device is connected

Invalid max_answer

Must be at least 1
Cannot exceed number of options
Use 1 for single-choice polls
Use higher numbers for multiple-choice

Options Not Displaying

Check options is an array of strings
Verify no empty strings in options
Remove any null or undefined values
Ensure proper JSON formatting

Send Text - Send text messages
Send Image - Send images
Send Link - Send links with preview
Group Info - Get group information

Overview

Device Management

Connection

User

Messaging

Message Operations

Chats

Groups

Newsletters

Endpoint

Headers

Request Body

Response

Code Examples

Response Example

Poll Types

Single Choice Poll (max_answer: 1)

Multiple Choice Poll (max_answer: 2+)

Use Cases

Group Decision Making

Event Planning

Customer Feedback

Quick Surveys

Educational Quizzes

Best Practices

Poll Limitations

Poll Results

Common Poll Templates

Meeting Scheduling

Lunch Decision

Feature Prioritization

NPS Survey

Error Responses

Troubleshooting

Poll Not Sending

Invalid max_answer

Options Not Displaying

Build docs developers (and LLMs) love

Overview

Device Management

Connection

User

Messaging

Message Operations

Chats

Groups

Newsletters

​Endpoint

​Headers

​Request Body

​Response

​Code Examples

​Response Example

​Poll Types

​Single Choice Poll (max_answer: 1)

​Multiple Choice Poll (max_answer: 2+)

​Use Cases

​Group Decision Making

​Event Planning

​Customer Feedback

​Quick Surveys

​Educational Quizzes

​Best Practices

​Poll Limitations

​Poll Results

​Common Poll Templates

​Meeting Scheduling

​Lunch Decision

​Feature Prioritization

​NPS Survey

​Error Responses

​Troubleshooting

​Poll Not Sending

​Invalid max_answer

​Options Not Displaying

​Related Endpoints

Build docs developers (and LLMs) love

Endpoint

Headers

Request Body

Response

Code Examples

Response Example

Poll Types

Single Choice Poll (max_answer: 1)

Multiple Choice Poll (max_answer: 2+)

Use Cases

Group Decision Making

Event Planning

Customer Feedback

Quick Surveys

Educational Quizzes

Best Practices

Poll Limitations

Poll Results

Common Poll Templates

Meeting Scheduling

Lunch Decision

Feature Prioritization

NPS Survey

Error Responses

Troubleshooting

Poll Not Sending

Invalid max_answer

Options Not Displaying

Related Endpoints