warb 1.0.0

data/docs/messages/video.md

@@ -0,0 +1,116 @@
+# Video
+
+For starters, not all video formats are supported by WhatsApp. Here is a table of supported video formats:
+
+| Video Type | Extension | MIME Type    | Max Size |
+|------------|-----------|--------------|----------|
+| MP4        | `.mp4`    | `video/mp4`  | 16 MB    |
+| 3GPP       | `.3gp`    | `video/3gpp` | 16 MB    |
+
+To send a video message, use the `video` dispatch wrapper as follows:
+
+```ruby
+recipient_number = "..."
+Warb.video.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 video message like this:
+
+```ruby
+Warb.video.dispatch(recipient_number, link: "https://example.com/video.mp4")
+```
+
+You can also use the block building strategy to send a video message:
+
+```ruby
+Warb.video.dispatch(recipient_number) do |video|
+  video.link = "https://example.com/video.mp4"
+end
+```
+
+As seen above, the `link` field is used to set the video file URL. This must be a direct link to a video file hosted online.
+
+Also, if using a link, the video 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 video by using its ID. For that, you need to have the ID of the video file already uploaded to WhatsApp.
+
+#### Upload
+
+Since our `video` 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 video file and get its ID:
+
+```ruby
+video_id = Warb.video.upload(file_path: "path/to/video.mp4", file_type: "video/mp4")
+```
+
+> `file_type` must be one of the supported video types listed [above](#), and `file_path` is the path to the video file you want to upload.
+
+**Note**: At this point, it is not possible to retrieve the ID of a video file that was previously uploaded, so keep the ID returned by the `upload` method for later use.
+
+**Note**: Also, note that uploaded videos 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 Video ID
+
+With the video ID in hand, you can use it to send the video message:
+
+```ruby
+Warb.video.dispatch(recipient_number, media_id: video_id)
+```
+
+You can also use the block building strategy to send a video message with an ID:
+
+```ruby
+Warb.video.dispatch(recipient_number) do |video|
+  video.media_id = video_id
+end
+```
+
+**Note**: Either only one of the `link` or `media_id` fields can be set at a time.
+
+#### Downloading Video
+
+You can also download a video file using its ID:
+
+```ruby
+Warb.video.download(media_id: video_id, file_path: "path/to/save/video.mp4")
+```
+
+This will download the video 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 video file you want to retrieve.
+
+```ruby
+Warb.video.retrieve(media_id: video_id)
+```
+
+And here is a sample response from the `retrieve` method:
+
+```json
+{
+  "url": "https://lookaside.fbsbx.com/...",
+  "mime_type": "video/mp4",
+  "sha256": "4b4719...",
+  "file_size": 1048576,
+  "id": "134183...",
+  "messaging_product": "whatsapp"
+}
+```
+
+#### Deleting Video
+
+You can delete a video file using its ID:
+
+```ruby
+Warb.video.delete(video_id)
+```
+
+This will delete the video 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 video file.

data/docs/setup.md

@@ -0,0 +1,46 @@
+# Setup
+
+## Global
+You can configure `Warb` globally as follow:
+
+```ruby
+Warb.setup do |config|
+  config.access_token = "access_token"
+  config.sender_id = "sender_id"
+end
+```
+
+This way, every time you use any method from Warb, like `Warb.message` or `Warb.audio`, the global configuration is going to be used automatically.
+
+So if you're running a Rails Application, you can put this code in an initializer file, like `config/initializers/warb.rb`.
+
+If you're not using Rails, you can put it in your main application file, like `app.rb` or `main.rb`.
+
+
+## Local
+
+Instead of using the global configuration, you might want to use a different configuration for a specific task. In such cases, it's possible to instatiate a client directly using `Warb.new`:
+
+```ruby
+client = Warb.new(access_token: "access_token", sender_id: "sender_id")
+client.message.dispatch(...)
+```
+
+Also, it is possible to reuse the global configuration but override some of the parameters, like `sender_id`:
+
+```ruby
+client = Warb.new(sender_id: "another_id")
+# This client will use the global `access_token` but a different `sender_id`
+client.message.dispatch(...)
+```
+
+Aside from the `access_token` and `sender_id`, you can also pass any other parameter that is supported by the `Warb::Client` class, a logger, or a custom HTTP client.
+
+```ruby
+Warb.setup do |config|
+  config.logger = Logger.new($stdout) # or any other logger you prefer
+  config.adapter = :net_http # or any other HTTP client adapter you prefer
+end
+```
+
+Also, note that calling `Warb.setup` multiple times **WILL NOT** override the previous configuration, so you can use it to change the global configuration at any time.

data/docs/webhook.md

@@ -0,0 +1,24 @@
+# Webhook
+
+You need to setup a webhook to receive messages from WhatsApp. The webhook is a URL that WhatsApp will call whenever there is an event related to your WhatsApp Business Account, such as receiving a message or a status update.
+
+Such status or updates include:
+- New Messages
+- Message delivery status
+- Message read status
+- Message reaction
+- Message template status
+- Message interactive list response
+- Message interactive reply button response
+- Errors responses
+
+To set up a webhook, follow these steps:
+1. **Create a Webhook URL**: This is the URL that WhatsApp will call to send you updates. It should be publicly accessible and able to handle POST requests.
+2. **Configure the Webhook in WhatsApp**: Go to your WhatsApp Business Account settings and configure the webhook URL. You will need to provide the URL and select the events you want to receive.
+3. **Handle Incoming Webhook Requests**: In your application, you need to create an endpoint that can handle incoming POST requests from WhatsApp. This endpoint should parse the incoming data and respond with a 200 OK status to acknowledge receipt of the message.
+4. **Verify the Webhook**: WhatsApp will send a verification request to your webhook URL. You need to respond with the `hub.challenge` parameter to verify that you own the webhook URL.
+5. **Test the Webhook**: Send a test message to your WhatsApp Business Account to ensure that your webhook is working correctly and that you are receiving updates as expected.
+
+After configuring the webhook in the WhatsApp Business Account settings, for a quick start, you can refer to [webhook.rb example](../examples/webhook.rb) to see how to handle incoming webhook requests in your application.
+
+Or you can refer to the official [Webhook Setup](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks) or [Webhook payload structure](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components) for more details.

data/examples/audio.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../lib/warb"
+
+# Configure your variables here
+
+access_token = ""
+business_id = ""
+sender_id = ""
+recipient_number = ""
+
+audio_link = ""
+
+# We recommend testing one section at a time, as it can be overwhelming to see all the messages at once.
+# So you can comment out the sections you don't want to test.
+
+# ############################################## #
+# ============== Using Warb.setup ============== #
+# ############################################## #
+
+warb_from_setup = Warb.setup do |config|
+  config.access_token = access_token
+  config.business_id = business_id
+  config.sender_id = sender_id
+end
+
+# To send audio using its ID, you may need to retrieve it first, which can be retrieved this way
+file_path = "" # fill this in with the file path pointing to wherever the audio is located
+file_type = "" # fill this in with the mimetype of the audio to be uploaded
+# allow values for file_type: audio/aac, audio/amr, audio/mpeg, audio/mp4 or audio/ogg
+audio_id = warb_from_setup.audio.upload(file_path: file_path, file_type: file_type)
+# if you already have an audio id, you can simply replace the above line with such id
+
+warb_from_setup.audio.dispatch(recipient_number, media_id: audio_id)
+warb_from_setup.audio.dispatch(recipient_number, link: audio_link)
+
+warb_from_setup.audio.dispatch(recipient_number) do |builder|
+  builder.media_id = audio_id
+end
+
+warb_from_setup.audio.dispatch(recipient_number) do |builder|
+  builder.link = audio_link
+end
+
+# ############################################ #
+# ============== Using Warb.new ============== #
+# ############################################ #
+
+warb_from_new = Warb.new(
+  access_token: access_token,
+  business_id: business_id,
+  sender_id: sender_id
+)
+
+# Same as stated above, if you need an audio id, you can upload it this way
+file_path = "" # fill this in with the file path pointing to wherever the audio is located
+file_type = "" # fill this in with the mimetype of the audio to be uploaded
+# allow values for file_type: audio/aac, audio/amr, audio/mpeg, audio/mp4 or audio/ogg
+audio_id = warb_from_setup.audio.upload(file_path: file_path, file_type: file_type)
+# if you already have an audio id, you can simply replace the above line with such id
+
+warb_from_new.audio.dispatch(recipient_number, media_id: audio_id)
+warb_from_new.audio.dispatch(recipient_number, link: audio_link)
+
+warb_from_new.audio.dispatch(recipient_number) do |builder|
+  builder.media_id = audio_id
+end
+
+warb_from_new.audio.dispatch(recipient_number) do |builder|
+  builder.link = audio_link
+end
+
+# ################################################# #
+# ============== Using Warb directly ============== #
+# ################################################# #
+
+Warb.audio.dispatch(recipient_number, media_id: audio_id)
+Warb.audio.dispatch(recipient_number, link: audio_link)
+
+Warb.audio.dispatch(recipient_number) do |builder|
+  builder.media_id = audio_id
+end
+
+Warb.audio.dispatch(recipient_number) do |builder|
+  builder.link = audio_link
+end

data/examples/document.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "../lib/warb"
+
+# Configure your variables here
+
+access_token = ""
+business_id = ""
+sender_id = ""
+recipient_number = ""
+
+document_link = ""
+
+# We recommend testing one section at a time, as it can be overwhelming to see all the messages at once.
+# So you can comment out the sections you don't want to test.
+
+# ############################################## #
+# ============== Using Warb.setup ============== #
+# ############################################## #
+
+warb_from_setup = Warb.setup do |config|
+  config.access_token = access_token
+  config.business_id = business_id
+  config.sender_id = sender_id
+end
+
+# To send document using its ID, you may need to retrieve it first, which can be retrieved this way
+file_path = "" # fill this in with the file path pointing to wherever the document is located
+file_type = "" # fill this in with the mimetype of the document to be uploaded
+# allow values for file_type:
+# text/plain, application/vnd.ms-excel, application/msword
+# application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint,
+# application/vnd.openxmlformats-officedocument.presentationml.presentation or application/pdf
+document_id = warb_from_setup.document.upload(file_path: file_path, file_type: file_type)
+# if you already have a document id, you can simply replace the above line with such id
+
+warb_from_setup.document.dispatch(recipient_number, media_id: document_id)
+warb_from_setup.document.dispatch(recipient_number, media_id: document_id, filename: "optional_name.pdf")
+warb_from_setup.document.dispatch(recipient_number, media_id: document_id, caption: "OPTIONAL - Document caption")
+warb_from_setup.document.dispatch(recipient_number, link: document_link)
+warb_from_setup.document.dispatch(recipient_number, link: document_link, filename: "optional_name.pdf")
+warb_from_setup.document.dispatch(recipient_number, link: document_link, caption: "OPTIONAL - Document caption")
+
+warb_from_setup.document.dispatch(recipient_number) do |builder|
+  builder.media_id = document_id
+  builder.filename = "optional_name.pdf"
+  builder.caption = "OPTIONAL - Document caption"
+end
+
+warb_from_setup.document.dispatch(recipient_number) do |builder|
+  builder.link = document_link
+  builder.filename = "optional_name.pdf"
+  builder.caption = "OPTIONAL - Document caption"
+end
+
+# ############################################ #
+# ============== Using Warb.new ============== #
+# ############################################ #
+
+warb_from_new = Warb.new(
+  access_token: access_token,
+  business_id: business_id,
+  sender_id: sender_id
+)
+
+# Same as stated above, if you need a document id, you can upload it this way
+file_path = "" # fill this in with the file path pointing to wherever the document is located
+file_type = "" # fill this in with the mimetype of the document to be uploaded
+# allow values for file_type:
+# text/plain, application/vnd.ms-excel, application/msword
+# application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint,
+# application/vnd.openxmlformats-officedocument.presentationml.presentation or application/pdf
+document_id = warb_from_setup.document.upload(file_path: file_path, file_type: file_type)
+# if you already have a document id, you can simply replace the above line with such id
+
+warb_from_new.document.dispatch(recipient_number, media_id: document_id)
+warb_from_new.document.dispatch(recipient_number, media_id: document_id, filename: "optional_name.pdf")
+warb_from_new.document.dispatch(recipient_number, media_id: document_id, caption: "OPTIONAL - Document caption")
+warb_from_new.document.dispatch(recipient_number, link: document_link)
+warb_from_new.document.dispatch(recipient_number, link: document_link, filename: "optional_name.pdf")
+warb_from_new.document.dispatch(recipient_number, link: document_link, caption: "OPTIONAL - Document caption")
+
+warb_from_new.document.dispatch(recipient_number) do |builder|
+  builder.media_id = document_id
+  builder.filename = "optional_name.pdf"
+  builder.caption = "OPTIONAL - Document caption"
+end
+
+warb_from_new.document.dispatch(recipient_number) do |builder|
+  builder.link = document_link
+  builder.filename = "optional_name.pdf"
+  builder.caption = "OPTIONAL - Document caption"
+end
+
+# ################################################# #
+# ============== Using Warb directly ============== #
+# ################################################# #
+
+Warb.document.dispatch(recipient_number, media_id: document_id)
+Warb.document.dispatch(recipient_number, media_id: document_id, filename: "optional_name.pdf")
+Warb.document.dispatch(recipient_number, media_id: document_id, caption: "OPTIONAL - Document caption")
+Warb.document.dispatch(recipient_number, link: document_link)
+Warb.document.dispatch(recipient_number, link: document_link, filename: "optional_name.pdf")
+Warb.document.dispatch(recipient_number, link: document_link, caption: "OPTIONAL - Document caption")
+
+Warb.document.dispatch(recipient_number) do |builder|
+  builder.media_id = document_id
+  builder.filename = "optional_name.pdf"
+  builder.caption = "OPTIONAL - Document caption"
+end
+
+Warb.document.dispatch(recipient_number) do |builder|
+  builder.link = document_link
+  builder.filename = "optional_name.pdf"
+  builder.caption = "OPTIONAL - Document caption"
+end

data/examples/image.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "../lib/warb"
+
+# Configure your variables here
+
+access_token = ""
+business_id = ""
+sender_id = ""
+recipient_number = ""
+
+image_link = ""
+
+# We recommend testing one section at a time, as it can be overwhelming to see all the messages at once.
+# So you can comment out the sections you don't want to test.
+
+# ############################################## #
+# ============== Using Warb.setup ============== #
+# ############################################## #
+
+warb_from_setup = Warb.setup do |config|
+  config.access_token = access_token
+  config.business_id = business_id
+  config.sender_id = sender_id
+end
+
+warb_from_setup.image.dispatch(recipient_number, link: image_link)
+warb_from_setup.image.dispatch(recipient_number, link: image_link, caption: "OPTIONAL - Image caption")
+
+# To send image using its ID, you may need to retrieve it first, which can be retrieved this way
+file_path = "" # fill this in with the file path pointing to wherever the image is located
+file_type = "" # fill this in with the mimetype of the image to be uploaded. allowed values: "image/jpeg" or "image/png"
+image_id = warb_from_setup.image.upload(file_path: file_path, file_type: file_type)
+# if you already have an image id, you can simply replace the above line with such id
+
+warb_from_setup.image.dispatch(recipient_number, media_id: image_id)
+warb_from_setup.image.dispatch(recipient_number, media_id: image_id, caption: "OPTIONAL - Image caption")
+
+warb_from_setup.image.dispatch(recipient_number) do |builder|
+  builder.media_id = image_id
+  builder.caption = "OPTIONAL - Image caption"
+end
+
+warb_from_setup.image.dispatch(recipient_number) do |builder|
+  builder.link = image_link
+  builder.caption = "OPTIONAL - Image caption"
+end
+
+# ############################################ #
+# ============== Using Warb.new ============== #
+# ############################################ #
+
+warb_from_new = Warb.new(
+  access_token: access_token,
+  business_id: business_id,
+  sender_id: sender_id
+)
+
+# Same as stated above, if you need an image id, you can upload it this way
+file_path = "" # fill this in with the file path pointing to wherever the image is located
+file_type = "" # fill this in with the mimetype of the image to be uploaded. allowed values: "image/jpeg" or "image/png"
+image_id = warb_from_new.image.upload(file_path: file_path, file_type: file_type)
+# if you already have an image id, you can simply replace the above line with such id
+
+warb_from_new.image.dispatch(recipient_number, media_id: image_id)
+warb_from_new.image.dispatch(recipient_number, media_id: image_id, caption: "OPTIONAL - Image caption")
+warb_from_new.image.dispatch(recipient_number, link: image_link)
+warb_from_new.image.dispatch(recipient_number, link: image_link, caption: "OPTIONAL - Image caption")
+
+warb_from_new.image.dispatch(recipient_number) do |builder|
+  builder.media_id = image_id
+  builder.caption = "OPTIONAL - Image caption"
+end
+
+warb_from_new.image.dispatch(recipient_number) do |builder|
+  builder.link = image_link
+  builder.caption = "OPTIONAL - Image caption"
+end
+
+# ################################################# #
+# ============== Using Warb directly ============== #
+# ################################################# #
+
+Warb.image.dispatch(recipient_number, media_id: image_id)
+Warb.image.dispatch(recipient_number, media_id: image_id, caption: "OPTIONAL - Image caption")
+Warb.image.dispatch(recipient_number, link: image_link)
+Warb.image.dispatch(recipient_number, link: image_link, caption: "OPTIONAL - Image caption")
+
+Warb.image.dispatch(recipient_number) do |builder|
+  builder.media_id = image_id
+  builder.caption = "OPTIONAL - Image caption"
+end
+
+Warb.image.dispatch(recipient_number) do |builder|
+  builder.link = image_link
+  builder.caption = "OPTIONAL - Image caption"
+end

data/examples/interactive_call_to_action_url.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require_relative "../lib/warb"
+
+# Configure your variables here
+
+access_token = ""
+business_id = ""
+sender_id = ""
+recipient_number = ""
+
+# You can use Resources to create headers for your messages.
+text_header = Warb::Resources::Text.as_header("OPTIONAL - Header")
+image_header = Warb::Resources::Image.as_header(media_id: image_id)
+video_header = Warb::Resources::Video.as_header(link: image_url)
+
+# You can use Action Components to create actions for your messages.
+action_component = Warb::Components::CTAAction.new(button_text: "Action button text", url: "https://www.rebase.com.br")
+
+# We recommend testing one section at a time, as it can be overwhelming to see all the messages at once.
+# So you can comment out the sections you don't want to test.
+
+# ############################################## #
+# ============== Using Warb.setup ============== #
+# ############################################## #
+
+warb_from_setup = Warb.setup do |config|
+  config.access_token = access_token
+  config.business_id = business_id
+  config.sender_id = sender_id
+end
+
+warb_from_setup.interactive_call_to_action_url.dispatch(
+  recipient_number,
+  header: text_header,
+  body: "body",
+  footer: "footer",
+  action: action_component
+)
+
+warb_from_setup.interactive_call_to_action_url.dispatch(
+  recipient_number,
+  header: image_header,
+  body: "body",
+  footer: "footer",
+  action: action_component
+)
+
+warb_from_setup.interactive_call_to_action_url.dispatch(
+  recipient_number,
+  header: video_header,
+  body: "body",
+  footer: "footer",
+  action: action_component
+)
+
+warb_from_setup.interactive_call_to_action_url.dispatch(recipient_number) do |builder|
+  # OPTIONAL Headers: you can choose between text, image, or video headers.
+
+  builder.set_text_header("Text Header")
+
+  # If you want to use an image header, uncomment the line below and provide a valid or Media ID or Link.
+  # builder.set_image_header(media_id: image_id) # or builder.set_image_header(link: image_link)
+
+  # If you want to use a video header, uncomment the line below and provide a valid Media ID or Link.
+  # builder.set_video_header(media_id: video_id) # or builder.set_video_header(link: video_link)
+
+  builder.body = "body"
+  builder.footer = "footer"
+
+  builder.build_action do |action|
+    action.button_text = "Action Button Text"
+    action.url = "https://www.rebase.com.br"
+  end
+end
+
+# ############################################ #
+# ============== Using Warb.new ============== #
+# ############################################ #
+
+warb_from_new = Warb.new(
+  access_token: access_token,
+  business_id: business_id,
+  sender_id: sender_id
+)
+
+warb_from_new.interactive_call_to_action_url.dispatch(
+  recipient_number,
+  header: text_header,
+  body: "body",
+  footer: "footer",
+  action: action_component
+)
+
+warb_from_new.interactive_call_to_action_url.dispatch(
+  recipient_number,
+  header: image_header,
+  body: "body",
+  footer: "footer",
+  action: action_component
+)
+
+warb_from_new.interactive_call_to_action_url.dispatch(
+  recipient_number,
+  header: video_header,
+  body: "body",
+  footer: "footer",
+  action: action_component
+)
+
+warb_from_new.interactive_call_to_action_url.dispatch(recipient_number) do |builder|
+  # Headers: you can choose between text, image, or video headers.
+
+  builder.set_text_header("Text Header")
+
+  # If you want to use an image header, uncomment the line below and provide a valid or Media ID or Link.
+  # builder.set_image_header(media_id: image_id) # or builder.set_image_header(link: image_link)
+
+  # If you want to use a video header, uncomment the line below and provide a valid Media ID or Link.
+  # builder.set_video_header(media_id: video_id) # or builder.set_video_header(link: video_link)
+
+  builder.body = "body"
+  builder.footer = "footer"
+
+  builder.build_action do |action|
+    action.button_text = "Action Button Text"
+    action.url = "https://www.rebase.com.br"
+  end
+end
+
+# ################################################# #
+# ============== Using Warb directly ============== #
+# ################################################# #
+
+Warb.interactive_call_to_action_url.dispatch(
+  recipient_number,
+  header: text_header,
+  body: "body",
+  footer: "footer",
+  action: action_component
+)
+
+Warb.interactive_call_to_action_url.dispatch(
+  recipient_number,
+  header: image_header,
+  body: "body",
+  footer: "footer",
+  action: action_component
+)
+
+Warb.interactive_call_to_action_url.dispatch(
+  recipient_number,
+  header: video_header,
+  body: "body",
+  footer: "footer",
+  action: action_component
+)
+
+Warb.interactive_call_to_action_url.dispatch(recipient_number) do |builder|
+  # Headers: you can choose between text, image, or video headers.
+
+  builder.set_text_header("Text Header")
+
+  # If you want to use an image header, uncomment the line below and provide a valid or Media ID or Link.
+  # builder.set_image_header(media_id: image_id) # or builder.set_image_header(link: image_link)
+
+  # If you want to use a video header, uncomment the line below and provide a valid Media ID or Link.
+  # builder.set_video_header(media_id: video_id) # or builder.set_video_header(link: video_link)
+
+  builder.body = "body"
+  builder.footer = "footer"
+
+  builder.build_action do |action|
+    action.button_text = "Action Button Text"
+    action.url = "https://www.rebase.com.br"
+  end
+end