whatsapp_sdk 1.0.5 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17de6b59f97c39b0d49c911d4e153d241f60d7f92727a10ec895ff4dc4d9822b
-  data.tar.gz: f2f25357ffa9d35972e157f57abfaa4a3ac2b2a9debb0f86fdb15230581c6ce6
+  metadata.gz: 6e1bc509c72a21009421ece7489cc79d178abec74db4445d84cf579fe374d5d3
+  data.tar.gz: b547704f8654b49e389547d27014089fdf1583583e57c6f567bf1193dbfc72aa
 SHA512:
-  metadata.gz: 1ef8af8f454441f188633dab7295b20da476d8692af1bf6602032b7504c08d1931bc9fbb9544452f981b3b58111ed0bec034de6138540c3445d6379a50f813ac
-  data.tar.gz: ead1a38b14a8d5d16539e61ba4b65c36c6652525ca10d7aab554dd3b83a8cd1b11fff52dc38e0c121f574db108ce3ea64546bf62a386b46078dfc369dd559710
+  metadata.gz: f302ce6f5126585be265c8a0bdcc7c7681cd27e6838ce6c961a0b196eb66ba0cc3522c87407cbc69af7d95f8adeca02f7dbcf76ee646fddff49e3e50ba6c62b3
+  data.tar.gz: d7a97fa6bc6de65711c1d1698cd38863650dfc7f2dd0ef5ec743d2c938e15bca6511f6481c5fd72ee2972ec258466c9066817a9a3ea378f98c0d2db26a05e186

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Unreleased
 
+# v 1.2.0
+- Expose Graph media upload sessions through the configured client @oitedi [199](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/199)
+- Support BSUID recipients and preserve user IDs in message responses @oitedi [198](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/198)
+- Add voice message support to audio sends @oitedi [197](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/197)
+- Guard `GenericErrorResponse.build_from_response` against non-Hash input @afonso-aguas [195](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/195)
+- Fix false-positive `HttpResponseError` on bodies containing "error" substring @afonso-aguas [194](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/194)
+
+# v 1.1.0
+- Add support for pagination in template_analytics with 'after' cursor @osvaldo-santos [190](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/190) 
+- Add template_analytics feature @osvaldo-santos [189](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/189) 
+- Add Business Account API support @osvaldo-santos [187](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/187) 
+
 # v 1.0.5
 - Added GET template endpoint. @osvaldo-santos [185](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/185)
 - Adding support for named paremeters in Templates API. @osvaldo-santos [184](https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/pull/184)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    whatsapp_sdk (1.0.5)
+    whatsapp_sdk (1.2.0)
       faraday (~> 2.0, > 2.0.1)
       faraday-multipart (~> 1)
       zeitwerk (~> 2)
@@ -9,14 +9,14 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.1)
-      public_suffix (>= 2.0.2, < 6.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.2)
     base64 (0.2.0)
     coderay (1.1.3)
     crack (0.4.5)
       rexml
-    faraday (2.14.0)
+    faraday (2.14.1)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
@@ -25,10 +25,10 @@ GEM
     faraday-net_http (3.4.2)
       net-http (~> 0.5)
     hashdiff (1.0.1)
-    json (2.18.0)
+    json (2.19.9)
     logger (1.7.0)
     method_source (1.0.0)
-    minitest (5.16.1)
+    minitest (5.27.0)
     mocha (1.14.0)
     multipart-post (2.4.1)
     net-http (0.9.1)
@@ -41,7 +41,7 @@ GEM
       method_source (~> 1.0)
     pry-nav (1.0.0)
       pry (>= 0.9.10, < 0.15)
-    public_suffix (5.0.0)
+    public_suffix (5.1.1)
     rainbow (3.1.1)
     rake (12.3.3)
     regexp_parser (2.5.0)
@@ -71,13 +71,14 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    zeitwerk (2.7.4)
+    zeitwerk (2.7.5)
 
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-24
+  arm64-darwin-25
   x86_64-darwin-19
   x86_64-darwin-21
   x86_64-linux

data/README.md

