> For the complete documentation index, see [llms.txt](https://support.whapi.cloud/help-desk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.whapi.cloud/help-desk/channels/send-quizzes-and-questions-to-whatsapp-channels.md).

# Send Quizzes and Questions to WhatsApp Channels

Whapi.Cloud allows you to publish interactive quizzes and open questions directly to a WhatsApp Channel, also known as a newsletter.

These message types can be used to test subscribers’ knowledge, collect feedback, run interactive activities, or encourage engagement with your Channel content.

### Before you start

You will need:

* An authorized Whapi.Cloud channel and its [API token](/help-desk/getting-started/getting-started.md#get-your-api-key);
* Administrator access to the WhatsApp Channel;
* The Channel ID in the `@newsletter` format.

A Channel ID looks like this:

```
120363298746512907@newsletter
```

In order to find out the identifier use the following method: [GET /newsletters](https://whapi.readme.io/reference/getnewsletters)

### Send a quiz

<figure><img src="/files/1DBtaA3GpBUGVaAjhhtZ" alt=""><figcaption></figcaption></figure>

Use the following endpoint to [publish a quiz](https://whapi.readme.io/reference/sendmessagequiz):

`POST https://gate.whapi.cloud/messages/quiz`

Example:

```bash
curl -X POST "https://gate.whapi.cloud/messages/quiz" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "120363298746512907@newsletter",
    "title": "Which planet is known as the Red Planet?",
    "options": ["Mars", "Venus", "Jupiter"],
    "correct_option_index": 0,
    "hide_participant_name": false,
    "allow_add_option": false
  }'
```

#### Parameters

Required:

* `to` — the Channel ID. It must end with `@newsletter`.
* `title` — the quiz question.
* `options` — an array with 2 to 12 answer options.
* `correct_option_index` — the index of the correct answer.

Optional:

* `end_time` — quiz end time as a Unix timestamp.
* `hide_participant_name` — hides participant information.
* `allow_add_option` — allows participants to add their own option.

#### Important: indexes start from zero

The first answer in the `options` array has index `0`.

```json
{
  "options": ["Mars", "Venus", "Jupiter"],
  "correct_option_index": 0
}
```

In this example:

* `Mars` — index `0`;
* `Venus` — index `1`;
* `Jupiter` — index `2`.

### Send an open question

An open question allows subscribers to submit a written response instead of selecting one of several predefined options.

<figure><img src="/files/g95mj2rUO2jbnR7074JT" alt=""><figcaption></figcaption></figure>

Use the following endpoint to send [question message](https://whapi.readme.io/reference/sendmessagequestion):

`POST https://gate.whapi.cloud/messages/question`

\
Example:

```bash
curl -X POST "https://gate.whapi.cloud/messages/question" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "120363298746512907@newsletter",
    "body": "What topic would you like us to cover next?"
  }'
```

Required parameters:

* `to` — the Channel ID ending with `@newsletter`;
* `body` — a non-empty question text.

***

### Enable Channel tracking

To receive quiz votes and question responses, [enable tracking for the Channel](https://whapi.readme.io/reference/subscribenewsletter):

`POST /newsletters/{NewsletterID}/tracking`

Example:

```bash
POST https://gate.whapi.cloud/newsletters/120363298746512907%40newsletter/tracking
```

We recommend renewing the tracking subscription at least once every 24 hours.

### Receive responses

After tracking is enabled, you can receive updates in two ways:

* Through `MESSAGES PATCH` webhooks;
* By requesting the message directly:

```bash
GET https://gate.whapi.cloud/messages/{MessageID}
```

The webhook option is better for automatic processing. The GET method is useful when you need the current state of a specific message.

### Quiz result example

```json
{
  "id": "H7nK4pQ2vD9mX6aL3sT8wB1cR5yF0jE",
  "from_me": true,
  "type": "quiz",
  "timestamp": 1782463650,
  "source": "api",
  "device_id": 41,
  "starred": false,
  "chat_id": "120363298746512907@newsletter",
  "from": "447911825604",
  "status": "pending",
  "quiz": {
    "title": "Which planet is known as the Red Planet?",
    "options": [
      "Mars",
      "Venus",
      "Jupiter"
    ],
    "vote_limit": 1,
    "total": 1,
    "results": [
      {
        "name": "Mars",
        "voters": [
          "447700912638"
        ],
        "count": 1,
        "id": "T9qL2rW7mF4xA8nK6pV1cD5sH3jB0eYzUoG="
      },
      {
        "name": "Venus",
        "voters": [],
        "count": 0,
        "id": "M4vC8aR1kP6sX9wD2nL7fT5jQ0hY3eBuZiN="
      },
      {
        "name": "Jupiter",
        "voters": [],
        "count": 0,
        "id": "K7dF3pA9xN2rV6mS1wQ8cL4jH0tY5eBzUiG="
      }
    ],
    "correct_answer": "Mars"
  }
}
```

Important fields:

* `total` — total number of votes;
* `results` — results for each option;
* `count` — number of votes;
* `voters` — participant identifiers;
* `correct_answer` — the correct answer.

### Phone numbers and LID identifiers

If the participant is available through WhatsApp contacts, the `voters` array may contain a phone number.

Otherwise, WhatsApp may return an identifier ending with `@lid`:

```json
182736451928374@lid
```

A LID is an internal WhatsApp identifier. Your integration should support both phone numbers and LID values. Read more about @lid here: [WhatsApp LID (@lid)](/help-desk/faq/whatsapp-lid-lid.md)