Send Poll Message

Send a WhatsApp poll to a WhatsApp recipient. The recipient can vote for one or more of the options you provide.

Endpoint

POST /whatsapp/send-poll/:instance

• :instance: The name of your WhatsApp instance (e.g., my-bot).

Authentication

This endpoint requires your ChatBreez API key. Include it in every request:

X-API-Key: your_api_key
Content-Type: application/json

Request Body

Parameter	Type	Required	Description
recipient	string	Yes	The recipient's WhatsApp number with country code (e.g., 254123456789) or the full sender address from a webhook (e.g., 123456789012345@lid or [email protected]). Send @lid addresses exactly as received; do not format them or remove the suffix.
pollName	string	Yes	The poll question shown to the recipient (1+ characters).
selectableValues	number	Yes	How many options the recipient may select. Must be between 1 and 10, and cannot exceed the number of poll options.
pollOptions	array	Yes	Two to ten unique poll options (strings).

Poll option rules

• Provide between 2 and 10 options.
• Options must be non-empty strings.
• Options must be unique — duplicate option values are rejected.
• selectableValues must be at least 1 and no more than the number of pollOptions.

Example Payload

{
  "recipient": "254123456789",
  "pollName": "Which colour should we launch next?",
  "selectableValues": 1,
  "pollOptions": ["Red", "Blue", "Green"]
}

Examples

cURL

curl -X POST https://api.chatbreez.com/whatsapp/send-poll/{instance} \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "254123456789",
    "pollName": "Which colour should we launch next?",
    "selectableValues": 1,
    "pollOptions": ["Red", "Blue", "Green"]
  }'

JavaScript

const axios = require('axios');

const sendPoll = async () => {
  try {
    const response = await axios.post('https://api.chatbreez.com/whatsapp/send-poll/{instance}', {
      recipient: '254123456789',
      pollName: 'Which colour should we launch next?',
      selectableValues: 1,
      pollOptions: ['Red', 'Blue', 'Green']
    }, {
      headers: {
        'X-API-Key': 'your_api_key'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

sendPoll();

Python

import requests

url = "https://api.chatbreez.com/whatsapp/send-poll/{instance}"

payload = {
    "recipient": "254123456789",
    "pollName": "Which colour should we launch next?",
    "selectableValues": 1,
    "pollOptions": ["Red", "Blue", "Green"]
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.chatbreez.com/whatsapp/send-poll/{instance}"

	payload := map[string]interface{}{
		"recipient":        "254123456789",
		"pollName":         "Which colour should we launch next?",
		"selectableValues": 1,
		"pollOptions":      []string{"Red", "Blue", "Green"},
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", "your_api_key")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.chatbreez.com/whatsapp/send-poll/{instance}";
        String json = """
            {
              "recipient": "254123456789",
              "pollName": "Which colour should we launch next?",
              "selectableValues": 1,
              "pollOptions": ["Red", "Blue", "Green"]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("X-API-Key", "your_api_key")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php

$url = 'https://api.chatbreez.com/whatsapp/send-poll/{instance}';

$payload = json_encode([
    'recipient' => '254123456789',
    'pollName' => 'Which colour should we launch next?',
    'selectableValues' => 1,
    'pollOptions' => ['Red', 'Blue', 'Green'],
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key',
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Response

{
  "message": "Poll message queued for delivery.",
  "messageId": "3EB0C767D097B7C7C030"
}

Keep the messageId if you need to reference the message later when investigating a delivery.

Common Errors

Errors are returned as JSON in this shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "selectableValues: Cannot exceed the number of poll options.",
    "correlationId": "abc123-def456-ghi789"
  }
}

Status	Code	Meaning
400	VALIDATION_ERROR	The request body is invalid, a poll option is missing or duplicated, selectableValues is out of range, or the recipient is not registered on WhatsApp.
401	UNAUTHORIZED	Missing or invalid API key.
403	FORBIDDEN	Your account is deactivated. Contact support to reactivate it.
404	NOT_FOUND	The instance does not exist.
409	CONFLICT	The instance is not connected to WhatsApp. Reconnect it and try again.
502	UPSTREAM_ERROR	WhatsApp did not acknowledge the message. Try again shortly.
500	INTERNAL_SERVER_ERROR	An unexpected error occurred on our side. Try again shortly.

Next Steps

• Send Text Messages
• Send Media Messages — images, videos, documents, and audio files
• Send Audio Messages — audio attachments and voice notes
• Send Location Messages — share a location pin
• Send Contact Messages — share contact cards
• Check Instance Status