warb 1.0.0

data/docs/messages/interactive_call_to_action_url.md

@@ -0,0 +1,96 @@
+# Interactive Call to Action URL
+
+An interactive call to action URL message allows you to send a message with a button that redirects the user to a specified URL when clicked.
+
+It may seem simple, but you can set a `header`, `body`, and `footer`, along with the `url` and `button_text`.
+
+While `body` and `footer` are simple text fields, the `header` can be a text, an image, a video or even a document.
+
+For all that, the `interactive_call_to_action_url` dispatcher wrapper can be used to facilitate the process of sending this type of message.
+
+You can send an interactive call to action URL message like this:
+
+```ruby
+header = Warb::Resources::Text.new(content: "Check this out!").build_header
+body = "body"
+footer = "footer"
+action = Warb::Components::CTAAction.new(url: "https://example.com",  button_text: "Click here")
+
+Warb.interactive_call_to_action_url.dispatch(recipient_number, header: header, body: body, footer: footer, action: action)
+```
+
+Here, the block building strategy starts to shine. With it, you don't need to create the `header` and `action` objects manually:
+
+```ruby
+Warb.interactive_call_to_action_url.dispatch(recipient_number) do |message|
+  # as body and footer are simple text fields, you can set them directly
+  message.body = "body"
+  message.footer = "footer"
+
+  # for header, there's a helper method to create a text header
+  message.set_text_header("Check this out!")
+
+  # and for action, you can use the build_action method to create a CTA action`
+  message.build_action(button_text: "Click Here") do |action|
+    action.url = "https://example.com"
+  end
+end
+```
+
+Aside from the text header, you can also set an image, video, or document as header using the respective methods, `set_image_header`, `set_video_header`, and `set_document_header`.
+
+Here is an example of using an image as header:
+
+```ruby
+Warb.interactive_call_to_action_url.dispatch(recipient_number) do |message|
+  message.body = "body"
+  message.footer = "footer"
+
+  # set an image as header
+  message.set_image_header(link: "https://example.com/image.jpg")
+
+  # the build_action method also returns the built action
+  action = message.build_action do |action|
+    action.url = "https://example.com"
+  end
+
+  # so you could set any attribute of the action after building it
+  action.button_text = "Click here"
+end
+```
+
+And here is an example using a document as header:
+
+```ruby
+Warb.interactive_call_to_action_url.dispatch(recipient_number) do |message|
+  message.body = "body"
+  message.footer = "footer"
+
+  # set a document as header
+  # for documents, you can also pass a filename. its extension will be used to determine the MIME type
+  message.set_document_header(link: "https://example.com/document.pdf", filename: "document.pdf")
+
+  message.build_action(url: "https://example.com", button_text: "Click here")
+end
+```
+
+Here is a summary of the fields you can set in the `dispatch` method of the `interactive_call_to_action_url` message:
+| Field     | Type                                                       | Description                                                                                   |
+|-----------|------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
+| `header`  | Object                                                     | The header of the message, can be a text, image, video, or document.                          |
+| `body`    | String                                                     | The body of the message, a simple text field.                                                 |
+| `footer`  | String                                                     | The footer of the message, a simple text field.                                               |
+| `action`  | [Warb::Components::CTAAction](../components/cta_action.md) | The action of the message, which contains the URL and button text.                            |
+
+
+For header, as seen above, you can set it using the following instance methods:
+| Method                | Named Parameters   | Positional Parameters  | Respective Resource Class   |
+|-----------------------|--------------------|------------------------|-----------------------------|
+| `set_text_header`     | -                  | the content header     | `Warb::Resources::Text`     |
+| `set_image_header`    | `link`             | -                      | `Warb::Resources::Image`    |
+| `set_video_header`    | `link`             | -                      | `Warb::Resources::Video`    |
+| `set_document_header` | `link`, `filename` | -                      | `Warb::Resources::Document` |
+
+Under the hood, the set header methods will create the respective resource object and call its `build_header` method to prepare the header for sending.
+
+For the action, the `build_action` instance method will create a `Warb::Components::CTAAction` and return it

data/docs/messages/interactive_list.md

@@ -0,0 +1,159 @@
+# Interactive List
+
+**Note**: It is recommended to read the [interactive reply button message](./interactive_reply_button.md) documentation before reading this one, as it shares many similarities with the interactive list message.
+
+An interactive list message allows you to create a list of items that the user can select from.
+
+This is useful for scenarios where you want to present multiple options to the user and let them choose one.
+
+After the user selects an item from the list, you can handle the selection in your application logic, such as sending a follow-up message or performing an action based on the user's choice.
+
+For that, you need to server a webhook on your own. Check the [webhook example](../../examples/webhook.rb) for a simple implementation.
+
+It may seem similar to the interactive reply button message, but the list message allows you to present more options and also allows the user to select an item from the list.
+
+Based on the one provided in the [interactive reply button message](./interactive_reply_button.md) documentation, let's create a simple interactive list message, step by step.
+
+Create the header, body, and footer of the message:
+
+```ruby
+header = Warb::Resources::Text.new(content: "Language Selection").build_header
+body = "Choose your preferred language"
+footer = "You can change it latter"
+```
+
+Until here, nothing new, we just created the header, body, and footer of the message as usual.
+
+But as with the interactive reply button message, we need to create the list of items that the user can select from.
+
+And in the same way, it is done using the corresponding `action`, which in this case, is the `Warb::Components::ListAction`.
+
+For reply buttons, we simply instantiate the corresponding action with the available options, but for the list message, the options go inside another component.
+
+Actually, aside from the action itself, there are two more components that we need to create: the `Warb::Components::Section` and the `Warb::Components::Row`.
+
+Rows go inside sections, and sections go inside the action. And the available options are the rows.
+
+Let's start with a single section:
+```ruby
+portuguese_row = Warb::Components::Row.new(title: "Português")
+english_row = Warb::Components::Row.new(title: "English")
+spanish_row = Warb::Components::Row.new(title: "Español")
+
+section = Warb::Components::Section.new title: "Languages", rows: [portuguese_row, english_row, spanish_row]
+
+action = Warb::Components::ListAction.new button_text: "Select", sections: [section]
+```
+
+Then, with everything ready, we can send the message:
+
+```ruby
+Warb.interactive_list.dispatch(recipient_number, header: header,  body: body,  footer: footer,  action: action)
+```
+
+Now, let's put everything together in a single code snippet:
+
+```ruby
+header = Warb::Resources::Text.new(content: "Language Selection").build_header
+header = nil
+body = "Choose your preferred language"
+footer = "You can change it latter"
+
+portuguese_row = Warb::Components::Row.new(title: "Português")
+english_row = Warb::Components::Row.new(title: "English")
+spanish_row = Warb::Components::Row.new(title: "Español")
+
+section = Warb::Components::Section.new title: "Languages", rows: [portuguese_row, english_row, spanish_row]
+
+action = Warb::Components::ListAction.new button_text: "Select", sections: [section]
+
+Warb.interactive_list.dispatch(recipient_number, header: header,  body: body,  footer: footer,  action: action)
+```
+
+Using the block strategy allows you to create the message in a more readable way, as shown below:
+
+```ruby
+Warb.interactive_list.dispatch(recipient_number) do |message|
+  message.body = "Choose your preferred language"
+  message.footer = "You can change it later"
+
+  message.set_text_header("Language Selection")
+
+  message.build_action(button_text: "Select") do |action|
+    section = action.add_section(title: nil)
+    section.add_row(title: "Português")
+    section.add_row(title: "English")
+    section.add_row(title: "Español")
+    section.add_row(title: "Français")
+    section.add_row(title: "Deutsch")
+    section.add_row(title: "Italiano")
+    section.add_row(title: "Nederlands")
+    section.add_row(title: "Русский")
+    section.add_row(title: "中文")
+    section.add_row(title: "日本語")
+  end
+end
+```
+
+As seen above, one obvious difference from interactive list to interactive reply button is that the list message allows up to 10 options, while the reply button message allows only up to 3 options.
+
+One other difference is that the list message only supports text headers, while the reply button message supports both text and media headers.
+
+And one side note, is that, the section title is not required, if you're using only one section. You could omit it, it was just added to make it more readable.
+
+Now let's see an interactive list message with multiple sections:
+
+```ruby
+Warb.interactive_list.dispatch(recipient_number) do |message|
+  message.body = "Choose your preferred language"
+  message.footer = "You can change it later"
+
+  message.set_text_header("Language Selection")
+
+  message.build_action(button_text: "Select") do |action|
+    action.add_section(title: "American Languages") do |american_section|
+      american_section.add_row(title: "English (USA)")
+      american_section.add_row(title: "Português (Brasil)")
+    end
+
+    action.add_section(title: "European Languages") do |european_section|
+      european_section.add_row(title: "English (UK)")
+      european_section.add_row(title: "Português (Portugal)")
+      european_section.add_row(title: "Français")
+      european_section.add_row(title: "Deutsch")
+      european_section.add_row(title: "Italiano")
+    end
+
+    action.add_section(title: "Asian Languages") do |asian_section|
+      asian_section.add_row(title: "中文 (Chinese)")
+      asian_section.add_row(title: "日本語 (Japanese)")
+      asian_section.add_row(title: "Русский (Central Asia)")
+    end
+  end
+end
+```
+
+Here, we keep the same total amount of options, but we split them into three sections, each with its own title.
+
+And since we are using more than one section, the title for each section is required, otherwise, it would not be clear what the options are about.
+
+Here is a table summarizing the differences between the interactive list and interactive reply button messages:
+| Feature                     | Interactive List Message | Interactive Reply Button Message |
+|-----------------------------|--------------------------|-----------------------------------|
+| Maximum Options             | 10                       | 3                                 |
+| Header Types                | Text only                | Text and Media                    |
+| Section Support             | Yes                      | No                                |
+| Row Support                 | Yes                      | No                                |
+| Action Type                 | ListAction               | ReplyButtonAction                 |
+| Button Text                 | Yes                      | Yes                               |
+| Footer Support              | Yes                      | Yes                               |
+| Body Support                | Yes                      | Yes                               |
+| Customization               | High                     | Medium                            |
+This table summarizes the key differences between the two types of interactive messages, helping you choose the right one for your use case.
+
+And here is a table summarizing the components used in the interactive list message:
+| Component                                                    | Description                                                                       | Named Paremeters                                                                 |
+|--------------------------------------------------------------|-----------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
+| [Warb::Components::Row](../components/row.md)                | Represents a single row in the list, containing a title, and optional description | `title`, `description`                                                           |
+| [Warb::Components::Section](../components/section.md)        | Contains multiple rows, representing a section in the list                        | `title`, `rows` (array of `Warb::Components::Row`)                               |
+| [Warb::Components::ListAction](../components/list_action.md) | Represents the action for the interactive list, containing sections and a button  | `button_text`, `sections` (array of `Warb::Components::Section`)                 |

data/docs/messages/interactive_reply_button.md

@@ -0,0 +1,67 @@
+# Interactive Reply Button
+
+An interactive reply button message allows you to send a message with a button that, when clicked, sends a predefined reply back.
+
+You can send, at most, 3 buttons in a single message, which the user can select one of them to reply with.
+
+After the user selects an item from the list, you can handle the selection in your application logic, such as sending a follow-up message or performing an action based on the user's choice.
+
+For that, you need to server a webhook on your own. Check the [webhook example](../../examples/webhook.rb) for a simple implementation.
+
+You can send an interactive reply button message like this:
+
+```ruby
+header = Warb::Resources::Text.new(content: "Options").build_header
+body = "Select a Language:"
+footer = nil
+action = Warb::Components::ReplyButtonAction.new(buttons_texts: ["Português", "English", "Español"])
+
+Warb.interactive_reply_button.dispatch(recipient_number, header: header, body: body, footer: footer, action: action)
+```
+
+Or you can use the block building strategy to simplify the process:
+
+```ruby
+Warb.interactive_reply_button.dispatch(recipient_number) do |message|
+  message.set_image_header(media_id: "1341834336894773")
+
+  message.body = "Select a Language:"
+  message.footer = nil
+
+  message.build_action do |action|
+    action.buttons_texts = ["Português", "English", "Español"]
+  end
+end
+```
+
+or you can build the action with the buttons texts directly, passing them to the `build_action` method, without using the block:
+
+```ruby
+Warb.interactive_reply_button.dispatch(recipient_number, action: action) do |message|
+  message.set_text_header(content: "Options")
+  message.body = "Select a Language:"
+  message.footer = nil
+  message.build_action(buttons_texts: ["Português", "English", "Español"])
+end
+```
+
+Aside from text and image headers, you can also set a video or document as header using the respective methods, `set_video_header` and `set_document_header`.
+
+For text header, `set_text_header` receives a string, while for image, video, and document headers, you can pass a `media_id` or a `link` to the media file.
+For header, as seen above, you can set it using the following instance methods:
+| Method                | Named Parameters               | Positional Parameters  | Respective Resource Class   |
+|-----------------------|--------------------------------|------------------------|-----------------------------|
+| `set_text_header`     | -                              | the content header     | `Warb::Resources::Text`     |
+| `set_image_header`    | `link`, `media_id`             | -                      | `Warb::Resources::Image`    |
+| `set_video_header`    | `link`, `media_id`             | -                      | `Warb::Resources::Video`    |
+| `set_document_header` | `link`, `media_id`, `filename` | -                      | `Warb::Resources::Document` |
+
+Either `link` or `media_id` can be used, but not both at the same time.
+
+If you're using a `link`, it will be used to download the media file from the provided URL, so it must not require any authentication or special headers to access the file.
+
+If you're using a `media_id`, it must be obtained from a previous upload using the appropriate media upload method — such as `Warb.document.upload`, `Warb.image.upload`, and so on.
+
+The `filename` for the document header is optional, but if provided, it will be used to determine the MIME type of the document.
+
+For the `action` of the message, you can use the [`Warb::Components::ReplyButtonAction`](../components/reply_button_action.md) class to build the action with the buttons texts.

data/docs/messages/location.md

@@ -0,0 +1,34 @@
+# Location
+
+The location dispatcher wrapper is used to send a location, such as a city or a point of interest.
+
+It can include details like the name of the location, its coordinates (latitude and longitude), and an optional address.
+
+To send a location, you can use the `dispatch` method of the `Warb.location` wrapper:
+```ruby
+Warb.location.dispatch(
+  recipient_number,
+  name: "Central Park",
+  latitude: 40.785091,
+  longitude: -73.968285,
+  address: "New York, NY, USA"
+)
+```
+
+You can also use the `dispatch` method with a block to set the location details:
+```ruby
+Warb.location.dispatch(recipient_number) do |location|
+  location.name = "Eiffel Tower"
+  location.latitude = 48.858844
+  location.longitude = 2.294351
+  location.address = "Champ de Mars, 5 Avenue Anatole France, 75007 Paris, France"
+end
+```
+
+Here is a breakdown of the parameters you can set for the location:
+| Attribute  | Type     | Description                                  | Required |
+|------------|----------|----------------------------------------------|----------|
+| `name`     | `String` | The name of the location                     | No       |
+| `latitude` | `Float`  | The latitude coordinate of the location      | Yes      |
+| `longitude`| `Float`  | The longitude coordinate of the location     | Yes      |
+| `address`  | `String` | The address of the location (optional)       | No       |

data/docs/messages/location_request.md

@@ -0,0 +1,21 @@
+# Location Request
+
+Location Request Message is an interactive message. That is, the user must interect for a complete flow.
+
+It is used to request the user's location, which can be useful for various purposes, such as finding nearby places.
+
+When the user receives a Location Request message, they will be able to share a location by clicking on the "Share Location" button, which can be their current location or a different selected one.
+
+Once the user shares their location, it will be sent to the webhook configured for the WhatsApp account, allowing you to process the location data as needed.
+
+You can check our [`webhook.rb`](../../examples/webhook.rb) example to see how to handle the location request message in your application.
+
+For more info, see the [WhatsApp documentation for Location Request](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages/location-request-messages#:~:text=%2B16505551234-,Webhook%20syntax,-When%20a%20WhatsApp), in the `Webhook syntax` section.
+
+Nevertheless, you can send a location request message like this:
+
+```ruby
+Warb.location_request.dispatch(recipient_number, body_text: "Please share your location")
+```
+
+For Location Request messages, `body_text` is the unique parameter which can be set, is required, and is used to set the text that will be displayed in the message body.

data/docs/messages/reaction.md

@@ -0,0 +1,23 @@
+# Reaction
+
+Reaction messages are used to send reactions to a specific message. They can be used to express emotions or feedback in response to a message.
+
+You can send a reaction message like this:
+
+```ruby
+Warb.reaction.dispatch(recipient_number, emoji: "✅", reply_to: "message_id")
+```
+
+`emoji` is required, is a string, and can be:
+- any emoji supported by Android and iOS devices;
+- rendered-emojis, such as `😀`, `🙃` or `✅`;
+- unicode values, which must be Java- or JavaScript-escape encoded, such as `\uD83D\uDE00`;
+- an empty string to remove a previously sent emoji.
+
+> Since ruby doesn't support unicode escape sequences, it is easier to use rendered emojis option.
+
+As for the `message_id`, it is the ID of the message you want to react to.
+
+You can get this ID from the webhook payload when receiving a message.
+
+Check our [`webhook.rb`](../../examples/webhook.rb) example to see how to react to a message in your application.

data/docs/messages/sticker.md

@@ -0,0 +1,116 @@
+# Sticker
+
+For starters, not all stickers are supported by WhatsApp. Here is a table of supported stickers:
+
+| Sticker Type    | Extension | MIME Type    | Max Size |
+|-----------------|-----------|--------------|----------|
+| WebP (static)   | `.webp`   | `image/webp` | 100 KB   |
+| WebP (animated) | `.webp`   | `image/webp` | 500 KB   |
+
+To send a sticker message, use the `sticker` dispatch wrapper as follows:
+
+```ruby
+recipient_number = "..."
+Warb.sticker.dispatch(recipient_number, ...)
+```
+
+**Note**: For the examples below, take into account `Warb.setup` was called to configure the global client instance, and that the variable `recipient_number` is already set.
+
+You can send a simple sticker message like this:
+
+```ruby
+Warb.sticker.dispatch(recipient_number, link: "https://example.com/sticker.webp")
+```
+
+You can also use the block building strategy to send a sticker message:
+
+```ruby
+Warb.sticker.dispatch(recipient_number) do |sticker|
+  sticker.link = "https://example.com/sticker.webp"
+end
+```
+
+As seen above, the `link` field is used to set the sticker file URL. This must be a direct link to a file hosted online.
+
+Also, if using a link, the sticker file must be publicly accessible, meaning it should not require any authentication or special permissions to access.
+
+Aside from a link, you can also send a sticker by using its ID. For that, you need to have the ID of the sticker file already uploaded to WhatsApp.
+
+#### Upload
+
+Since our `sticker` wrapper is a media dispatcher, it supports media-related operations, like `upload` and `download` methods.
+
+So, we can use the `upload` method to upload a sticker file and get its ID:
+
+```ruby
+sticker_id = Warb.sticker.upload(file_path: "path/to/sticker.webp", file_type: "image/webp")
+```
+
+> `file_type` must be one of the supported sticker types listed [above](#), and `file_path` is the path to the sticker file you want to upload.
+
+**Note**: At this point, it is not possible to retrieve the ID of a sticker file that was previously uploaded, so keep the ID returned by the `upload` method for later use.
+
+**Note**: Also, note that uploaded stickers are stored on WhatsApp servers for 30 days. After that period, they will be deleted and you won't be able to use the ID anymore.
+
+#### Sending with Sticker ID
+
+With the sticker ID in hand, you can use it to send the sticker message:
+
+```ruby
+Warb.sticker.dispatch(recipient_number, media_id: sticker_id)
+```
+
+You can also use the block building strategy to send a sticker message with an ID:
+
+```ruby
+Warb.sticker.dispatch(recipient_number) do |sticker|
+  sticker.media_id = sticker_id
+end
+```
+
+**Note**: Either only one of the `link` or `media_id` fields can be set at a time.
+
+#### Downloading Sticker
+
+You can also download a sticker file using its ID:
+
+```ruby
+Warb.sticker.download(media_id: sticker_id, file_path: "path/to/save/sticker.webp")
+```
+
+This will download the sticker file to the specified path.
+
+Under the hood, the `download` method will use the `retrieve` method to get the download URL.
+
+With the URL in hand, the `download` method will, in fact, download the file to the specified path.
+
+The `retrieve` method receives a single parameter, which is the `media_id` of the sticker file you want to retrieve.
+
+```ruby
+Warb.sticker.retrieve(media_id: sticker_id)
+```
+
+And here is a sample response from the `retrieve` method:
+
+```json
+{
+  "url": "https://lookaside.fbsbx.com/...",
+  "mime_type": "image/webp",
+  "sha256": "4b4719...",
+  "file_size": 1048576,
+  "id": "134183...",
+  "messaging_product": "whatsapp"
+}
+```
+
+#### Deleting Sticker
+
+You can delete a sticker file using its ID:
+
+```ruby
+Warb.sticker.delete(sticker_id)
+```
+
+This will delete the sticker file from WhatsApp servers and return `true` on success.
+
+This is useful if you want to free up space or if you no longer need the sticker file.

data/docs/messages/text.md

@@ -0,0 +1,47 @@
+# Text
+
+Send a simple text message using the `text` wrapper:
+
+```ruby
+recipient_number = "..."
+Warb.message.dispatch(recipient_number, ...)
+```
+
+**Note**: For the examples below, take into account `Warb.setup` was called to configure the global client instance, and that the variable `recipient_number` is already set.
+
+You can send a simple text message like this:
+
+```ruby
+Warb.message.dispatch(recipient_number, content: "Hello, World!")
+```
+
+You can also use the block building strategy to send a text message:
+
+```ruby
+Warb.message.dispatch(recipient_number) do |text|
+  text.content = "Hey, check this out! https://www.google.com"
+  text.preview_url = true
+end
+```
+
+> If `preview_url` is set to `true`, the recipient WhatsApp phone/computer will try to generate a preview for the URL in the content.
+
+| Field         | Type    | Description                                                                 | Required                                 |
+|---------------|---------|-----------------------------------------------------------------------------|------------------------------------------|
+| `preview_url` | Boolean | Whether to generate a preview for URLs in the content. Defaults to `false`. | No                                       |
+| `content`     | String  | The text content of the message.                                            | Yes *                                      |
+| `text`        | String  | The text content of the message.                                            | Yes *                                      |
+| `message`     | String  | The text content of the message.                                            | Yes *                                      |
+
+> `content`, `text`, and `message` are interchangeable, you can use any of them to set the text content of the message.
+> But if using multiple of them, the priority is: `content` > `text` > `message`.
+
+Also, remember that you can use `reply_to` to reply to a previous message:
+
+```ruby
+Warb.message.dispatch(recipient_number, content: "Hello, World!", reply_to: "message_id")
+```
+
+Since text messages are the most common to be sent as replies, we're reforcing the use of `reply_to` here in the `text` wrapper. But keep in mind it can used for any other message type, like `image`, `video`, `document`, etc.
+
+**Remember**: it is a param for the `dispatch` method, not a field of the message itself.