warb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae3d5993ad731dab7a7aeb08130e76aff0872f4f4420680c8724613241043966
+  data.tar.gz: c1fa725f65ad1f69dd37abee564a9864b8cb96b224bc2e098d6ffee183fa33a6
+SHA512:
+  metadata.gz: 30e29c7d31ea2d88bb844c1d50c727cbecf7a32d08d4eb5b6b0114a7d756eb16a103c8e4ca3e32c9532d0a834d0524e8d4d90ba536de8560bb2523dc3dd0c34a
+  data.tar.gz: 765c7adf8cefc2a3eb53dfacfa847f1e29ffddbfd512273a6af8ae09a8f247259b4d6f4465a3c9ea46f83621781c94fa24176c1158589b9e0bda7e9e37c6e355

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0] - 2025-07-01
+
+### Added
+- Messages sending
+  - Text
+  - Audio
+  - Image
+  - Video
+  - Document
+  - Sticker
+  - Contact
+  - Location
+  - Location Request
+  - Interactive List
+  - Interactive Reply Button
+  - Interactive Call to Action URL
+  - Draft Flows
+- Message builder module using blocks
+- Media Uploading/Downloading
+- Message Reaction
+- Typing/Mark Messages as read indicators

data/README.md

@@ -0,0 +1,135 @@
+# Warb
+
+<p>
+  <img src="https://img.shields.io/badge/em_desenvolvimento-lightgreen?label=status"/>
+  <img src="https://img.shields.io/badge/0.0.0-lightgreen?label=version"/>
+</p>
+
+A Ruby Gem focused on wrap all the functionalities and use cases of the WhatsApp Business API. With Warb you can send messages, audio, images, videos, locations and so much more.
+
+## Installation
+
+Add `warb` to your bundle
+
+```ruby
+bundle add warb
+```
+
+or add it manually to your Gemfile if you prefer.
+
+```ruby
+gem 'warb'
+```
+
+## Configuration
+
+If you don't have a **facebook developer account**, **business portfolio** and **meta app** created yet, please redirect to this [official documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) to get started.
+
+### Rails
+
+To use Warb in your Rails application first you will need to initialize it in `config/initializers/warb.rb`:
+
+```ruby
+Warb.setup do |config|
+  config.access_token = <YOUR_WHATSAPP_BUSINESS_ACCESS_TOKEN>
+  config.business_id = <YOUR_WHATSAPP_BUSINESS_ID>
+  config.sender_id = <YOUR_WHATSAPP_BUSINESS_PHONE_ID>
+  config.adapter = <YOUR_ADAPTER_CHOICE> # defaults to Faraday.default_adapter (which is "":net_http" at the moment)
+  config.logger = <YOUR_PERSONALIZED_LOGGER> # defaults to Logger.new($stdout)
+end
+```
+
+If you would like a more direct way to use it, you can always instanciate it directly:
+
+```ruby
+warb = Warb.new(
+  access_token: <YOUR_WHATSAPP_BUSINESS_ACCESS_TOKEN>,
+  business_id: <YOUR_WHATSAPP_BUSINESS_ID>,
+  sender_id: <YOUR_WHATSAPP_BUSINESS_PHONE_ID>
+  adapter: <YOUR_ADAPTER_CHOICE> # defaults to Faraday.default_adapter (which is "":net_http" at the moment)
+  logger: <YOUR_PERSONALIZED_LOGGER> # defaults to Logger.new($stdout)
+)
+```
+
+## Usage
+
+### Initial Steps
+
+Warb is simple to use — either directly from the module or via an instance.
+
+The **first** and **second** usage modes share a common global configuration instance. The **third** mode, however, creates a new configuration instance, allowing you to define separate local configurations **based on the global configuration (if it exists)** when needed.
+
+1. From the Warb module:
+```ruby
+Warb.message.dispatch(recipient_number, message: "Hello from warb!")
+```
+
+2. From the Warb instance returned from `.setup`:
+```ruby
+warb = Warb.setup { |config| ... }
+
+warb.message.dispatch(recipient_number, message: "Hello from warb!")
+```
+
+3. From the Warb instance return from `.new`:
+```ruby
+warb = Warb.new(...)
+
+warb.message.dispatch(recipient_number, message: "Hello from warb!")
+```
+
+### What more can we do?
+
+You can also pass a block to the `dispatch` method, which look like this:
+
+```ruby
+Warb.message.dispatch(recipient_number) do |builder|
+  builder.message = "Hello from warb!"
+end
+```
+
+### What types of messages can I send?
+
+Warb implements the main types of WhatsApp messages, you can follow the message types [`here`](docs/messages/README.md#messages-types)
+
+examples:
+
+```ruby
+
+warb = Warb.new(...)
+
+warb.message.dispatch(...)
+warb.audio.dispatch(...)
+warb.video.dispatch(...)
+warb.image.dispatch(...)
+...
+```
+
+### Find all usage examples
+
+We suggest heading to the [`examples`](examples) directory, where you'll find documentation files with plenty of usage examples, organized by **Resources** (**Resources** are the types of messages you can send via WhatsApp using Warb).
+
+You can also check the [`docs`](docs/README.md) for a more structured overview of the available resources and their usage.
+
+### Webhook Support
+
+You might want to take action in response to messages users send. For example:
+
+1. A user sends a message like: “generate an image based on...”
+2. You receive the message, so you mark it as read to let the user know their request was acknowledged.
+3. Since the operation might take some time, you send a typing indicator to show that the request is being processed.
+
+To enable this kind of flow, you’ll need to know **when** a message is received. For that, you’ll need to run your own server to listen for incoming webhook events and respond accordingly.
+
+> ⚠️ **Note:** This gem **does not** provide built-in support for webhooks.
+> However, you can look at [`examples/webhook.rb`](examples/webhook.rb) for a starting point on how to implement it. Also, check the [official documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/payload-examples) for more details if you get stuck.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/warb.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/README.md

@@ -0,0 +1,16 @@
+# Warb Documentation
+
+## Configuration
+Refer to [setup](setup.md) for more details on how to configure Warb.
+
+## Webhook
+Refer to [webhook](webhook.md) for more details on how to setup a webhook to get started.
+
+## Sending Messages
+Refer to [messages](./messages/README.md) for more details on how to send messages using Warb.
+
+## Components
+Refer to [components](./components/README.md) for more details on how Warb components work.
+
+## Resources
+Refer to [resources](./resources/README.md) for more details on resources.

data/docs/components/README.md

@@ -0,0 +1,24 @@
+# Components
+
+Components cannot be used directly, they are used in messages.
+
+Components are used to build complex messages with multiple fields and types.
+
+Here is a table of available components, and where they can be used:
+
+| Component Class                       | Used in Message Types                                                           | Component DOC                                |
+|---------------------------------------|---------------------------------------------------------------------------------|----------------------------------------------|
+| `Warb::Components::Address`           | [Contact](../messages/contact.md)                                               | [Address](./address.md)                      |
+| `Warb::Components::Email`             | [Contact](../messages/contact.md)                                               | [Email](./email.md)                          |
+| `Warb::Components::Name`              | [Contact](../messages/contact.md)                                               | [Name](./name.md)                            |
+| `Warb::Components::Phone`             | [Contact](../messages/contact.md)                                               | [Phone](./phone.md)                          |
+| `Warb::Components::Org`               | [Contact](../messages/contact.md)                                               | [Org](./org.md)                              |
+| `Warb::Components::URL`               | [Contact](../messages/contact.md)                                               | [URL](./url.md)                              |
+| `Warb::Components::CTAAction`         | [Interactive Call to Action URL](../messages/interactive_call_to_action_url.md) | [CTAAction](./cta_action.md)                 |
+| `Warb::Components::ReplyButtonAction` | [Interactive Reply Button](../messages/interactive_reply_button.md)             | [Reply Button Action](./reply_button_action) |
+| `Warb::Components::Row`               | [Interactive List](../messages/interactive_list.md)                             | [Row](./row.md)                              |
+| `Warb::Components::ListAction`        | [Interactive List](../messages/interactive_list.md)                             | [List Action](./list_action.md)              |
+| `Warb::Components::Section`           | [Interactive List](../messages/interactive_list.md)                             | [Section](./section.md)                      |
+| `Warb::Components::Button`            | [Template](../messages/template.md)                                             | [Button](./button.md)                        |
+| `Warb::Components::UrlButton`         | [Template](../messages/template.md)                                             | [UrlButton](./url_button.md)                 |
+| `Warb::Components::CopyCodeButton`    | [Template](../messages/template.md)                                             | [CopyCodeButton](./copy_code_button.md)      |

data/docs/components/address.md

@@ -0,0 +1,68 @@
+# Address
+
+Address, `Warb::Components::Address`, is a component used in the `Contact` message type.
+
+It represents an address with the following fields:
+
+|Attribute       | Type     | Description                                     | Required |
+|----------------|----------|-------------------------------------------------|----------|
+| `street`       | `String` | The street address                              | No       |
+| `city`         | `String` | The city of the address                         | No       |
+| `state`        | `String` | The state of the address                        | No       |
+| `zip`          | `String` | The ZIP code of the address                     | No       |
+| `country`      | `String` | The country of the address                      | No       |
+| `country_code` | `String` | The country code of the address                 | No       |
+| `type`         | `String` | The type of the address (e.g., "HOME", "WORK" ) | No       |
+
+When using the `Warb::Components::Address` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+address = Warb::Components::Address.new(
+  street: "123 Main St",
+  city: "Springfield",
+  state: "IL",
+  zip: "62701",
+  country: "USA",
+  country_code: "US",
+  type: "HOME"
+)
+```
+
+or
+
+```ruby
+address = Warb::Components::Address.new
+address.street = "123 Main St"
+address.city = "Springfield"
+address.state = "IL"
+address.zip = "62701"
+address.country = "USA"
+```
+
+But is better to use it in the context of a `Contact` message type, where you can add addresses using the `add_address` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  # Adding an address using a block
+  contact.add_address do |address|
+    address.street = "123 Main St"
+    address.city = "Springfield"
+    address.state = "IL"
+    address.zip = "62701"
+    address.country = "USA"
+    address.country_code = "US"
+    address.type = "HOME"
+  end
+
+  # Adding an address with parameters
+  contact.add_address(
+    street: "456 Elm St",
+    city: "Shelbyville",
+    state: "IL",
+    zip: "62565",
+    country: "USA",
+    country_code: "US",
+    type: "WORK"
+  )
+end
+```

data/docs/components/button.md

@@ -0,0 +1,61 @@
+# Button
+
+`Warb::Components::Button` is a component that represents a generic button used in template messages. It's part of the Components module, which contains reusable parts of complex structures.
+
+It represents a generic button, which can be set with the following attributes:
+
+## Attributes
+|   Attribute  |    Type   | Required |                   Description                 |
+|--------------|-----------|----------|-----------------------------------------------|
+| `index`      | `Integer` |   Yes    | An identifier or position for the button.     |
+| `sub_type`   | `String`  |   Yes    | A more specific classification for the button |
+
+## Common Button Types
+| Button Type   | Template Instance Method     | Params                  |
+|---------------|------------------------------|-------------------------|
+| `quick_reply` | `add_quick_reply_button`     | `index`                 |
+| `voice_call`  | `add_voice_call_button`      | `index`                 |
+| `url`         | `add_dynamic_url_button`     | `index`, `text`         |
+| `copy_code`   | `add_copy_code_button`       | `index`, `coupon_code`  |
+
+Please, refer to our [templates messaging documentation](../messages/template.md) for more info. You can check the methods to insert a button in the "Adding Buttons" section.
+
+## Examples
+
+### Quick Reply button
+```ruby
+quick_reply = Warb::Components::Button.new(index: 0, sub_type: "quick_reply")
+quick_reply.to_h
+=> {
+     type: "button",
+     sub_type: "quick_reply",
+     index: 0
+   }
+```
+
+### Voice Call button
+```ruby
+voice_call = Warb::Components::Button.new(index: 1, sub_type: "voice_call")
+voice_call.to_h
+=> {
+     type: "button",
+     sub_type: "voice_call",
+     index: 1
+   }
+```
+
+## Usage in Templates
+
+Buttons are typically used within template messages. Here's how to add them:
+
+```ruby
+template = Warb::Resources::Template.new(name: "my_template", language: "en_US")
+
+# Add a quick reply button
+template.add_quick_reply_button(index: 0)
+
+# Add a voice call button
+template.add_voice_call_button(index: 1)
+
+# The buttons will be included in the template's build_payload (as components)
+```

data/docs/components/copy_code_button.md

@@ -0,0 +1,57 @@
+# CopyCodeButton
+
+`Warb::Components::CopyCodeButton` is a component used in template messages for copy code buttons.
+
+## Attributes
+|   Attribute    |    Type   | Required |                   Description                 |
+|----------------|-----------|----------|-----------------------------------------------|
+| `index`        | `Integer` |   Yes    | An identifier or position for the button.     |
+| `sub_type`     | `String`  |   Yes    | Always "copy_code" for this button type       |
+| `coupon_code`  | `String`  |   No     | The coupon code to be copied when button is pressed |
+
+## Examples
+
+### Basic copy code button
+```ruby
+copy_button = Warb::Components::CopyCodeButton.new(index: 0, sub_type: "copy_code", coupon_code: "SAVE20")
+copy_button.to_h
+=> {
+     type: "button",
+     sub_type: "copy_code",
+     index: 0,
+     parameters: [
+       {
+         type: "coupon_code",
+         coupon_code: "SAVE20"
+       }
+     ]
+   }
+```
+
+### Copy code button without coupon code
+```ruby
+copy_button = Warb::Components::CopyCodeButton.new(index: 1, sub_type: "copy_code")
+copy_button.to_h
+=> {
+     type: "button",
+     sub_type: "copy_code",
+     index: 1
+   }
+```
+
+## Usage in Templates
+
+Copy code buttons are typically added to templates using the `add_copy_code_button` method:
+
+```ruby
+template = Warb::Resources::Template.new(name: "my_template", language: "en_US")
+
+# Add a copy code button
+template.add_copy_code_button(index: 0, coupon_code: "SAVE20")
+
+# Or using a block for more complex configuration
+template.add_copy_code_button do |button|
+  button.index = 0
+  button.coupon_code = "SAVE20"
+end
+```

data/docs/components/cta_action.md

@@ -0,0 +1,13 @@
+# Call To Action Url Action (CTAAction)
+
+The `CTAAction` component is used to define the action of a call to action URL message.
+
+You don't need to create an instance of `CTAAction` manually, as the `Warb::Resources::InteractiveCalltoActionURL` resource class provides a convenient method to build it, but here are its parameters:
+| Attribute     | Type     | Description                                              | Required |
+|---------------|----------|----------------------------------------------------------|----------|
+| `url`         | `String` | The URL to redirect the user when the button is clicked. | Yes      |
+| `button_text` | `String` | The text to display on the button.                       | Yes      |
+
+The `button_text` content must be, at most, 20 characters long.
+
+See its usage in the [Interactive Call to Action URL Message](../messages/interactive_call_to_action_url.md) documentation.

data/docs/components/email.md

@@ -0,0 +1,40 @@
+# Email
+
+Email, `Warb::Components::Email`, is a component used in the `Contact` message type.
+
+It represents an email address with the following fields:
+
+|Attribute | Type     | Description                                   | Required |
+|----------|----------|-----------------------------------------------|----------|
+| `email`  | `String` | The email address                             | No       |
+| `type`   | `String` | The type of the email (e.g., "HOME", "WORK" ) | No       |
+
+When using the `Warb::Components::Email` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+address = Warb::Components::Email.new(
+  email: "personal@example.com",
+  type: "HOME"
+)
+```
+or
+
+```ruby
+address = Warb::Components::Email.new(type: "WORK")
+address.email = "work@example.com"
+```
+
+But is better to use it in the context of a `Contact` message type, where you can add emails using the `add_email` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  # Adding an email using a block
+  contact.add_email do |email|
+    email.email = "work@example.com"
+    email.type = "WORK"
+  end
+
+  # Adding an email with parameters
+  contact.add_email(email: "home@example.com", type: "HOME")
+end
+```

data/docs/components/list_action.md

@@ -0,0 +1,29 @@
+# Interactive List Action
+
+The `ListAction` component is used to define the action of an interactive list message.
+
+You don't need to create an instance of `ListAction` manually, as the `Warb::Resources::InteractiveList` resource class provides a convenient method to build it, but here are its parameters:
+
+| Attribute     | Type     | Description                                                                                                          | Required |
+|---------------|----------|----------------------------------------------------------------------------------------------------------------------|----------|
+| button_text   | String   | The text displayed on the button that the user can click to select an option from the list.                          | Yes      |
+| sections      | Array    | An array of [`Warb::Components::Section`](./section.md) instances, each representing a group of options in the list. | Yes      |
+
+The `ListAction` component also provides a `add_section` method to add a section to the action after its creation.
+
+```ruby
+action = Warb::Components::ListAction.new(button_text: "Select")
+section = action.add_section(title: "Languages") # returns a Warb::Components::Section instance
+```
+
+You can also use a block with the `add_section` method to build the section, which is useful for setting its options:
+
+```ruby
+action = Warb::Components::ListAction.new(button_text: "Select")
+section = action.add_section do |section|
+  section.title = "Languages"
+  section.add_row(...) # add options here
+end
+```
+
+Check its complete usage in the [interactive list message documentation](../messages/interactive_list.md).

data/docs/components/name.md

@@ -0,0 +1,49 @@
+# Name
+
+Name, `Warb::Components::Name`, is a component used in the `Contact` message type.
+
+It represents a name with the following fields:
+
+|Attribute         | Type     | Description                                            | Required |
+|------------------|----------|--------------------------------------------------------|----------|
+| `prefix`         | `String` | The prefix used to address the person                  | *No      |
+| `formatted_name` | `String` | The formatted name to be displayed in the contact info | Yes      |
+| `first_name`     | `String` | The contact's first name                               | *No      |
+| `middle_name`    | `String` | The contact's middle name                              | *No      |
+| `last_name`      | `String` | The contact's last name                                | *No      |
+| `suffix`         | `String` | The contact's suffix, if applicable                    | *No      |
+
+**Note**: At least one other attribute **must be provided** along with `formatted_name`.
+
+When using the `Warb::Components::Name` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+name = Warb::Components::Name.new(
+  formatted_name: "John Doe",
+  prefix: "Mr",
+  first_name: "John",
+  last_name: "Doe"
+)
+```
+or
+
+```ruby
+name = Warb::Components::Name.new
+name.formatted_name = "John Doe"
+name.prefix = "Mr"
+name.first_name = "John"
+name.last_name = "Doe"
+```
+
+But it is better to use it in the context of a `Contact` message type, where you can build the name using the `build_name` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  contact.build_name do |name|
+    name.formatted_name = "John Doe"
+    name.prefix = "Mr"
+    name.first_name = "John"
+    name.last_name = "Doe"
+  end
+end
+```

data/docs/components/org.md

@@ -0,0 +1,42 @@
+# Org
+
+Org, `Warb::Components::Org`, is a component used in the `Contact` message type.
+
+It represents an Organization with the following fields:
+
+|Attribute       | Type     | Description                                   | Required |
+|----------------|----------|-----------------------------------------------|----------|
+| `company`      | `String` | Name of the company where the contact works   | No       |
+| `title`        | `String` | Contact's job title                           | No       |
+| `department`   | `String` | Department within the company                 | No       |
+
+When using the `Warb::Components::Org` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+org = Warb::Components::Org.new(
+  company: "Example Corp",
+  title: "Software Engineer",
+  department: "Engineering"
+)
+```
+
+or
+
+```ruby
+org = Warb::Components::Org.new
+org.company = "Example Corp"
+org.title = "Software Engineer"
+org.department = "Engineering"
+```
+
+But it is better to use it in the context of a `Contact` message type, where you can build the organization using the `build_org` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  contact.build_org do |org|
+    org.company = "Example Corp"
+    org.title = "Software Engineer"
+    org.department = "Engineering"
+  end
+end
+```

data/docs/components/phone.md

@@ -0,0 +1,57 @@
+# Phone
+
+Phone, `Warb::Components::Phone`, is a component used in the `Contact` message type.
+
+It represents a phone with the following fields:
+
+|Attribute | Type     | Description                                   | Required |
+|----------|----------|-----------------------------------------------|----------|
+| `phone`  | `String` | The phone number                              | No       |
+| `type`   | `String` | The type of the phone (e.g., "HOME", "WORK" ) | No       |
+| `wa_id`  | `String` | The WhatsApp ID associated with the phone     | No       |
+
+The `wa_id` is used to identify the WhatsApp account associated with the given phone number. Generally, it is the same as the phone number, without the `+` sign.
+
+When used, the sent message will allow the recipient to interact directly with the WhatsApp account associated with the `wa_id`:
+
+<img src="../images/contact-with-wa_id.png" width="600">
+
+
+If omitted, or without account associated to the given `wa_id`, the recipient will be able to send a WhatsApp invitation:
+
+<img src="../images/contact-without-wa_id.png" width="600">
+
+When using the `Warb::Components::Phone` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+phone = Warb::Components::Phone.new(
+  phone: "+1234567890",
+  type: "WORK",
+  wa_id: "1234567890"
+)
+```
+
+or
+
+```ruby
+phone = Warb::Components::Phone.new
+phone.phone = "+1234567890"
+phone.type = "WORK"
+phone.wa_id = "1234567890"
+```
+
+But it is better to use it in the context of a `Contact` message type, where you can add phones using the `add_phone` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  # Adding a phone using a block
+  contact.add_phone do |phone|
+    phone.phone = "+1234567890"
+    phone.type = "WORK"
+    phone.wa_id = "1234567890"
+  end
+
+  # Adding a phone with parameters
+  contact.add_phone(phone: "+0987654321", type: "HOME", wa_id: "0987654321")
+end
+```