@@ -17,6 +17,7 @@ Send stickers, messages, audio, videos, locations, react and reply to messages o
 - [APIs](#apis)
   - [Templates](#templates)
   - [Business Profile API](#business-profile-api)
+  - [Business Account API](#business-account-api)
   - [Phone numbers API](#phone-numbers-api)
   - [Media API](#media-api)
   - [Messages API](#messages-api)
@@ -207,6 +208,12 @@ client.templates.create(
 
 # Delete a template
 client.templates.delete(business_id: BUSINESS_ID, name: "my_name") # delete by name
+
+# Get templates analytics
+client.templates.template_analytics(
+  business_id: BUSINESS_ID, start_timestamp: 1767236400,
+  end_timestamp: 1767322799, template_ids: [id]
+)
 ```
 </details>
 
@@ -223,6 +230,22 @@ client.business_profiles.update(phone_number_id: SENDER_ID, params: { about: "A
 ```
 </details>
 
+### Business Account API
+<details>
+
+```ruby
+# Get the details of your business account
+client.business_accounts.get(BUSINESS_ID)
+
+# Get some fields of your business account
+client.business_accounts.get(BUSINESS_ID, fields: ["id", "name"])
+
+# Update your business account
+# Note: You can only update the `name` and `timezone_id` fields of your business account.
+client.business_accounts.update(business_id: BUSINESS_ID, params: { name: "My new business name", timezone_id: "1" })
+```
+</details>
+
 ### Phone numbers API
 
 <details>
@@ -512,6 +535,54 @@ If the API response is still `success`, but the message is not delivered:
 
 Note: Sometimes the messages are delayed; see [Meta documentation](https://developers.facebook.com/docs/whatsapp/on-premises/guides/send-message-performance#delays).
 
+
+### Voice messages
+
+Pass `voice: true` to `send_audio` with an uploaded `audio_id` or hosted `link`.
+Voice messages require an Ogg file encoded with Opus; the SDK does not transcode media.
+Omitting `voice` (or passing `false`) sends basic audio.
+
+```ruby
+client.messages.send_audio(sender_id: sender_id, recipient_number: recipient_number,
+                           audio_id: media_id, voice: true)
+```
+
+See [Meta's audio message documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/audio-messages/).
+
+### Upload handles for templates and profile photos
+
+Use Graph upload sessions when an endpoint requires a media handle instead of a WhatsApp media ID:
+
+```ruby
+session = client.media.create_upload_session(app_id: app_id, file_path: "header.png", type: "image/png")
+upload = client.media.upload_file_to_session(session_id: session.fetch("id"), file_path: "header.png")
+handle = upload.fetch("h")
+```
+
+Both methods use the client's configured API version and token. An optional `access_token:`
+overrides the token for that request only. They return the Graph response hashes and raise
+`WhatsappSdk::Api::Responses::HttpResponseError` on Graph errors, like the other APIs.
+Missing files or directories raise `WhatsappSdk::Api::Medias::FileNotFoundError`.
+The upload reads the entire file into memory and starts at offset zero; automatic retries and
+resuming interrupted uploads are not included.
+See [Meta's upload guide](https://developers.facebook.com/docs/graph-api/guides/upload).
+
+### Business-scoped user IDs (BSUIDs)
+
+All message sends accept `recipient:` as an alternative to `recipient_number:`.
+Use the complete BSUID (or parent BSUID), including its country prefix:
+
+```ruby
+response = client.messages.send_text(sender_id: sender_id, recipient: "US.123abc", message: "Hello")
+response.contacts.first.user_id # => "US.123abc"
+response.contacts.first.wa_id   # => nil when Meta omits the phone number
+```
+
+Phone numbers take precedence when both destinations are supplied. Missing or blank
+selected destinations raise `WhatsappSdk::Resource::Errors::MissingArgumentError` before sending.
+Authentication templates require a phone number; the SDK does not infer template category from its name or buttons.
+See [Meta's BSUID documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.

data/example.rb

@@ -142,6 +142,12 @@ end
 
 # client.templates.delete(business_id: BUSINESS_ID, name: "name2", hsm_id: "243213188351928") # delete by name and id
 
+## Get template analytics
+analytics = client.templates.template_analytics(
+  business_id: BUSINESS_ID, start_timestamp: 1767236400,
+  end_timestamp: 1767322799, template_ids: [id, new_template.id]
+)
+puts "GET template analytics: #{analytics.records.first}"
 
 
 # ############################## Business API ##############################
@@ -158,6 +164,22 @@ run_and_catch_error("Update business profile") do
   updated_bp = client.business_profiles.update(phone_number_id: SENDER_ID, params: { about: "A cool business" } )
 end
 
+# ############################## Business Account API ##############################
+puts "\n\n\n ------------------ Testing Business Account API -----------------------"
+
+business_account = client.business_accounts.get(BUSINESS_ID)
+puts "GET Business Account by id: #{business_account.name}"
+
+business_account = client.business_accounts.get(BUSINESS_ID, fields: %w[id name account_review_status message_template_namespace] )
+puts "GET Business Account with fields by id: #{business_account.name}, #{business_account.account_review_status}, #{business_account.message_template_namespace}"
+
+updated_ba = client.business_accounts.update(business_id: BUSINESS_ID, params: { name: 'A cool updated business' } )
+puts "UPDATE Business Account by id: #{updated_ba} }"
+
+run_and_catch_error("Update business account") do
+  # message_template_namespace can't be set
+  client.business_accounts.update(business_id: BUSINESS_ID, params: { message_template_namespace: "namespace" } )
+end
 
 
 ############################## Phone Numbers API ##############################

data/lib/whatsapp_sdk/api/business_account.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "request"
+require_relative "../resource/business_account"
+
+module WhatsappSdk
+  module Api
+    class BusinessAccount < Request
+      DEFAULT_FIELDS = %w[id name timezone_id message_template_namespace account_review_status
+                          business_verification_status country ownership_type primary_business_location]
+                       .join(',')
+                       .freeze
+
+      # Get the details of business account.
+      #
+      # @param business_id [Integer] Business Account Id.
+      # @param fields [Array<String>] Optional list of fields to include in the response. Defaults to 'id,name'.
+      # @return [Resource::BusinessAccount] Response object.
+      def get(business_id, fields: nil)
+        fields = if fields
+                   fields.join(',')
+                 else
+                   DEFAULT_FIELDS
+                 end
+
+        response = send_request(
+          http_method: "get",
+          endpoint: "#{business_id}?fields=#{fields}"
+        )
+
+        Resource::BusinessAccount.from_hash(response)
+      end
+
+      # Update the details of business account.
+      #
+      # @param business_id [Integer] Business Account Id.
+      # @param params [Hash] Params to update. The possible attributes to update are: `name`, `timezone_id`.
+      # @return [Boolean] Whether the update was successful.
+      def update(business_id:, params:)
+        raise ArgumentError, "Params must be a hash." unless params.is_a?(Hash)
+
+        # Only name and timezone_id can be updated. If other keys are present, they will be ignored.
+        filtered_params = params.transform_keys(&:to_sym).slice(:name, :timezone_id)
+
+        if filtered_params.empty?
+          raise ArgumentError, "No valid parameters provided. Only 'name' and 'timezone_id' can be updated."
+        end
+
+        response = send_request(
+          http_method: "post",
+          endpoint: business_id.to_s,
+          params: filtered_params
+        )
+
+        Api::Responses::SuccessResponse.success_response?(response: response)
+      end
+    end
+  end
+end

data/lib/whatsapp_sdk/api/client.rb

@@ -7,7 +7,7 @@ module WhatsappSdk
   module Api
     class Client
       API_VERSIONS = [
-        'v24.0', 'v23.0', 'v22.0', 'v21.0', 'v20.0', 'v19.0', 'v18.0', 'v17.0', 'v16.0', 'v15.0', 'v14.0',
+        'v25.0', 'v24.0', 'v23.0', 'v22.0', 'v21.0', 'v20.0', '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'
@@ -43,6 +43,10 @@ module WhatsappSdk
         @business_profiles ||= WhatsappSdk::Api::BusinessProfile.new(self)
       end
 
+      def business_accounts
+        @business_accounts ||= WhatsappSdk::Api::BusinessAccount.new(self)
+      end
+
       def templates
         @templates ||= WhatsappSdk::Api::Templates.new(self)
       end
@@ -54,13 +58,13 @@ module WhatsappSdk
 
         response = faraday_request.public_send(http_method, endpoint, request_params(params, headers), headers)
 
-        if response.status > 499 || Api::Responses::GenericErrorResponse.response_error?(response: response.body)
-          raise Api::Responses::HttpResponseError.new(http_status: response.status, body: JSON.parse(response.body))
-        end
+        parsed_body = parse_response_body(response.body)
 
-        return nil if response.body == ""
+        if response.status > 499 || Api::Responses::GenericErrorResponse.response_error?(response: parsed_body)
+          raise Api::Responses::HttpResponseError.new(http_status: response.status, body: parsed_body)
+        end
 
-        JSON.parse(response.body)
+        parsed_body
       end
 
       def download_file(url:, content_type_header:, file_path: nil)
@@ -81,6 +85,12 @@ module WhatsappSdk
 
       private
 
+      def parse_response_body(body)
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body)
+      end
+
       def request_params(params, headers)
         return params.to_json if params.is_a?(Hash) && headers['Content-Type'] == 'application/json'
 

data/lib/whatsapp_sdk/api/medias.rb

@@ -117,6 +117,33 @@ module WhatsappSdk
         Api::Responses::SuccessResponse.success_response?(response: response)
       end
 
+      # Create a Graph upload session for template media or a business profile photo.
+      # Returns the raw response containing the upload session "id".
+      # Uses the client's API version and token unless access_token is supplied.
+      def create_upload_session(app_id:, file_path:, type:, access_token: nil)
+        raise FileNotFoundError.new(file_path: file_path) unless File.file?(file_path)
+
+        headers = { 'Content-Type' => 'application/json' }
+        headers['Authorization'] = "Bearer #{access_token}" if access_token
+        send_request(
+          endpoint: "./#{app_id}/uploads",
+          params: { file_name: File.basename(file_path), file_length: File.size(file_path), file_type: type },
+          headers: headers
+        )
+      end
+
+      # Upload the complete file to a Graph upload session, starting at offset zero.
+      # Returns the raw response containing the reusable media handle "h".
+      # This does not resume partial uploads or retry failed requests.
+      def upload_file_to_session(session_id:, file_path:, access_token: nil)
+        raise FileNotFoundError.new(file_path: file_path) unless File.file?(file_path)
+
+        headers = { 'Content-Type' => 'application/octet-stream', 'file_offset' => '0' }
+        headers['Authorization'] = "Bearer #{access_token}" if access_token
+        # ponytail: buffers the whole file; stream bytes if large uploads become a requirement.
+        send_request(endpoint: "./#{session_id}", params: File.binread(file_path), headers: headers)
+      end
+
       private
 
       def map_media_type_to_content_type_header(media_type)

data/lib/whatsapp_sdk/api/messages.rb

@@ -13,8 +13,9 @@ module WhatsappSdk
       # @param recipient_number [Integer] Recipient' Phone number.
       # @param message [String] Text to send.
       # @param message_id [String] The id of the message to reply to.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
       # @return [MessageDataResponse] Response object.
-      def send_text(sender_id:, recipient_number:, message:, message_id: nil)
+      def send_text(sender_id:, message:, recipient_number: nil, message_id: nil, recipient: nil)
         params = {
           messaging_product: "whatsapp",
           to: recipient_number,
@@ -23,6 +24,7 @@ module WhatsappSdk
           text: { body: message }
         }
         params[:context] = { message_id: message_id } if message_id
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -42,9 +44,10 @@ module WhatsappSdk
       # @param name [String] Location name.
       # @param address [String] Location address.
       # @param message_id [String] The id of the message to reply to.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
       # @return [MessageDataResponse] Response object.
       def send_location(
-        sender_id:, recipient_number:, longitude:, latitude:, name:, address:, message_id: nil
+        sender_id:, longitude:, latitude:, name:, address:, recipient_number: nil, message_id: nil, recipient: nil
       )
         params = {
           messaging_product: "whatsapp",
@@ -59,6 +62,7 @@ module WhatsappSdk
           }
         }
         params[:context] = { message_id: message_id } if message_id
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -77,9 +81,10 @@ module WhatsappSdk
       # @param link [String] Image link.
       # @param caption [String] Image caption.
       # @param message_id [String] The id of the message to reply to.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
       # @return [MessageDataResponse] Response object.
       def send_image(
-        sender_id:, recipient_number:, image_id: nil, link: nil, caption: "", message_id: nil
+        sender_id:, recipient_number: nil, image_id: nil, link: nil, caption: "", message_id: nil, recipient: nil
       )
         raise Resource::Errors::MissingArgumentError, "image_id or link is required" if !image_id && !link
 
@@ -95,6 +100,7 @@ module WhatsappSdk
                            { id: image_id, caption: caption }
                          end
         params[:context] = { message_id: message_id } if message_id
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -112,8 +118,12 @@ module WhatsappSdk
       # @param audio_id [String] Audio ID.
       # @param link [String] Audio link.
       # @param message_id [String] The id of the message to reply to.
+      # @param voice [Boolean] Send an Ogg/Opus voice message instead of basic audio. Defaults to false.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
       # @return [MessageDataResponse] Response object.
-      def send_audio(sender_id:, recipient_number:, audio_id: nil, link: nil, message_id: nil)
+      def send_audio(
+        sender_id:, recipient_number: nil, audio_id: nil, link: nil, message_id: nil, voice: false, recipient: nil
+      )
         raise Resource::Errors::MissingArgumentError, "audio_id or link is required" if !audio_id && !link
 
         params = {
@@ -122,8 +132,9 @@ module WhatsappSdk
           recipient_type: "individual",
           type: "audio"
         }
-        params[:audio] = link ? { link: link } : { id: audio_id }
+        params[:audio] = link ? { link: link, voice: voice } : { id: audio_id, voice: voice }
         params[:context] = { message_id: message_id } if message_id
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -143,9 +154,10 @@ module WhatsappSdk
       # @param link [String] Image link.
       # @param caption [String] Image caption.
       # @param message_id [String] The id of the message to reply to.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
       # @return [MessageDataResponse] Response object.
       def send_video(
-        sender_id:, recipient_number:, video_id: nil, link: nil, caption: "", message_id: nil
+        sender_id:, recipient_number: nil, video_id: nil, link: nil, caption: "", message_id: nil, recipient: nil
       )
         raise Resource::Errors::MissingArgumentError, "video_id or link is required" if !video_id && !link
 
@@ -161,6 +173,7 @@ module WhatsappSdk
                            { id: video_id, caption: caption }
                          end
         params[:context] = { message_id: message_id } if message_id
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -179,9 +192,11 @@ module WhatsappSdk
       # @param link [String] Image link.
       # @param caption [String] Image caption.
       # @param message_id [String] The id of the message to reply to.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
       # @return [MessageDataResponse] Response object.
       def send_document(
-        sender_id:, recipient_number:, document_id: nil, link: nil, caption: "", message_id: nil, filename: nil
+        sender_id:, recipient_number: nil, document_id: nil, link: nil, caption: "", message_id: nil,
+        filename: nil, recipient: nil
       )
         if !document_id && !link
           raise Resource::Errors::MissingArgumentError,
@@ -201,6 +216,7 @@ module WhatsappSdk
                             end
         params[:document] = params[:document].merge({ filename: filename }) if filename
         params[:context] = { message_id: message_id } if message_id
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -211,15 +227,16 @@ module WhatsappSdk
         Api::Responses::MessageDataResponse.build_from_response(response: response)
       end
 
-      # Send a document.
+      # Send a sticker.
       #
       # @param sender_id [Integer] Sender' phone number.
       # @param recipient_number [Integer] Recipient' Phone number.
       # @param sticker_id [String] The sticker ID.
       # @param link [String] Image link.
       # @param message_id [String] The id of the message to reply to.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
       # @return [MessageDataResponse] Response object.
-      def send_sticker(sender_id:, recipient_number:, sticker_id: nil, link: nil, message_id: nil)
+      def send_sticker(sender_id:, recipient_number: nil, sticker_id: nil, link: nil, message_id: nil, recipient: nil)
         raise Resource::Errors::MissingArgumentError, "sticker or link is required" if !sticker_id && !link
 
         params = {
@@ -230,6 +247,7 @@ module WhatsappSdk
         }
         params[:sticker] = link ? { link: link } : { id: sticker_id }
         params[:context] = { message_id: message_id } if message_id
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -248,9 +266,10 @@ module WhatsappSdk
       # @param contacts [Array<Contact>] Contacts.
       # @param contacts_json [Json] Contacts.
       # @param message_id [String] The id of the message to reply to.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
       # @return [MessageDataResponse] Response object.
       def send_contacts(
-        sender_id:, recipient_number:, contacts: nil, contacts_json: {}, message_id: nil
+        sender_id:, recipient_number: nil, contacts: nil, contacts_json: {}, message_id: nil, recipient: nil
       )
         params = {
           messaging_product: "whatsapp",
@@ -260,6 +279,7 @@ module WhatsappSdk
         }
         params[:contacts] = contacts ? contacts.map(&:to_h) : contacts_json
         params[:context] = { message_id: message_id } if message_id
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -284,9 +304,10 @@ module WhatsappSdk
       # @param interactive_json [Json] The interactive object as a Json.
       #    If you pass interactive_json, you can't pass interactive.
       # @param message_id [String] The id of the message to reply to.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
       # @return [MessageDataResponse] Response object.
       def send_interactive_message(
-        sender_id:, recipient_number:, interactive: nil, interactive_json: nil, message_id: nil
+        sender_id:, recipient_number: nil, interactive: nil, interactive_json: nil, message_id: nil, recipient: nil
       )
         if !interactive && !interactive_json
           raise Resource::Errors::MissingArgumentError,
@@ -306,6 +327,7 @@ module WhatsappSdk
                                  interactive.to_json
                                end
         params[:context] = { message_id: message_id } if message_id
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -348,9 +370,11 @@ module WhatsappSdk
       # @param language [String] template language.
       # @param components [Component] Component.
       # @param components_json [Json] The component as a Json. If you pass components_json, you can't pass components.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
+      #    Not allowed for authentication templates.
       # @return [MessageDataResponse] Response object.
       def send_template(
-        sender_id:, recipient_number:, name:, language:, components: nil, components_json: nil
+        sender_id:, name:, language:, recipient_number: nil, components: nil, components_json: nil, recipient: nil
       )
         if !components && !components_json
           raise Resource::Errors::MissingArgumentError,
@@ -373,6 +397,7 @@ module WhatsappSdk
                                          else
                                            components.map(&:to_json)
                                          end
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -389,8 +414,9 @@ module WhatsappSdk
       # @param recipient_number [Integer] Recipient' Phone number.
       # @param message_id [String] the id of the message to reaction.
       # @param emoji [String] unicode of the emoji to send.
+      # @param recipient [String] Recipient' Business-Scoped User ID (BSUID). Optional alternative to recipient_number.
       # @return [MessageDataResponse] Response object.
-      def send_reaction(sender_id:, recipient_number:, message_id:, emoji:)
+      def send_reaction(sender_id:, message_id:, emoji:, recipient_number: nil, recipient: nil)
         params = {
           messaging_product: "whatsapp",
           recipient_type: "individual",
@@ -401,6 +427,7 @@ module WhatsappSdk
             emoji: emoji
           }
         }
+        apply_recipient!(params, recipient_number, recipient)
 
         response = send_request(
           endpoint: endpoint(sender_id),
@@ -441,6 +468,22 @@ module WhatsappSdk
       def endpoint(sender_id)
         "#{sender_id}/messages"
       end
+
+      # Applies the destination to the payload.
+      # - Phone send (recipient_number present): keeps `to`, never adds `recipient` — payload is
+      #   identical to the pre-BSUID behavior.
+      # - BSUID send (recipient_number absent, recipient present): drops `to` and sets `recipient`
+      #   (the field Meta uses to address a Business-Scoped User ID).
+      # Requires at least one destination.
+      def apply_recipient!(params, recipient_number, recipient)
+        if (recipient_number.nil? ? recipient : recipient_number).to_s.strip.empty?
+          raise Resource::Errors::MissingArgumentError, "recipient_number or recipient is required"
+        end
+
+        params.delete(:to) if recipient_number.nil?
+        params[:recipient] = recipient if recipient_number.nil? && recipient
+        params
+      end
     end
   end
 end

data/lib/whatsapp_sdk/api/responses/generic_error_response.rb

@@ -16,10 +16,14 @@ module WhatsappSdk
         end
 
         def self.response_error?(response:)
+          return false unless response.is_a?(Hash)
+
           response["error"]
         end
 
         def self.build_from_response(response:)
+          return unless response.is_a?(Hash)
+
           error_response = response["error"]
           return unless error_response
 

data/lib/whatsapp_sdk/api/responses/message_data_response.rb

@@ -27,7 +27,9 @@ module WhatsappSdk
           end
 
           def parse_contact(contact_json)
-            Resource::ContactResponse.new(input: contact_json["input"], wa_id: contact_json["wa_id"])
+            Resource::ContactResponse.new(
+              input: contact_json["input"], wa_id: contact_json["wa_id"], user_id: contact_json["user_id"]
+            )
           end
         end
       end

data/lib/whatsapp_sdk/api/templates.rb

@@ -175,6 +175,50 @@ module WhatsappSdk
         Api::Responses::SuccessResponse.success_response?(response: response)
       end
 
+      # Get Template Analytics
+      #
+      # Get analytics data for message templates over a specified time range.
+      # @param business_id [Integer] The business ID.
+      # @param start_timestamp [Integer] The start of the time range to retrieve analytics data, in Unix timestamp.
+      # @param end_timestamp [Integer] The end of the time range to retrieve analytics data, in Unix timestamp.
+      # @param template_ids [Array<String>] An array of template IDs for which to retrieve analytics data.
+      # @param metric_types [Array<String>] An array of metric types to retrieve.
+      def template_analytics(
+        business_id:, start_timestamp:, end_timestamp:, template_ids:, metric_types: [],
+        granularity: WhatsappSdk::Resource::TemplateAnalytic::Granularity::DAILY,
+        after: nil
+      )
+        if !metric_types.empty? && !valid_metric_types?(metric_types)
+          valid_types = WhatsappSdk::Resource::TemplateAnalytic::MetricType::METRIC_TYPES.join(', ')
+
+          raise ArgumentError, "Invalid metric type. Valid types are: #{valid_types}."
+        end
+
+        if granularity != WhatsappSdk::Resource::TemplateAnalytic::Granularity::DAILY
+          raise ArgumentError, "Invalid granularity. The only supported granularity is DAILY."
+        end
+
+        query_params = {
+          start: start_timestamp,
+          end: end_timestamp,
+          template_ids: template_ids.join(","),
+          metric_types: metric_types.join(","),
+          granularity: granularity
+        }
+        query_params[:after] = after if after
+
+        response = send_request(
+          endpoint: "#{business_id}/template_analytics?#{URI.encode_www_form(query_params)}",
+          http_method: "get"
+        )
+
+        Api::Responses::PaginationRecords.new(
+          records: parse_template_analytics(response['data']),
+          before: response.dig('paging', 'cursors', 'before'),
+          after: response.dig('paging', 'cursors', 'after')
+        )
+      end
+
       private
 
       def parse_templates(templates_data)
@@ -182,6 +226,18 @@ module WhatsappSdk
           Resource::Template.from_hash(template)
         end
       end
+
+      def parse_template_analytics(analytics_data)
+        analytics_data.map do |analytic|
+          Resource::TemplateAnalytic.from_hash(analytic)
+        end
+      end
+
+      def valid_metric_types?(metric_types)
+        metric_types.all? do |type|
+          WhatsappSdk::Resource::TemplateAnalytic::MetricType.valid?(type)
+        end
+      end
     end
   end
 end

data/lib/whatsapp_sdk/resource/business_account.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module WhatsappSdk
+  module Resource
+    class BusinessAccount
+      attr_accessor :id, :name, :timezone_id, :message_template_namespace, :account_review_status,
+                    :business_verification_status, :country, :ownership_type, :primary_business_location,
+                    :analytics, :conversation_analytics, :pricing_analytics, :call_analytics
+
+      def self.from_hash(hash)
+        business_account = BusinessAccount.new
+        business_account.id = hash["id"]
+        business_account.name = hash["name"]
+        business_account.timezone_id = hash["timezone_id"]
+        business_account.message_template_namespace = hash["message_template_namespace"]
+        business_account.account_review_status = hash["account_review_status"]
+        business_account.business_verification_status = hash["business_verification_status"]
+        business_account.country = hash["country"]
+        business_account.ownership_type = hash["ownership_type"]
+        business_account.primary_business_location = hash["primary_business_location"]
+        business_account.analytics = hash["analytics"]
+        business_account.conversation_analytics = hash["conversation_analytics"]
+        business_account.pricing_analytics = hash["pricing_analytics"]
+        business_account.call_analytics = hash["call_analytics"]
+
+        business_account
+      end
+
+      def ==(other)
+        return false unless other.is_a?(WhatsappSdk::Resource::BusinessAccount)
+
+        %i[id name timezone_id message_template_namespace account_review_status
+           business_verification_status country ownership_type primary_business_location].all? do |field|
+          send(field) == other.send(field)
+        end
+      end
+    end
+  end
+end

data/lib/whatsapp_sdk/resource/contact_response.rb

@@ -3,11 +3,12 @@
 module WhatsappSdk
   module Resource
     class ContactResponse
-      attr_accessor :wa_id, :input
+      attr_accessor :wa_id, :input, :user_id
 
-      def initialize(input:, wa_id:)
+      def initialize(input:, wa_id: nil, user_id: nil)
         @input = input
         @wa_id = wa_id
+        @user_id = user_id
       end
     end
   end

data/lib/whatsapp_sdk/resource/template_analytic.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module WhatsappSdk
+  module Resource
+    class TemplateAnalytic
+      module Granularity
+        DAILY = "DAILY"
+      end
+
+      module MetricType
+        COST = "COST"
+        CLICKED = "CLICKED"
+        DELIVERED = "DELIVERED"
+        READ = "READ"
+        SENT = "SENT"
+
+        # (MM API for WhatsApp only)
+        APP_ACTIVATIONS = "APP_ACTIVATIONS"
+        APP_ADD_TO_CART = "APP_ADD_TO_CART"
+        APP_CHECKOUTS_INITIATED = "APP_CHECKOUTS_INITIATED"
+        APP_PURCHASES = "APP_PURCHASES"
+        APP_PURCHASES_CONVERSION_VALUE = "APP_PURCHASES_CONVERSION_VALUE"
+        WEBSITE_ADD_TO_CART = "WEBSITE_ADD_TO_CART"
+        WEBSITE_CHECKOUTS_INITIATED = "WEBSITE_CHECKOUTS_INITIATED"
+        WEBSITE_PURCHASES = "WEBSITE_PURCHASES"
+        WEBSITE_PURCHASES_CONVERSION_VALUE = "WEBSITE_PURCHASES_CONVERSION_VALUE"
+
+        METRIC_TYPES = [COST, CLICKED, DELIVERED, READ, SENT, APP_ACTIVATIONS, APP_ADD_TO_CART, APP_CHECKOUTS_INITIATED,
+                        APP_PURCHASES, APP_PURCHASES_CONVERSION_VALUE, WEBSITE_ADD_TO_CART, WEBSITE_CHECKOUTS_INITIATED,
+                        WEBSITE_PURCHASES, WEBSITE_PURCHASES_CONVERSION_VALUE].freeze
+
+        def self.valid?(metric_type)
+          METRIC_TYPES.include?(metric_type)
+        end
+      end
+
+      attr_accessor :granularity, :product_type, :data_points
+
+      def initialize(granularity:, product_type:, data_points:)
+        @granularity = granularity
+        @product_type = product_type
+        @data_points = data_points
+      end
+
+      def self.from_hash(hash)
+        new(
+          granularity: hash["granularity"],
+          product_type: hash["product_type"],
+          data_points: hash["data_points"]
+        )
+      end
+    end
+  end
+end

data/lib/whatsapp_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WhatsappSdk
-  VERSION = "1.0.5"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: whatsapp_sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.2.0
 platform: ruby
 authors:
 - ignacio-chiazzo
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -134,6 +133,7 @@ files:
 - example.rb
 - lib/whatsapp_sdk.rb
 - lib/whatsapp_sdk/api/api_configuration.rb
+- lib/whatsapp_sdk/api/business_account.rb
 - lib/whatsapp_sdk/api/business_profile.rb
 - lib/whatsapp_sdk/api/client.rb
 - lib/whatsapp_sdk/api/medias.rb
@@ -151,6 +151,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_account.rb
 - lib/whatsapp_sdk/resource/business_profile.rb
 - lib/whatsapp_sdk/resource/button_parameter.rb
 - lib/whatsapp_sdk/resource/component.rb
@@ -181,6 +182,7 @@ files:
 - lib/whatsapp_sdk/resource/phone_number.rb
 - lib/whatsapp_sdk/resource/phone_number_component.rb
 - lib/whatsapp_sdk/resource/template.rb
+- lib/whatsapp_sdk/resource/template_analytic.rb
 - lib/whatsapp_sdk/resource/url.rb
 - lib/whatsapp_sdk/version.rb
 - tmp/whatsapp.png
@@ -193,7 +195,6 @@ metadata:
   source_code_uri: https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk
   changelog_uri: https://github.com/ignacio-chiazzo/ruby_whatsapp_sdk/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -208,8 +209,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Use the Ruby Whatsapp SDK to communicate with Whatsapp API using the Cloud
   API