whatsapp_sdk 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3afc828e9c913c0aa1988b1ec75dcbd6453f13f67d46f3a25c77ef2558aacf8c
-  data.tar.gz: 64d8ea9e6c36c6d37c8dad014ee1dab10d906df4dcb7777206f6fc7300af44b6
+  metadata.gz: 53c16bc6791e7862e5e35d1324792e0c0cea54a171e2f861f3e834ec3751e196
+  data.tar.gz: 610c042ac0cf2c095251c2bef1768776260a1d47e93898dd69c410609e6e722a
 SHA512:
-  metadata.gz: 4c4e910413ddf8366abd12b1aaed78e8a47d69b1cc979f7afaae00fc644ff9f735f6c1f594749de242fc87c70f6c2c7c9ccf6c215c2e85bda40f0f6540fc3a55
-  data.tar.gz: 5a2bac9b5b4f416af7abbfbdf07c91717b517f7c030fcb47c767c4d2863c538e2b03402ff3a0968b7a889b4748f3c5a14d1e4b75f1cbc75f238a1888d5cc78d1
+  metadata.gz: 8fdce7569dbb71b96744ee296feb1e90ee5c5300e82ce860550d0e1c3c4c9521ddc88c2ce7f5924c41f0559b17e7d301e9b81c1c0a78e881abc42bcae8102bd1
+  data.tar.gz: cab5e1753ee9ef35b05f7409ceb42af407cd6242dffa4a975a9f511bef417b05cc0cb221b7195508fcb53e7e912c9c5a24ff49eaa4c3df65cda199d16567a11e

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Unreleased
 
