diff --git a/docs/site/content/en/docs/how-to/chats/index.md b/docs/site/content/en/docs/how-to/chats/index.md index 8a33f91e..f8193250 100644 --- a/docs/site/content/en/docs/how-to/chats/index.md +++ b/docs/site/content/en/docs/how-to/chats/index.md @@ -6,7 +6,7 @@ date: 2020-10-06T08:48:45+00:00 lastmod: 2020-10-06T08:48:45+00:00 draft: false images: [] -weight: 126 +weight: 127 --- Chats methods. diff --git a/docs/site/content/en/docs/how-to/polls/handle-poll-vote-failed.jpg b/docs/site/content/en/docs/how-to/polls/handle-poll-vote-failed.jpg new file mode 100644 index 00000000..7023c3b3 Binary files /dev/null and b/docs/site/content/en/docs/how-to/polls/handle-poll-vote-failed.jpg differ diff --git a/docs/site/content/en/docs/how-to/polls/index.md b/docs/site/content/en/docs/how-to/polls/index.md new file mode 100644 index 00000000..75a3cec2 --- /dev/null +++ b/docs/site/content/en/docs/how-to/polls/index.md @@ -0,0 +1,219 @@ +--- +title: "Polls" +description: "How to send polls and receive votes" +lead: "" +date: 2020-10-06T08:48:45+00:00 +lastmod: 2020-10-06T08:48:45+00:00 +draft: false +images: [ ] +weight: 126 +--- + +**Available on NOWEB engine only**. + +Waiting for WEBJS engine to support it, and we'll add it ASAP! + +![poll-example.jpg](poll-example.jpg) + +## Endpoints + +### Send poll + +Use the endpoint to send a poll! + +```bash +POST /api/sendPoll +``` + +The request body is pretty simple: +```json +{ + "session": "default", + "chatId": "123123123@c.us", + "poll": { + "name": "How are you?", + "options": [ + "Awesome!", + "Good!", + "Not bad!" + ], + "multipleAnswers": false + } +} +``` + +The response you get back: + +```json +{ + "id": "true_321321321@c.us_83ACBAAAAAAAAAAAAAAAAAAAA", + "other-fields-here": "value" +} +``` + +You must save the `id` field from the response in your database so that you can identify the poll for which you receive +a vote (see webhook events below). + +## Events + +### poll.vote + +With this event, you receive new votes for the poll sent. + +#### Vote from a user in direct messages. + +```json +{ + "event": "poll.vote", + "session": "default", + "payload": { + "vote": { + "id": "false_1111111111@c.us_83ACBE602A05C79B234B54415E95EE8A", + "to": "me", + "from": "1111111@c.us", + "fromMe": false, + "selectedOptions": [ + "Awesome!" + ], + "timestamp": 1692861427 + }, + "poll": { + "id": "true_1111111111@c.us_BAE5F2EF5C69001E", + "to": "1111111111@c.us", + "from": "me", + "fromMe": true + } + }, + "engine": "NOWEB" +} +``` + +#### Do I receive votes only for my polls? + +No, you receive all votes. Keep in mind that you'll get all votes with this event, even from other polls. To identify +that it's your poll, look at the `poll.fromMe` field. + +#### How to handle multiple-answer votes + +For `multipleAnswers: true`, you receive the `selectedOptions` with all the selected values at a certain moment. So if a +user has chosen 3 options from the poll, you will receive **3** `poll.vote` events: + +1. `selectedOptions: ["First"]` +2. `selectedOptions: ["First", "Second"]` +3. `selectedOptions: ["First", "Second", "Third"]` + +#### Timestamp + +If a user clicks on the poll multiple times, you will receive multiple `poll.vote` events. This is true for +both `multipleAnswers: false` (when a user changes their mind about answers) and `multipleAnswers: true` (when a user +selects two or more options) events. + +There is a little chance that you may receive votes in the wrong order (due to the nature of HTTP and Webhooks), +like `1-3-2` instead of `1-2-3`. To determine the right order, look at the `timestamp` field. The event with a +higher `timestamp` value is more recent. + +👉 It's important to save the `timestamp` for each vote in your database and compare them as numbers, without converting to +internal datetime. Right now, the `timestamp` shows the timestamp in seconds, but it may be changed to milliseconds in +the future. + +#### Vote from a user in a group + +```json +{ + "event": "poll.vote", + "session": "default", + "payload": { + "vote": { + "id": "false_3333333333333@g.us_1C18A7EAADD2A8D0324755D241C4238A", + "to": "3333333333333@g.us", + "from": "1111111111@c.us", + "fromMe": false, + "selectedOptions": [ + "Awesome!" + ], + "timestamp": 1692861427 + }, + "poll": { + "id": "true_3333333333333@g.us_BAE5304BA1ECF704", + "to": "33333333333333@g.us", + "from": "222222222@c.us", + "fromMe": true + } + }, + "engine": "NOWEB" +} +``` + +### poll.vote.failed + +There may be cases when WAHA fails to decrypt a vote from the user. In such cases, you will receive +a `poll.vote.failed` event on your webhook. + +The payload for `poll.vote.failed` is the same as for `poll.vote`, but with an empty list in `selectedOptions`. + +```json +{ + "event": "poll.vote.failed", + "session": "default", + "payload": { + "vote": { + "id": "false_11111111111@c.us_2E8C4CDA89EDE3BC0BC7F605364B8451", + "to": "me", + "from": "111111111@c.us", + "fromMe": false, + "selectedOptions": [], + "timestamp": 1692956972 + }, + "poll": { + "id": "true_1111111111@c.us_BAE595F4E0A2042C", + "to": "111111111@c.us", + "from": "me", + "fromMe": true + } + }, + "engine": "NOWEB" +} +``` + +#### How should I handle poll.vote.failed events? + +When you send a poll, save the poll configuration (question and options) in your database with the `id` field from the +response you received from `POST /api/sendPoll`. + +Later, when you receive a `poll.vote.failed` event, find the `id` for the poll in the database and repeat the same +question to the user, apologizing for the inconvenience. +For example, you can say: + +> Sorry, we don't understand your choice 😞 +> +> Please click one more time on the message below 👇 + +After the user clicks on the poll again, you will receive a `poll.vote` event with their choice. + +![handle-poll-vote-failed.jpg](handle-poll-vote-failed.jpg) + +#### How to test poll.vote.failed events? + +To receive `poll.vote.failed` events, follow these steps: + +1. Start a session and authorize it with a QR code. +2. Send a poll to a chat. +3. Stop the session (logout is not required). +4. Start the session again. +5. Vote on the poll. +6. You will receive a `poll.vote.failed` event. + +#### Why does the poll.vote.failed event occur and when will it be fixed? + +The issue occurs because WAHA does not have a proper storage system, but polls require proper storage in order to +decrypt votes later. + +There will be two fixes for this: + +1. In the short term, a [local file storage](https://github.com/devlikeapro/whatsapp-http-api/issues/188) will be used + to save poll keys. +2. In the long term, work is being done + on [remote storages](https://github.com/devlikeapro/whatsapp-http-api/issues/41). + +Even after these fixes are implemented, it's better to handle `poll.vote.failed` events anyway, so your application is +prepared for such cases! diff --git a/docs/site/content/en/docs/how-to/polls/poll-example.jpg b/docs/site/content/en/docs/how-to/polls/poll-example.jpg new file mode 100644 index 00000000..4e257132 Binary files /dev/null and b/docs/site/content/en/docs/how-to/polls/poll-example.jpg differ diff --git a/docs/site/content/en/docs/how-to/presence/index.md b/docs/site/content/en/docs/how-to/presence/index.md index c3f99837..159b34f5 100644 --- a/docs/site/content/en/docs/how-to/presence/index.md +++ b/docs/site/content/en/docs/how-to/presence/index.md @@ -129,7 +129,8 @@ You can subscribe to presence information by calling `POST /api/{session}/presen You can get later presence information for the chat with above `GET` endpoints or by listening to `presence.update` webhook. -## Webhook +## Events +### presence.update You can subscribe to `presence.update` webhook event to get the most recent presence information. diff --git a/docs/site/content/en/docs/how-to/send-messages/index.md b/docs/site/content/en/docs/how-to/send-messages/index.md index 06bd09d2..c4999e0e 100644 --- a/docs/site/content/en/docs/how-to/send-messages/index.md +++ b/docs/site/content/en/docs/how-to/send-messages/index.md @@ -31,7 +31,7 @@ When sending media (images, voice, files) you can either use: ## Endpoints -### Send text ![](/images/versions/core.png) +### Send text To send text message - use `POST /api/sendText` with example payload. ```json { @@ -58,7 +58,12 @@ also mention it in `mentions` in format `2132132130@c.us` } ``` -### Reply on message ![](/images/versions/core.png) +### Send poll +We have a dedicated page [how to send polls and receive votes]({{< relref "/docs/how-to/polls" >}})! + +![](poll-example.jpg) + +### Reply on message To reply on a message - use `POST /api/reply` with example payload. ```json { @@ -72,7 +77,7 @@ To reply on a message - use `POST /api/reply` with example payload. #### Reply files ![](/images/versions/plus-soon.png) WAHA does not support reply with files (images, voice, etc). If you're interested in it - please create an issue in GitHub. -### Add a reaction ![](/images/versions/core.png) +### Add a reaction Use `PUT /api/reaction` method to set reaction to a message. {{< alert icon="👉" text="Reaction API uses PUT, not POST request! Please make sure you send right request." />}} diff --git a/docs/site/content/en/docs/how-to/send-messages/poll-example.jpg b/docs/site/content/en/docs/how-to/send-messages/poll-example.jpg new file mode 100644 index 00000000..4e257132 Binary files /dev/null and b/docs/site/content/en/docs/how-to/send-messages/poll-example.jpg differ diff --git a/docs/site/content/en/docs/how-to/webhooks/index.md b/docs/site/content/en/docs/how-to/webhooks/index.md index bcccd91a..4ad6e53e 100644 --- a/docs/site/content/en/docs/how-to/webhooks/index.md +++ b/docs/site/content/en/docs/how-to/webhooks/index.md @@ -284,6 +284,60 @@ It's an internal engine's state, not **session** `status`. } ``` +### poll.vote +We have a dedicated page [how to send polls and receive votes]({{< relref "/docs/how-to/polls" >}})! + +```json +{ + "event": "poll.vote", + "session": "default", + "payload": { + "vote": { + "id": "false_1111111111@c.us_83ACBE602A05C79B234B54415E95EE8A", + "to": "me", + "from": "1111111@c.us", + "fromMe": false, + "selectedOptions": ["Awesome!"], + "timestamp": 1692861427 + }, + "poll": { + "id": "true_1111111111@c.us_BAE5F2EF5C69001E", + "to": "1111111111@c.us", + "from": "me", + "fromMe": true + } + }, + "engine": "NOWEB" +} +``` + +### poll.vote.failed +We have a dedicated page [how to send polls and receive votes]({{< relref "/docs/how-to/polls" >}})! + +```json +{ + "event": "poll.vote.failed", + "session": "default", + "payload": { + "vote": { + "id": "false_11111111111@c.us_2E8C4CDA89EDE3BC0BC7F605364B8451", + "to": "me", + "from": "111111111@c.us", + "fromMe": false, + "selectedOptions": [], + "timestamp": 1692956972 + }, + "poll": { + "id": "true_1111111111@c.us_BAE595F4E0A2042C", + "to": "111111111@c.us", + "from": "me", + "fromMe": true + } + }, + "engine": "NOWEB" +} +``` + ## Webhooks Advanced ![](/images/versions/plus.png) ### HMAC authentication diff --git a/docs/site/content/en/docs/overview/changelog.md b/docs/site/content/en/docs/overview/changelog.md index aa775c81..2d9f7af2 100644 --- a/docs/site/content/en/docs/overview/changelog.md +++ b/docs/site/content/en/docs/overview/changelog.md @@ -14,6 +14,7 @@ toc: true --- ## 2023.9 September 2023 +- Add [polls support in NOWEB engine](https://waha.devlike.pro/docs/how-to/polls) - Add dedicated [Get QR](https://waha.devlike.pro/docs/how-to/sessions/#get-qr) endpoint! - Support [pairing method (NOWEB)](https://waha.devlike.pro/docs/how-to/sessions/#get-pairing-code) - you can connect with a code instead of QR. - Add string field `ackName: DEVICE|READ|...` in [message.ack payload](https://waha.devlike.pro/docs/how-to/webhooks/#messageack)