Send Quizzes and Questions to WhatsApp Channels

Create & Share Quizzes on WhatsApp

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;

• 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

Send a quiz

Use the following endpoint to publish a quiz:

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

Example:

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.

{
  "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.

Use the following endpoint:

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

Example:

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:

POST /newsletters/{NewsletterID}/tracking

Example:

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:

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

{
  "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:

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)