+# v 0.12.0
+- Added ability to specify logger @chahmedejaz [#129](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/129)
+- Allow download of unsupported media types @dvuckovic [#128](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/128)
+- Allow users to specify the API version. @conr [#126](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/126)
+- Use http multipart only when is needed. @ignacio-chiazzo [#123](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/123)
+- Validate Vertical on BusinessProfile update API. @ignacio-chiazzo [#120](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/120)
+- Added ability to specify fields param in the busines profile API. @ignacio-chiazzo [#119](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/119)
+
 # v 0.11.0
 - Bumped API version to v19. @paulomcnally  https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/116
 

data/CONTRIBUTING.MD

@@ -0,0 +1,30 @@
+Bug reports and pull requests are welcome on GitHub at [https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk) This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+If you want a feature implemented in the gem, please open an issue, and we will look as soon as we can. 
+
+Do you want to contribute and are unsure where to start? Ping me on Twitter, and I will help you!
+
+### Getting started
+
+Clone the project and ensure tests are passing locally.
+
+```console
+bundle install
+bundle exec rake test
+```
+
+#### Configure an App and enable WhatsApp
+
+Follow the steps in the [Readme#set-up-a-meta-app](/README.md#set-up-a-meta-app)
+
+#### Architecture
+
+The main logic lives under `/lib`. There, you can find API classes (Medias, Messages, PhoneNumbers, etc.) and Resources (Button, Address, etc.). 
+Each API class inherits from `Request`, which contains the helper methods to make HTTP requests to Meta. 
+
+If you are new to the code, a good place to start is looking at [closed PRs](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pulls?q=is%3Apr+is%3Aclosed). Here are some helpful PRs: 
+- [Added a new Templates API](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/90)
+- [Added an error when the user entered a bad input](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/89/files)
+- [Change on Faraday configuration](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/123/files).
+
+ Do you want to contribute and are unsure where to start? Ping me on Twitter, and I will help you!

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    whatsapp_sdk (0.11.0)
+    whatsapp_sdk (0.12.0)
       faraday (~> 2)
       faraday-multipart (~> 1)
       sorbet-runtime (~> 0.5)
@@ -17,8 +17,7 @@ GEM
     coderay (1.1.3)
     crack (0.4.5)
       rexml
-    diff-lcs (1.5.0)
-    faraday (2.7.12)
+    faraday (2.8.1)
       base64
       faraday-net_http (>= 2.0, < 3.1)
       ruby2_keywords (>= 0.0.4)
@@ -29,8 +28,7 @@ GEM
     method_source (1.0.0)
     minitest (5.16.1)
     mocha (1.14.0)
-    multipart-post (2.3.0)
-    netrc (0.11.0)
+    multipart-post (2.4.0)
     parallel (1.22.1)
     parser (3.1.2.0)
       ast (~> 2.4.1)
@@ -42,11 +40,6 @@ GEM
     public_suffix (5.0.0)
     rainbow (3.1.1)
     rake (12.3.3)
-    rbi (0.0.15)
-      ast
-      parser (>= 2.6.4.0)
-      sorbet-runtime (>= 0.5.9204)
-      unparser
     regexp_parser (2.5.0)
     rexml (3.2.5)
     rubocop (1.30.1)
@@ -75,39 +68,18 @@ GEM
     sorbet-static (0.5.10346-universal-darwin-19)
     sorbet-static (0.5.10346-universal-darwin-21)
     sorbet-static (0.5.10346-x86_64-linux)
-    sorbet-static-and-runtime (0.5.10346)
-      sorbet (= 0.5.10346)
-      sorbet-runtime (= 0.5.10346)
     spoom (1.1.12)
       sorbet (>= 0.5.9204)
       sorbet-runtime (>= 0.5.9204)
       thor (>= 0.19.2)
-    tapioca (0.9.4)
-      bundler (>= 1.17.3)
-      netrc (>= 0.11.0)
-      parallel (>= 1.21.0)
-      pry (>= 0.12.2)
-      rbi (~> 0.0.0, >= 0.0.14)
-      sorbet-static-and-runtime (>= 0.5.9204)
-      spoom (~> 1.1.0, >= 1.1.11)
-      thor (>= 1.2.0)
-      yard-sorbet
+    tapioca (0.0.1)
     thor (1.2.1)
     unicode-display_width (2.2.0)
-    unparser (0.6.5)
-      diff-lcs (~> 1.3)
-      parser (>= 3.1.0)
     webmock (3.18.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    webrick (1.7.0)
-    yard (0.9.28)
-      webrick (~> 1.7.0)
-    yard-sorbet (0.7.0)
-      sorbet-runtime (>= 0.5)
-      yard (>= 0.9)
-    zeitwerk (2.6.12)
+    zeitwerk (2.6.13)
 
 PLATFORMS
   arm64-darwin-21

data/README.md

@@ -1,4 +1,5 @@
 # Ruby Whatsapp SDK
+
 [![Gem Version](https://badge.fury.io/rb/whatsapp_sdk.svg)](https://badge.fury.io/rb/whatsapp_sdk)
 [![CircleCI](https://circleci.com/gh/circleci/circleci-docs.svg?style=svg)](https://circleci.com/gh/ignacio-chiazzo/ruby_whatsapp_sdk)
 <a href="https://codeclimate.com/github/ignacio-chiazzo/ruby_whatsapp_sdk/maintainability"><img src="https://api.codeclimate.com/v1/badges/169cce95450272e4ad7d/maintainability" /></a>
@@ -6,7 +7,6 @@
 The SDK provides a set of operations and classes to use the Whatsapp API.
 Send stickers, messages, audio, videos, locations, react and reply to messages or just ask for the phone numbers through this library in a few steps!
 
-
 ## Demo
 
 https://user-images.githubusercontent.com/11672878/173238826-6fc0a6f8-d0ee-4eae-8947-7dfd3b8b3446.mov
@@ -35,21 +35,37 @@ There are three primary resources, `Messages`, `Media` and `PhoneNumbers`. `Mess
 
 To use `Messages`, `Media` or `PhoneNumbers`, you need to initialize the `Client` that contains auth information. There are two ways to do it.
 
-1) Use an initializer
-  
+1. Use an initializer
+
+Note:
+Optionally, you can specify the desired API version to use (defaults to the latest version if omitted).
+Available API version can be found [here](https://developers.facebook.com/docs/graph-api/changelog/versions).
+
 ```ruby
 # config/initializers/whatsapp_sdk.rb
 WhatsappSdk.configure do |config|
   config.access_token = ACCESS_TOKEN
+  config.api_version = API_VERSION
+  config.logger = Logger.new(STDOUT) # optional, Faraday logger to attach
+  config.logger_options = { bodies: true } # optional, they are all valid logger_options for Faraday
 end
 ```
+More Details on Faraday Logger Options are [here](https://lostisland.github.io/faraday/#/middleware/included/logging?id=logging).
+
 OR 2) Create a `Client` instance and pass it to the `Messages`, `Medias` or `PhoneNumbers` instance like this:
 
+**Without Logger:**
 ```ruby
 client = WhatsappSdk::Api::Client.new("<ACCESS TOKEN>") # replace this with a valid access token
 messages_api = WhatsappSdk::Api::Messages.new(client)
 ```
-
+**With Logger:**
+```ruby
+logger = Logger.new(STDOUT)
+logger_options = { bodies: true }
+client = WhatsappSdk::Api::Client.new("<ACCESS TOKEN>", "<API VERSION>", logger, logger_options) # replace this with a valid access token
+messages_api = WhatsappSdk::Api::Messages.new(client)
+```
 Each API operation returns a `WhatsappSdk::Api::Response` that contains `data` and `error` and a couple of helpful functions such as `ok?` and `error?`. There are three types of responses `WhatsappSdk::Api::MessageDataResponse`, `WhatsappSdk::Api::PhoneNumberDataResponse` and `WhatsappSdk::Api::PhoneNumbersDataResponse`. Each of them contains different attributes.
 
 ## Set up a Meta app
@@ -68,7 +84,7 @@ Each API operation returns a `WhatsappSdk::Api::Response` that contains `data` a
 
 Try sending a message to your phone in the UI.
 
-<details><summary>4) Copy the ACCESS_TOKEN, the SENDER_ID, the BUSINESS_ID and the RECEIPIENT_NUMBER</summary>
+<details><summary>4) Copy the ACCESS_TOKEN, the SENDER_ID, the BUSINESS_ID and the RECIPIENT_NUMBER</summary>
 <img width="1010" alt="Screen Shot 2022-09-05 at 11 13 24 AM" src="https://user-images.githubusercontent.com/11672878/188480634-369f8de1-b851-4735-86de-f49e96f78d8c.png">
 </details>
 
@@ -76,11 +92,12 @@ Try sending a message to your phone in the UI.
 
 <details><summary>5) Use the GEM to interact with Whatsapp</summary>
 
-Example: 
-1) Install the gem by running `gem install whatsapp_sdk` in the gem.
-2) Open the irb terminal by running `irb` 
-3) `require "whatsapp_sdk"` 
-4) Set up the `ACCESS_TOKEN`, the `SENDER_ID`, the `BUSINESS_ID` and the `RECEIPIENT_NUMBER` in variables.
+Example:
+
+1. Install the gem by running `gem install whatsapp_sdk` in the gem.
+2. Open the irb terminal by running `irb`
+3. `require "whatsapp_sdk"`
+4. Set up the `ACCESS_TOKEN`, the `SENDER_ID`, the `BUSINESS_ID` and the `RECIPIENT_NUMBER` in variables.
 
 ```ruby
 ACCESS_TOKEN = "EAAZAvvr0DZBs0BABRLF8zohP5Epc6pyNu"
@@ -89,7 +106,7 @@ SENDER_ID = 1234567891011
 RECIPIENT_NUMBER = 12398765432
 ```
 
-5) Configure the Client by running 
+5. Configure the Client by running
 
 ```ruby
 WhatsappSdk.configure do |config|
@@ -97,15 +114,17 @@ WhatsappSdk.configure do |config|
 end
 ```
 
-6) Try the Phone Numbers API or Messages API
+6. Try the Phone Numbers API or Messages API
 
 Phone Numbers API
+
 ```ruby
 phone_numbers_api = WhatsappSdk::Api::PhoneNumbers.new
 registered_number = phone_numbers_api.registered_number(SENDER_ID)
 ```
 
 Messages API
+
 ```ruby
 messages_api = WhatsappSdk::Api::Messages.new
 message_sent = messages_api.send_text(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER,
@@ -117,6 +136,7 @@ Check the [example.rb file](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk
 </details>
 
 ## Operations
+
 First, create the client and then create an instance `WhatsappSdk::Api::Messages` that requires a client as a param like this:
 
 ```ruby
@@ -132,6 +152,7 @@ Note: Remember to initialize the client first!
 ## APIs
 
 ### Templates
+
 <details>
 
 ```ruby
@@ -142,25 +163,30 @@ templates_api.templates(business_id: BUSINESS_ID)
 new_template = templates_api.create(
   business_id: BUSINESS_ID, name: "seasonal_promotion", language: "en_US", category: "MARKETING",
   components_json: components_json, allow_category_change: true
-) 
+)
 
 # Delete a template
 templates_api.delete(business_id: BUSINESS_ID, name: "my_name") # delete by name
 ```
+
 </details>
 
 ### Business Profile API
+
 <details>
 
 Get the details of your business
+
 ```ruby
 business_profile = business_profile_api.details(123456)
 ```
 
 Update the details of your business
+
 ```ruby
 business_profile_api.update(phone_number_id: SENDER_ID, params: { about: "A very cool business" } )
 ```
+
 </details>
 
 ### Phone numbers API
@@ -168,45 +194,55 @@ business_profile_api.update(phone_number_id: SENDER_ID, params: { about: "A very
 <details>
 
 Get the list of phone numbers registered
+
 ```ruby
 phone_numbers_api.registered_numbers(123456) # accepts a business_id
 ```
 
 Get the a phone number by id
+
 ```ruby
 phone_numbers_api.registered_numbers(123456) # accepts a phone_number_id
 ```
 
 Register a phone number
+
 ```ruby
 phone_numbers_api.register_number(phone_number_id, pin)
 ```
 
 Deregister a phone number
+
 ```ruby
 phone_numbers_api.deregister_number(phone_number_id)
 ```
+
 </details>
 
 ### Media API
+
 <details>
 
 Upload a media
+
 ```ruby
 medias_api.upload(sender_id: SENDER_ID, file_path: "tmp/whatsapp.png", type: "image/png")
 ```
 
 Get a media
+
 ```ruby
 media = medias_api.media(media_id: MEDIA_ID)
 ```
 
 Download media
+
 ```ruby
 medias_api.download(url: MEDIA_URL, file_path: 'tmp/downloaded_whatsapp.png', media_type: "image/png")
 ```
 
 Delete a media
+
 ```ruby
 medias_api.delete(media_id: MEDIA_ID)
 ```
@@ -214,6 +250,7 @@ medias_api.delete(media_id: MEDIA_ID)
 </details>
 
 ### Messages API
+
 <details>
 
 **Send a text message**
@@ -223,6 +260,7 @@ messages_api.send_text(sender_id: 1234, recipient_number: 112345678, message: "h
 ```
 
 **Read a message**
+
 ```ruby
 messages_api.read_message(sender_id: 1234, message_id: "wamid.HBgLMTM0M12345678910=")
 ```
@@ -230,7 +268,7 @@ messages_api.read_message(sender_id: 1234, message_id: "wamid.HBgLMTM0M123456789
 Note: To get the `message_id` you can set up [Webhooks](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components) that will listen and fire an event when a message is received.
 
 **Send a reaction to message**
-To send a reaction to a message, you need to obtain the mssage id and look for the emoji's unicode you want to use.
+To send a reaction to a message, you need to obtain the message id and look for the emoji's unicode you want to use.
 
 ```ruby
 messages_api.send_reaction(sender_id: 123_123, recipient_number: 56_789, message_id: "12345", emoji: "\u{1f550}")
@@ -256,6 +294,7 @@ messages_api.send_location(
 
 **Send an image message**
 It could use a link or an image_id.
+
 ```ruby
 # with a link
 messages_api.send_image(
@@ -270,6 +309,7 @@ messages_api.send_image(
 
 **Send an audio message**
 It could use a link or an audio_id.
+
 ```ruby
 # with a link
 messages_api.send_audio(sender_id: 123123, recipient_number: 56789, link: "audio_link")
@@ -280,6 +320,7 @@ messages_api.send_audio(sender_id: 123123, recipient_number: 56789, audio_id: "1
 
 **Send a document message**
 It could use a link or a document_id.
+
 ```ruby
 # with a link
 messages_api.send_document(
@@ -294,6 +335,7 @@ messages_api.send_document(
 
 **Send a sticker message**
 It could use a link or a sticker_id.
+
 ```ruby
 # with a link
 messages_api.send_sticker(sender_id: 123123, recipient_number: 56789, link: "link")
@@ -310,7 +352,8 @@ contacts = [create_contact(params)]
 messages_api.send_contacts(sender_id: 123123, recipient_number: 56789, contacts: contacts)
 ```
 
-Alernative, you could pass a plain json like this:
+Alternatively, you could pass a plain json like this:
+
 ```ruby
 messages_api.send_contacts(sender_id: 123123, recipient_number: 56789, contacts_json: {...})
 ```
@@ -328,7 +371,7 @@ date_time = WhatsappSdk::Resource::DateTime.new(fallback_value: "2020-01-01T00:0
 image = WhatsappSdk::Resource::Media.new(type: "image", link: "http(s)://URL")
 
 parameter_image = WhatsappSdk::Resource::ParameterObject.new(type: WhatsappSdk::Resource::ParameterObject::Type::Image, image: image)
-# You can also use a plain string as type e.g. 
+# You can also use a plain string as type e.g.
 # parameter_image = WhatsappSdk::Resource::ParameterObject.new(type: "image", image: image)
 parameter_text = WhatsappSdk::Resource::ParameterObject.new(type: WhatsappSdk::Resource::ParameterObject::Type::Text, text: "TEXT_STRING")
 parameter_currency = WhatsappSdk::Resource::ParameterObject.new(type: WhatsappSdk::Resource::ParameterObject::Type::Currency, currency: currency)
@@ -366,7 +409,8 @@ button_component2 = WhatsappSdk::Resource::Component.new(
 
 </details>
 
-Alernative, you could pass a plain json like this:
+Alternatively, you could pass a plain json like this:
+
 ```ruby
 @messages_api.send_template(sender_id: 12_345, recipient_number: 12345678, name: "hello_world", language: "en_US", components_json: [{...}])
 ```
@@ -421,9 +465,11 @@ messages_api.send_interactive_list_messages(
   interactive: interactive_list_messages
 )
 ```
+
 </details>
 
-Alternative, you could pass a plain json like this:
+Alternatively, you could pass a plain json like this:
+
 ```ruby
 messages_api.send_interactive_list_messages(
   sender_id: 12_345, recipient_number: 1234567890
@@ -477,17 +523,19 @@ messages_api.send_interactive_reply_buttons(
   interactive: interactive_reply_buttons
 )
 ```
+
 </details>
 
 Alternative, you could pass a plain json like this:
+
 ```ruby
 messages_api.send_interactive_reply_buttons(
   sender_id: 12_345, recipient_number: 1234567890
   interactive_json: {...}
 )
 ```
-</details>
 
+</details>
 
 ## Examples
 
@@ -500,11 +548,11 @@ Visit [the example file](/example.rb) with examples to call the API in a single
 
 ## Troubleshooting
 
-- If the API response is `success`,  but the message is not delivered, ensure the device you're sending the message to is using a supported Whatsapp version. [Check documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/support/troubleshooting#message-not-delivered). Try also replying a message to the number you are registered on your Whatsapp.
+- If the API response is `success`, but the message is not delivered, ensure the device you're sending the message to is using a supported Whatsapp version. [Check documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/support/troubleshooting#message-not-delivered). Try also replying a message to the number you are registered on your Whatsapp.
 - Ensure your Meta App uses an API version greater than or equal to `v.14`.
 - Ensure that the Panel in the Facebook dashboard doesn't display any errors.
 
-Note: Sometimes the messages are delayed; see [Meta documentation](https://developers.facebook.com/docs/whatsapp/on-premises/guides/send-message-performance#delays). 
+Note: Sometimes the messages are delayed; see [Meta documentation](https://developers.facebook.com/docs/whatsapp/on-premises/guides/send-message-performance#delays).
 
 ## Development
 
@@ -513,22 +561,23 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 Run ' bundle exec rake install ' to install this gem onto your local machine. 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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ### Run all the tests
+
 - **Unit tests:** Run `rake test`
 - **Sorbet Typecheck:** run `srb tc`
 - **Linters:** `bundle exec rubocop`
 
-
 To update the Cloud API version update the version in `lib/whatsapp_sdk/api/api_configuration.rb`. Check the [Cloud API changelog for API udpates](https://developers.facebook.com/docs/whatsapp/business-platform/changelog#api-error-response-behavior).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk) This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-If you want a feature to be implemented in the gem, please, open an issue and we will take a look as soon as we can. 
-
+If you want a feature to be implemented in the gem, please, open an issue and we will take a look as soon as we can.
 
 Do you want to contribute and are unsure where to start? Ping me on Twitter, and I will help you!
 
+Check [Contributing](/CONTRIBUTING.MD) file.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/config/api_versions.yml

@@ -0,0 +1,32 @@
+- v19.0
+- v18.0
+- v17.0
+- v16.0
+- v15.0
+- v14.0
+- v13.0
+- v12.0
+- v11.0
+- v10.0
+- v9.0
+- v8.0
+- v7.0
+- v6.0
+- v5.0
+- v4.0
+- v3.3
+- v3.2
+- v3.1
+- v3.0
+- v2.12
+- v2.11
+- v2.10
+- v2.9
+- v2.8
+- v2.7
+- v2.6
+- v2.5
+- v2.4
+- v2.3
+- v2.2
+- v2.1

data/example.rb

@@ -33,6 +33,8 @@ if ACCESS_TOKEN == "<TODO replace>"
   exit
 end
 
+puts "\n\n\n\n\n\n ***************    Starting calling the Cloud API    *************** \n"
+
 ################# Initialize Client #################
 WhatsappSdk.configure do |config|
   config.access_token = ACCESS_TOKEN
@@ -46,6 +48,14 @@ def print_message_sent(message_response)
     puts "Error: #{message_response.error&.to_s}"
   end
 end
+
+def print_data_or_error(response, identifier)
+  if response.error?
+    return "Error: #{response.error&.to_s}"
+  end
+
+  return identifier
+end
 ##################################################
 
 
@@ -56,12 +66,13 @@ business_profile_api = WhatsappSdk::Api::BusinessProfile.new
 templates_api = WhatsappSdk::Api::Templates.new
 
 ############################## Templates API ##############################
-
 ## Get list of templates
-templates_api.templates(business_id: BUSINESS_ID)
+templates = templates_api.templates(business_id: BUSINESS_ID)
+puts "GET Templates list : #{print_data_or_error(templates, templates.data&.templates.map { |r| r.template.name })}"
 
 ## Get message templates namespace
-templates_api.get_message_template_namespace(business_id: BUSINESS_ID)
+template_namespace = templates_api.get_message_template_namespace(business_id: BUSINESS_ID)
+puts "GET template by namespace: #{print_data_or_error(template_namespace, template_namespace.data&.id)}"
 
 # Create a template
 components_json = [
@@ -97,6 +108,7 @@ new_template = templates_api.create(
   business_id: BUSINESS_ID, name: "seasonal_promotion", language: "ka", category: "MARKETING",
   components_json: components_json, allow_category_change: true
 )
+puts "GET template by namespace: #{print_data_or_error(template_namespace, template_namespace.data&.id)}"
 
 # Update a template
 components_json = [
@@ -112,66 +124,83 @@ components_json = [
     ]
   }
 ]
-templates_api.update(template_id: "1624560287967996", category: "UTILITY")
+updated_template = templates_api.update(template_id: "1624560287967996", category: "UTILITY")
+puts "UPDATE template by id: #{print_data_or_error(updated_template, updated_template.data&.id)}"
 
 ## Delete a template
-templates_api.delete(business_id: BUSINESS_ID, name: "seasonal_promotion") # delete by name
+delete_template = templates_api.delete(business_id: BUSINESS_ID, name: "seasonal_promotion") # delete by name
+puts "DELETE template by id: #{print_data_or_error(delete_template, delete_template.data&.id) }"
 # templates_api.delete(business_id: BUSINESS_ID, name: "name2", hsm_id: "243213188351928") # delete by name and id
 
 ############################## Business API ##############################
 business_profile = business_profile_api.details(SENDER_ID)
-business_profile_api.update(phone_number_id: SENDER_ID, params: { about: "A very cool business" } )
+puts "DELETE Business Profile by id: #{print_data_or_error(delete_template, business_profile.data&.id) }"
+
+updated_bp = business_profile_api.update(phone_number_id: SENDER_ID, params: { about: "A very cool business" } )
+puts "UPDATE Business Profile by id: #{print_data_or_error(updated_bp, updated_bp.data&.id) }"
 
 ############################## Phone Numbers API ##############################
 registered_number = phone_numbers_api.registered_number(SENDER_ID)
+puts "GET Registered number: #{print_data_or_error(registered_number, registered_number.data&.id)}"
+
 registered_numbers = phone_numbers_api.registered_numbers(BUSINESS_ID)
+puts "GET Registered numbers: #{print_data_or_error(registered_number, registered_numbers.data&.phone_numbers.map(&:id))}"
 
 ############################## Media API ##############################
 
 ##### Image #####
 # upload a Image
 uploaded_media = medias_api.upload(sender_id: SENDER_ID, file_path: "tmp/whatsapp.png", type: "image/png")
-media_id = uploaded_media.data&.id
-puts "Uploaded media id: #{media_id}"
+puts "Uploaded media id: #{print_data_or_error(uploaded_media, uploaded_media.data&.id)}"
 
 # get a media Image
-media = medias_api.media(media_id: media_id).data
-puts "Media info: #{media.raw_data_response}"
+if uploaded_media.data&.id
+  media = medias_api.media(media_id: uploaded_media.data&.id)
+  puts "GET Media id: #{print_data_or_error(media, media.data&.id)}"
 
-# download media Image
-download_image = medias_api.download(url: media.url, file_path: 'tmp/downloaded_image.png', media_type: "image/png")
-puts "Downloaded: #{download_image.data.success?}"
+  # download media Image
+  download_image = medias_api.download(url: media.data.url, file_path: 'tmp/downloaded_image.png', media_type: "image/png")
+  puts "Downloaded: #{print_data_or_error(download_image, download_image.data.success?)}"
 
-# delete a media
-deleted_media = medias_api.delete(media_id: media&.id)
-puts "Deleted: #{deleted_media.data.success?}"
+  # delete a media
+  deleted_media = medias_api.delete(media_id: media.data.id)
+  puts "DELETE: #{print_data_or_error(deleted_media, deleted_media.data.success?)}"
+end
 
 #### Audio ####
 # upload an audio
 uploaded_media = medias_api.upload(sender_id: SENDER_ID, file_path: "tmp/downloaded_audio.ogg", type: "audio/ogg")
+puts "Uploaded media id: #{print_data_or_error(uploaded_media, uploaded_media.data&.id)}"
+
+if uploaded_media.data&.id
+media_id = uploaded_media.data&.id
 media_id = uploaded_media.data&.id
+puts "Uploaded media id: #{media_id}"
+  media_id = uploaded_media.data&.id
 puts "Uploaded media id: #{media_id}"
 
-# get a media audio
-media = medias_api.media(media_id: media_id).data
-puts "Media info: #{media.raw_data_response}"
+  # get a media audio
+  media = medias_api.media(media_id: media_id)
+  puts "GET Media id: #{print_data_or_error(media, media.data&.id)}"
 
-# get a media audio
-audio_link = media.url
-download_image = medias_api.download(url: audio_link, file_path: 'tmp/downloaded_audio2.ogg', media_type: "audio/ogg")
-puts "Downloaded: #{download_image.data.success?}"
+  # get a media audio
+  audio_link = media.data.url
+  download_image = medias_api.download(url: audio_link, file_path: 'tmp/downloaded_audio2.ogg', media_type: "audio/ogg")
+  puts "Download Media Audio: #{print_data_or_error(download_image, download_image.data.success?)}"
+end
 
 ############################## Messages API ##############################
 
 ######### SEND A TEXT MESSAGE
-message_sent = messages_api.send_text(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER,
-                                      message: "Hey there! it's Whatsapp Ruby SDK")
+message_sent = messages_api.send_text(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, message: "Hey there! it's Whatsapp Ruby SDK")
 print_message_sent(message_sent)
 
 ######### React to a message
 message_id = message_sent.data.messages.first.id
-messages_api.send_reaction(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, message_id: message_id, emoji: "\u{1f550}")
-messages_api.send_reaction(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, message_id: message_id, emoji: "⛄️")
+reaction_1_sent = messages_api.send_reaction(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, message_id: message_id, emoji: "\u{1f550}")
+reaction_2_sent = messages_api.send_reaction(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, message_id: message_id, emoji: "⛄️")
+puts "Message Reaction 1: #{print_data_or_error(reaction_1_sent, reaction_1_sent.data&.messages.first&.id)}"
+puts "Message Reaction 2: #{print_data_or_error(reaction_2_sent, reaction_2_sent.data&.messages.first&.id)}"
 
 ######### Reply to a message
 message_to_reply_id = message_sent.data.messages.first.id
@@ -190,40 +219,49 @@ print_message_sent(location_sent)
 
 ######### SEND AN IMAGE
 # Send an image with a link
-image_sent = messages_api.send_image(
-  sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, link: media.url, caption: "Ignacio Chiazzo Profile"
-)
-print_message_sent(image_sent)
-
-# Send an image with an id
-messages_api.send_image(
-  sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, image_id: media.id, caption: "Ignacio Chiazzo Profile"
-)
+if media.data&.id
+  image_sent = messages_api.send_image(
+    sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, link: media.data.url, caption: "Ignacio Chiazzo Profile"
+  )
+  print_message_sent(image_sent)
+
+  # Send an image with an id
+  messages_api.send_image(
+    sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, image_id: media.data.id, caption: "Ignacio Chiazzo Profile"
+  )
+  print_message_sent(image_sent)
+end
 
 ######### SEND AUDIOS
 ## with a link
-messages_api.send_audio(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, link: "audio_link")
+audio_sent = messages_api.send_audio(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, link: "audio_link")
+print_message_sent(audio_sent)
 
 ## with an audio id
-messages_api.send_audio(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, audio_id: "1234")
+audio_sent = messages_api.send_audio(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, audio_id: "1234")
+print_message_sent(audio_sent)
 
 ######### SEND DOCUMENTS
 ## with a link
-messages_api.send_document(
+document_sent = messages_api.send_document(
   sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, link: "document_link", caption: "Ignacio Chiazzo"
 )
+print_message_sent(document_sent)
 
 ## with a document id
-messages_api.send_document(
+document_sent = messages_api.send_document(
   sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, document_id: "1234", caption: "Ignacio Chiazzo"
 )
+print_message_sent(document_sent)
 
 ######### SEND STICKERS
 ## with a link
-messages_api.send_sticker(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, link: "link")
+sticker_sent = messages_api.send_sticker(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, link: "link")
+print_message_sent(sticker_sent)
 
 ## with a sticker_id
-messages_api.send_sticker(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, sticker_id: "1234")
+sticker_sent = messages_api.send_sticker(sender_id: SENDER_ID, recipient_number: RECIPIENT_NUMBER, sticker_id: "1234")
+print_message_sent(sticker_sent)
 
 ######### SEND A TEMPLATE
 # Note: The template must have been created previously.

data/lib/whatsapp_sdk/api/api_configuration.rb

@@ -6,8 +6,8 @@ module WhatsappSdk
     module ApiConfiguration
       extend T::Sig
 
-      API_VERSION = T.let("v19.0", String)
-      API_URL = T.let("https://graph.facebook.com/#{API_VERSION}/", String)
+      DEFAULT_API_VERSION = T.let("v19.0", String)
+      API_URL = T.let("https://graph.facebook.com", String)
     end
   end
 end

data/lib/whatsapp_sdk/api/business_profile.rb

@@ -3,21 +3,42 @@
 
 require_relative "request"
 require_relative "response"
+require_relative "../resource/business_profile"
 
 module WhatsappSdk
   module Api
     class BusinessProfile < Request
       DEFAULT_FIELDS = 'about,address,description,email,profile_picture_url,websites,vertical'
 
+      class InvalidVertical < StandardError
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_accessor :message
+
+        sig { params(vertical: String).void }
+        def initialize(vertical:)
+          @message = "invalid vertical #{vertical}. See the supported types in the official documentation " \
+                     "https://developers.facebook.com/docs/whatsapp/cloud-api/reference/business-profiles"
+          super
+        end
+      end
+
       # Get the details of business profile.
       #
       # @param phone_number_id [Integer] Phone Number Id.
       # @return [Api::Response] Response object.
-      sig { params(phone_number_id: Integer).returns(Api::Response) }
-      def details(phone_number_id)
+      sig { params(phone_number_id: Integer, fields: T.nilable(T::Array[String])).returns(Api::Response) }
+      def details(phone_number_id, fields: nil)
+        fields = if fields
+                   fields.join(',')
+                 else
+                   DEFAULT_FIELDS
+                 end
+
         response = send_request(
           http_method: "get",
-          endpoint: "#{phone_number_id}/whatsapp_business_profile?fields=#{DEFAULT_FIELDS}"
+          endpoint: "#{phone_number_id}/whatsapp_business_profile?fields=#{fields}"
         )
 
         Api::Response.new(
@@ -39,6 +60,7 @@ module WhatsappSdk
       def update(phone_number_id:, params:)
         # this is a required field
         params[:messaging_product] = 'whatsapp'
+        return raise InvalidVertical.new(vertical: params[:vertical]) unless valid_vertical?(params)
 
         response = send_request(
           http_method: "post",
@@ -51,6 +73,15 @@ module WhatsappSdk
           data_class_type: Api::Responses::SuccessResponse
         )
       end
+
+      private
+
+      sig { params(params: T::Hash[T.untyped, T.untyped]).returns(T::Boolean) }
+      def valid_vertical?(params)
+        return true unless params[:vertical]
+
+        WhatsappSdk::Resource::BusinessProfile::VERTICAL_VALUES.include?(params[:vertical])
+      end
     end
   end
 end

data/lib/whatsapp_sdk/api/client.rb

@@ -3,15 +3,35 @@
 
 require "faraday"
 require "faraday/multipart"
+require "yaml"
 
 module WhatsappSdk
   module Api
     class Client
       extend T::Sig
 
-      sig { params(access_token: String).void }
-      def initialize(access_token)
+      API_VERSIONS = T.let(YAML.load_file("config/api_versions.yml"), T::Array[String])
+
+      sig do
+        params(
+          access_token: String,
+          api_version: String,
+          logger: T.nilable(T.any(Logger, T.class_of(Logger))),
+          logger_options: Hash
+        ).void
+      end
+      def initialize(
+        access_token,
+        api_version = ApiConfiguration::DEFAULT_API_VERSION,
+        logger = nil,
+        logger_options = {}
+      )
         @access_token = access_token
+        @logger = logger
+        @logger_options = logger_options
+
+        validate_api_version(api_version)
+        @api_version = api_version
       end
 
       sig do
@@ -20,13 +40,14 @@ module WhatsappSdk
           full_url: T.nilable(String),
           http_method: String,
           params: T::Hash[T.untyped, T.untyped],
-          headers: T::Hash[T.untyped, T.untyped]
+          headers: T::Hash[T.untyped, T.untyped],
+          multipart: T::Boolean
         ).returns(T.nilable(T::Hash[T.untyped, T.untyped]))
       end
-      def send_request(endpoint: "", full_url: nil, http_method: "post", params: {}, headers: {})
-        url = full_url || ApiConfiguration::API_URL
+      def send_request(endpoint: "", full_url: nil, http_method: "post", params: {}, headers: {}, multipart: false)
+        url = full_url || "#{ApiConfiguration::API_URL}/#{@api_version}/"
 
-        faraday_request = T.unsafe(faraday(url))
+        faraday_request = T.unsafe(faraday(url: url, multipart: multipart))
 
         response = faraday_request.public_send(http_method, endpoint, request_params(params, headers), headers)
 
@@ -69,15 +90,21 @@ module WhatsappSdk
         params
       end
 
-      sig { params(url: String).returns(Faraday::Connection) }
-      def faraday(url)
+      sig { params(url: String, multipart: T::Boolean).returns(Faraday::Connection) }
+      def faraday(url:, multipart: false)
         ::Faraday.new(url) do |client|
-          client.request :multipart
-          client.request :url_encoded
-          client.adapter ::Faraday.default_adapter
+          client.request(:multipart) if multipart
+          client.request(:url_encoded)
+          client.adapter(::Faraday.default_adapter)
           client.headers['Authorization'] = "Bearer #{@access_token}" unless @access_token.nil?
+          client.response(:logger, @logger, @logger_options) unless @logger.nil?
         end
       end
+
+      sig { params(api_version: String).void }
+      def validate_api_version(api_version)
+        raise ArgumentError, "Invalid API version: #{api_version}" unless API_VERSIONS.include?(api_version)
+      end
     end
   end
 end

data/lib/whatsapp_sdk/api/medias.rb

@@ -64,12 +64,15 @@ module WhatsappSdk
       #
       # @param url URL.
       # @param file_path [String] The file_path to download the media e.g. "tmp/downloaded_image.png".
-      # @param media_type [String] The media type e.g. "audio/mp4". See the supported types in the official
-      #  documentation https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types.
+      # @param media_type [String] The media type e.g. "audio/mp4". See possible types in the official
+      #  documentation https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types,
+      #  but note that the API may allow more depending on the client.
       # @return [Api::Response] Response object.
       sig { params(url: String, file_path: String, media_type: String).returns(Api::Response) }
       def download(url:, file_path:, media_type:)
-        raise InvalidMediaTypeError.new(media_type: media_type) unless valid_media_type?(media_type)
+        # Allow download of unsupported media types, since Cloud API may decide to let it through.
+        #   https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/discussions/127
+        # raise InvalidMediaTypeError.new(media_type: media_type) unless valid_media_type?(media_type)
 
         content_type_header = map_media_type_to_content_type_header(media_type)
 
@@ -104,7 +107,7 @@ module WhatsappSdk
           type: type
         }
 
-        response = send_request(http_method: "post", endpoint: "#{sender_id}/media", params: params)
+        response = send_request(http_method: "post", endpoint: "#{sender_id}/media", params: params, multipart: true)
 
         Api::Response.new(
           response: response,

data/lib/whatsapp_sdk/api/messages.rb

@@ -167,7 +167,8 @@ module WhatsappSdk
         response = send_request(
           endpoint: endpoint(sender_id),
           params: params,
-          headers: DEFAULT_HEADERS
+          headers: DEFAULT_HEADERS,
+          multipart: true
         )
 
         Api::Response.new(

data/lib/whatsapp_sdk/api/request.rb

@@ -14,9 +14,14 @@ module WhatsappSdk
         @client.download_file(url: url, content_type_header: content_type_header, file_path: file_path)
       end
 
-      def send_request(endpoint: nil, full_url: nil, http_method: "post", params: {}, headers: {})
+      def send_request(endpoint: nil, full_url: nil, http_method: "post", params: {}, headers: {}, multipart: false)
         @client.send_request(
-          http_method: http_method, full_url: full_url, endpoint: endpoint, params: params, headers: headers
+          http_method: http_method,
+          full_url: full_url,
+          endpoint: endpoint,
+          params: params,
+          headers: headers,
+          multipart: multipart
         )
       end
     end

data/lib/whatsapp_sdk/configuration.rb

@@ -5,23 +5,51 @@ module WhatsappSdk
   # This module allows client instantiating the client as a singleton like the following example:
   # WhatsappSdk.configure do |config|
   #   config.access_token = ACCESS_TOKEN
+  #   config.api_version = API_VERSION
   # end
   #
   # The gem have access to the client through WhatsappSdk.configuration.client
   class Configuration
     extend T::Sig
 
+    logger_or_subclass_or_nil = T.nilable(T.any(Logger, T.class_of(Logger)))
+
     sig { returns(String) }
     attr_accessor :access_token
 
-    sig { params(access_token: String).void }
-    def initialize(access_token = "")
+    sig { returns(String) }
+    attr_accessor :api_version
+
+    # loggers like ActiveSupport::Logger (Rails.logger) is a subclass of Logger
+    sig { returns(logger_or_subclass_or_nil) }
+    attr_accessor :logger
+
+    sig { returns(Hash) }
+    attr_accessor :logger_options
+
+    sig do
+      params(
+        access_token: String,
+        api_version: String,
+        logger: logger_or_subclass_or_nil,
+        logger_options: Hash
+      ).void
+    end
+    def initialize(
+      access_token = "",
+      api_version = Api::ApiConfiguration::DEFAULT_API_VERSION,
+      logger = nil,
+      logger_options = {}
+    )
       @access_token = access_token
+      @api_version = api_version
+      @logger = logger
+      @logger_options = logger_options
     end
 
     sig { returns(Api::Client) }
     def client
-      Api::Client.new(access_token)
+      Api::Client.new(access_token, api_version, logger, logger_options)
     end
   end
 end

data/lib/whatsapp_sdk/resource/business_profile.rb

@@ -0,0 +1,15 @@
+# typed: strict
+# frozen_string_literal: true
+
+module WhatsappSdk
+  module Resource
+    class BusinessProfile
+      extend T::Sig
+
+      VERTICAL_VALUES = %w[
+        UNDEFINED OTHER AUTO BEAUTY APPAREL EDU ENTERTAIN EVENT_PLAN FINANCE GROCERY
+        GOVT HOTEL HEALTH NONPROFIT PROF_SERVICES RETAIL TRAVEL RESTAURANT NOT_A_BIZ
+      ].freeze
+    end
+  end
+end

data/lib/whatsapp_sdk/resource/media_types.rb

@@ -13,6 +13,8 @@ module WhatsappSdk
       # The content-type header matches with the media type using Internet Assigned Numbers Authority (IANA).
       # Media type list defined by IANA https://www.iana.org/assignments/media-types/media-types.xhtml
       #
+      # NOTE: Cloud API may decide to allow more media types to be downloaded, since the support differs depending on
+      # the used client.
 
       AUDIO_TYPES = %w[audio/aac audio/mp4 audio/mpeg audio/amr audio/ogg].freeze
       DOCUMENT_TYPES = %w[

data/lib/whatsapp_sdk/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module WhatsappSdk
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: whatsapp_sdk
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - ignacio-chiazzo
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-01-31 00:00:00.000000000 Z
+date: 2024-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -142,6 +142,7 @@ files:
 - ".travis.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.MD
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -150,6 +151,7 @@ files:
 - bin/console
 - bin/setup
 - bin/tapioca
+- config/api_versions.yml
 - example.rb
 - lib/whatsapp_sdk.rb
 - lib/whatsapp_sdk/api/api_configuration.rb
@@ -179,6 +181,7 @@ files:
 - lib/whatsapp_sdk/error.rb
 - lib/whatsapp_sdk/resource/address.rb
 - lib/whatsapp_sdk/resource/address_type.rb
+- lib/whatsapp_sdk/resource/business_profile.rb
 - lib/whatsapp_sdk/resource/button_parameter.rb
 - lib/whatsapp_sdk/resource/component.rb
 - lib/whatsapp_sdk/resource/contact.rb
@@ -249,7 +252,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Use the Ruby Whatsapp SDK to communicate with Whatsapp API using the Cloud