ruby-whatsapp 0.3.0

data/lib/ruby/whatsapp/message_templates/template.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # The payload for creating a template, and for the multi-language upsert form.
+    #
+    # Owns the template's *identity* — name, language, category and the flags that
+    # apply to the whole template. Everything about the components, including the rules
+    # that span several of them, is delegated to {ComponentSet}; this class only passes
+    # the category and parameter format down so those rules can be applied.
+    #
+    # Supports two language forms, which is why they are validated as an exclusive
+    # choice: a single `language` for {MessageTemplates#create}, or a `languages` array
+    # for {MessageTemplates#upsert}, which creates or updates the same template across
+    # several locales in one call.
+    #
+    # Cloning a pre-written template from Meta's library is a different payload with no
+    # components at all — see {LibraryTemplate}.
+    # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-account/message_templates/
+    class Template
+      include ValueObject
+
+      module Defaults
+        # Meta accepts lowercase alphanumerics and underscores, nothing else.
+        NAME_PATTERN = /\A[a-z0-9_]+\z/
+        MAX_NAME_LENGTH = 512
+      end
+
+      # Refinements Meta recognises for order-related utility templates.
+      module SubCategories
+        ORDER_DETAILS = "ORDER_DETAILS"
+        ORDER_STATUS = "ORDER_STATUS"
+        RICH_ORDER_STATUS = "RICH_ORDER_STATUS"
+
+        ALL = [ORDER_DETAILS, ORDER_STATUS, RICH_ORDER_STATUS].freeze
+      end
+
+      # @!attribute [rw] name
+      #   @return [String]
+      attr_accessor :name
+
+      # @!attribute [rw] language
+      #   @return [String, nil] A single locale code, for create.
+      attr_accessor :language
+
+      # @!attribute [rw] languages
+      #   @return [Array<String>, nil] Several locale codes, for upsert.
+      attr_accessor :languages
+
+      # @!attribute [rw] category
+      #   @return [String]
+      attr_accessor :category
+
+      # @!attribute [rw] parameter_format
+      #   @return [String]
+      attr_accessor :parameter_format
+
+      # @!attribute [rw] component_set
+      #   @return [ComponentSet]
+      attr_accessor :component_set
+
+      # @!attribute [rw] sub_category
+      #   @return [String, nil]
+      attr_accessor :sub_category
+
+      # @!attribute [rw] message_send_ttl_seconds
+      #   @return [Integer, nil]
+      attr_accessor :message_send_ttl_seconds
+
+      # @!attribute [rw] allow_category_change
+      #   Effectively a no-op since 2025-04-09, when Meta made automatic
+      #   recategorisation the default regardless of this flag. Kept because it is
+      #   still a documented parameter.
+      #   @return [Boolean, nil]
+      attr_accessor :allow_category_change
+
+      # @!attribute [rw] cta_url_link_tracking_opted_out
+      #   @return [Boolean, nil]
+      attr_accessor :cta_url_link_tracking_opted_out
+
+      validates :name, presence: true,
+        format: { with: Defaults::NAME_PATTERN,
+                  message: "must contain only lowercase alphanumeric characters and underscores", },
+        length: { maximum: Defaults::MAX_NAME_LENGTH }
+      validates :category, presence: true, inclusion: { in: Categories::ALL }
+      validates :parameter_format, inclusion: { in: ParameterFormats::ALL }
+      validates :sub_category, inclusion: { in: SubCategories::ALL }, allow_nil: true
+      validate :validate_language_choice
+      validate :validate_language_codes
+      validate :validate_message_send_ttl
+
+      # @param name [String] The template name; lowercase alphanumerics and underscores.
+      # @param category [String, Symbol] One of {Categories::ALL}.
+      # @param components [Array<Hash, Component::Base>] The template's components.
+      # @param language [String, nil] A single locale code. Mutually exclusive with
+      #   `languages`.
+      # @param languages [Array<String>, nil] Locale codes, for the upsert form.
+      # @param parameter_format [String, Symbol] `POSITIONAL` (default) or `NAMED`.
+      # @param sub_category [String, nil] One of {SubCategories::ALL}.
+      # @param message_send_ttl_seconds [Integer, nil] Delivery-retry TTL override.
+      # @param allow_category_change [Boolean, nil] See the attribute note.
+      # @param cta_url_link_tracking_opted_out [Boolean, nil] Opt out of link tracking.
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      #  @raise [TemplateError] if a component or button type is unknown.
+      def initialize(name:, category:, components:, language: nil, languages: nil,
+        parameter_format: ParameterFormats::POSITIONAL, sub_category: nil,
+        message_send_ttl_seconds: nil, allow_category_change: nil,
+        cta_url_link_tracking_opted_out: nil)
+        @name = name
+        @language = language
+        @languages = languages
+        @category = Categories.normalize(category)
+        @parameter_format = ParameterFormats.normalize(parameter_format)
+        @sub_category = sub_category
+        @message_send_ttl_seconds = message_send_ttl_seconds
+        @allow_category_change = allow_category_change
+        @cta_url_link_tracking_opted_out = cta_url_link_tracking_opted_out
+        @component_set = ComponentSet.new(components:, category: @category, parameter_format: @parameter_format)
+
+        validate!
+      end
+
+      # @return [Array<Component::Base>]
+      def components
+        component_set.components
+      end
+
+      # @return [Hash] The create/upsert payload.
+      def serialize
+        {
+          name:,
+          **language_payload,
+          category:,
+          parameter_format:,
+          components: component_set.serialize,
+          sub_category:,
+          message_send_ttl_seconds:,
+          allow_category_change:,
+          cta_url_link_tracking_opted_out:,
+        }.compact
+      end
+
+    private
+
+      # @return [Hash] Either `language` or `languages`, never both.
+      def language_payload
+        return { languages: } unless blank_value?(languages)
+
+        { language: }
+      end
+
+      # @return [void]
+      def validate_language_choice
+        single = !blank_value?(language)
+        multiple = !blank_value?(languages)
+
+        return errors.add(:base, "language and languages cannot be combined") if single && multiple
+        return if single || multiple
+
+        errors.add(:base, "requires either language or languages")
+      end
+
+      # @return [void]
+      def validate_language_codes
+        codes = blank_value?(languages) ? [language] : Array(languages)
+
+        codes.compact.reject { |code| Utils::LanguageCodes.valid?(code) }.each do |code|
+          errors.add(:language, "#{code.inspect} is not a valid WhatsApp language code")
+        end
+      end
+
+      # @return [void]
+      def validate_message_send_ttl
+        return if message_send_ttl_seconds.nil? || message_send_ttl_seconds.is_a?(Integer)
+
+        errors.add(:message_send_ttl_seconds, "must be an integer number of seconds")
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/value_object.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # Shared behaviour for the nested value objects that make up a template payload:
+    # components, buttons, carousel cards, and library inputs.
+    #
+    # Pulls together the three things every one of them needs — ActiveModel
+    # validations, the class-level `.serialize` shorthand used throughout this gem,
+    # and a couple of validation helpers — so they are declared once rather than
+    # re-stated in each `Base`.
+    module ValueObject
+      # @param base [Class]
+      # @return [void]
+      def self.included(base)
+        base.include(ActiveModel::Validations)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Builds an instance and serializes it in one step.
+        # @return [Hash]
+        def serialize(**)
+          new(**).serialize
+        end
+      end
+
+      # @return [Hash] The API payload for this object.
+      def serialize
+        raise NotImplementedError, "Subclasses must implement the serialize method"
+      end
+
+    protected
+
+      # Plain-Ruby blank check, spelled out because the rest of this gem avoids
+      # ActiveSupport's core extensions.
+      #
+      # Deliberately *not* named `blank?`: ActiveModel's presence validator calls
+      # `value.blank?` on attribute values, so defining a one-argument `blank?` here
+      # would shadow `Object#blank?` on every component and make
+      # `validates :header, presence: true` raise instead of validate.
+      # @param value [Object]
+      # @return [Boolean]
+      def blank_value?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+
+      # Records an error for a field Meta does not accept at template creation time.
+      #
+      # Used where Meta supplies the value itself (OTP and copy-code button labels) or
+      # where the field is meaningless for the chosen shape (text on a location
+      # header): silently dropping a caller's value would be worse than saying why it
+      # is not allowed.
+      # @param field [Symbol]
+      # @param reason [String]
+      # @return [void]
+      def reject_unsupported(field, reason)
+        errors.add(field, reason) unless blank_value?(public_send(field))
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Manages the message templates on a WhatsApp Business Account: create, list, read,
+  # edit, and delete.
+  #
+  # This is the opposite side of {Whatsapp::Messages::Template}, which *sends* an
+  # already-approved template. The two are separate APIs with incompatible payload
+  # schemas — different endpoint, different ID (`waba_id`, not `phone_id`), different
+  # permission (`whatsapp_business_management`), and components that carry `text` plus
+  # an `example` here versus `parameters` when sending. See
+  # `lib/ruby/whatsapp/message_templates/CLAUDE.md`.
+  #
+  # This class is only the transport: it builds paths, issues requests, and hands the
+  # bodies to {Response}. Every rule about what a valid template looks like lives in
+  # {Template} / {ComponentSet} / {Component} / {Button}, so nothing here needs to know
+  # what a carousel is.
+  #
+  # @example
+  #   templates = Whatsapp::MessageTemplates.new
+  #   created = templates.create(
+  #     name: "order_confirmation", language: "en_US", category: "UTILITY",
+  #     components: [{ type: :body, text: "Thanks, {{1}}!", example: ["Pablo"] }]
+  #   )
+  #   templates.find(template_id: created.id).status # => "PENDING"
+  # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-account/message_templates/
+  class MessageTemplates
+    include ResponseHandling
+
+    class TemplateError < Whatsapp::Error; end
+
+    # The API edges these operations address.
+    module Edges
+      MESSAGE_TEMPLATES = "message_templates"
+      UPSERT_MESSAGE_TEMPLATES = "upsert_message_templates"
+    end
+
+    module Defaults
+      # Meta's cap on a single bulk delete.
+      MAX_DELETE_IDS = 100
+      # Filters whose value is a list of names rather than a JSON array.
+      COMMA_JOINED_FILTERS = [:fields].freeze
+    end
+
+    # @!attribute [rw] client
+    #   @return [Whatsapp::Client]
+    attr_accessor :client
+
+    # @param client [Whatsapp::Client] The WhatsApp client instance.
+    def initialize(client: Client.new)
+      @client = client
+    end
+
+    # Creates a template.
+    #
+    # Validation happens before the request, so an invalid template costs nothing. The
+    # response `status` is usually PENDING — Meta reviews templates asynchronously and
+    # reports the outcome via the `message_template_status_update` webhook.
+    # @param attrs [Hash] Forwarded to {Template} (`name:`, `language:`, `category:`,
+    #   `components:`, and the optional fields).
+    # @return [Response::Created]
+    # @raise [ActiveModel::ValidationError] if the template is invalid.
+    # @raise [TemplateError] if the request fails.
+    def create(**attrs)
+      created_from(edge_path(Edges::MESSAGE_TEMPLATES), Template.new(**attrs), action: "create template")
+    end
+
+    # Creates a template by cloning one of Meta's pre-written library templates.
+    #
+    # Uses the same edge as {#create} but a different payload — no components, just the
+    # library template's name and the inputs that customise it. Library templates are
+    # pre-categorised and pre-reviewed, so the response is usually APPROVED immediately.
+    # @param attrs [Hash] Forwarded to {LibraryTemplate}.
+    # @return [Response::Created]
+    # @raise [ActiveModel::ValidationError] if the payload is invalid.
+    # @raise [TemplateError] if the request fails.
+    def create_from_library(**attrs)
+      created_from(
+        edge_path(Edges::MESSAGE_TEMPLATES), LibraryTemplate.new(**attrs),
+        action: "create template from library"
+      )
+    end
+
+    # Creates or updates the same template across several languages in one call.
+    #
+    # Matching is on `(name, language)`: an existing pair is updated, a missing one is
+    # created. Primarily documented for authentication templates.
+    # @param attrs [Hash] Forwarded to {Template}; must include `languages:`.
+    # @return [Response::Created]
+    # @raise [TemplateError] if `languages:` is missing or the request fails.
+    # @raise [ActiveModel::ValidationError] if the template is invalid.
+    def upsert(**attrs)
+      if blank_value?(attrs[:languages])
+        raise TemplateError, "#upsert requires `languages:` (an array of locale codes); use #create for a single one"
+      end
+
+      created_from(
+        edge_path(Edges::UPSERT_MESSAGE_TEMPLATES), Template.new(**attrs), action: "upsert templates"
+      )
+    end
+
+    # Lists the account's templates.
+    #
+    # @param filters [Hash] Any documented filter: `name`, `name_or_content`, `content`,
+    #   `language`, `category`, `status`, `quality_score`, `since`, `until`, `fields`,
+    #   `limit`, `after`, `before`. Array values are encoded for you.
+    # @return [Response::Collection] Enumerable over the templates on this page.
+    # @raise [TemplateError] if the request fails.
+    def list(**filters)
+      response = client.connection.get(edge_path(Edges::MESSAGE_TEMPLATES), params: encode_filters(filters))
+
+      Response::Collection.deserialize(
+        parse_json(handle_response!(response, error_class: TemplateError, action: "list templates"))
+      )
+    end
+
+    # Reads a single template by ID.
+    # @param template_id [String] The template's numeric ID.
+    # @param fields [Array<String>, String, nil] Restrict the response to these fields.
+    # @return [Response::Node]
+    # @raise [TemplateError] if the id is missing or the request fails.
+    def find(template_id:, fields: nil)
+      raise TemplateError, "template_id can't be blank" if blank_value?(template_id)
+
+      response = client.connection.get(
+        client.path_for(template_id), params: encode_filters(fields:)
+      )
+
+      Response::Node.deserialize(
+        parse_json(handle_response!(response, error_class: TemplateError, action: "find template"))
+      )
+    end
+
+    # Edits a template.
+    #
+    # Only `category`, `components` and `message_send_ttl_seconds` are editable, and
+    # `components` is a **full replacement** — Meta has no way to patch one component.
+    # The edit goes to the template's own ID with POST; PUT and PATCH are not supported
+    # on this edge.
+    #
+    # Two limits cannot be checked locally, so they surface as API errors: only
+    # APPROVED, REJECTED and PAUSED templates may be edited (see {Response::Node#editable?}),
+    # and an approved template allows 10 edits per 30 days and 1 per 24 hours. Editing an
+    # approved template also re-submits it for review, though it keeps working meanwhile.
+    #
+    # @param template_id [String] The template's numeric ID.
+    # @param category [String, Symbol, nil] Cannot be changed on an APPROVED template.
+    # @param components [Array<Hash, Component::Base>, nil] The full replacement set.
+    # @param message_send_ttl_seconds [Integer, nil]
+    # @param parameter_format [String, Symbol] Used to build and validate `components`
+    #   locally; not sent, since Meta does not list it as editable.
+    # @return [Boolean] Whether the API reported success.
+    # @raise [TemplateError] if there is nothing to update, or the request fails.
+    # @raise [ActiveModel::ValidationError] if the replacement components are invalid.
+    def update(template_id:, category: nil, components: nil, message_send_ttl_seconds: nil,
+      parameter_format: ParameterFormats::POSITIONAL)
+      raise TemplateError, "template_id can't be blank" if blank_value?(template_id)
+
+      payload = update_payload(category:, components:, message_send_ttl_seconds:, parameter_format:)
+      raise TemplateError, "nothing to update: pass category, components or message_send_ttl_seconds" if payload.empty?
+
+      response = client.connection.post(client.path_for(template_id), json: payload)
+
+      success?(handle_response!(response, error_class: TemplateError, action: "update template"))
+    end
+
+    # Deletes templates.
+    #
+    # Three mutually exclusive ways to address them, and the choice matters:
+    #
+    #   `name:` alone   — deletes **every language variant** with that name
+    #   `hsm_id:`       — one template; Meta's docs pass `name:` alongside it
+    #   `hsm_ids:`      — up to 100 templates, and cannot be mixed with the other two
+    #
+    # Deleting an approved template blocks reuse of its name for 30 days, and messages
+    # already in flight get a 30-day delivery window under the PENDING_DELETION status.
+    # DISABLED templates cannot be deleted at all.
+    #
+    # @param name [String, nil] The template name.
+    # @param hsm_id [String, nil] A single template ID.
+    # @param hsm_ids [Array<String>, nil] Up to 100 template IDs.
+    # @return [Boolean] Whether the API reported success.
+    # @raise [TemplateError] if the arguments are unusable, or the request fails.
+    def delete(name: nil, hsm_id: nil, hsm_ids: nil)
+      params = delete_params(name:, hsm_id:, hsm_ids:)
+
+      response = client.connection.delete(edge_path(Edges::MESSAGE_TEMPLATES), params:)
+
+      success?(handle_response!(response, error_class: TemplateError, action: "delete template"))
+    end
+
+  private
+
+    # Posts a serialized payload and deserializes the create-style response.
+    # @return [Response::Created]
+    def created_from(path, payload, action:)
+      response = client.connection.post(path, json: payload.serialize)
+
+      Response::Created.deserialize(
+        parse_json(handle_response!(response, error_class: TemplateError, action:))
+      )
+    end
+
+    # @return [String] The versioned path for a WABA-scoped edge.
+    # @raise [TemplateError] if no WABA ID is configured.
+    def edge_path(edge)
+      if blank_value?(client.waba_id)
+        raise TemplateError,
+          "waba_id is required for template management; set it via Whatsapp.configure or Client.new(waba_id:)"
+      end
+
+      client.path_for(client.waba_id, edge)
+    end
+
+    # @return [Hash] Only the editable fields that were supplied.
+    def update_payload(category:, components:, message_send_ttl_seconds:, parameter_format:)
+      {
+        category: Categories.normalize(category),
+        components: components && ComponentSet.new(
+          components:, category: Categories.normalize(category), parameter_format:
+        ).serialize,
+        message_send_ttl_seconds:,
+      }.compact
+    end
+
+    # @return [Hash] The delete query parameters.
+    # @raise [TemplateError] if the addressing modes are unusable.
+    def delete_params(name:, hsm_id:, hsm_ids:)
+      return single_delete_params(name:, hsm_id:) if blank_value?(hsm_ids)
+
+      unless blank_value?(name) && blank_value?(hsm_id)
+        raise TemplateError, "hsm_ids cannot be combined with name or hsm_id"
+      end
+
+      if hsm_ids.size > Defaults::MAX_DELETE_IDS
+        raise TemplateError, "#delete accepts at most #{Defaults::MAX_DELETE_IDS} hsm_ids, got #{hsm_ids.size}"
+      end
+
+      # Meta documents this as `hsm_ids=[123,456]` — bare numbers, not a quoted
+      # JSON array of strings.
+      { hsm_ids: "[#{hsm_ids.join(',')}]" }
+    end
+
+    # @return [Hash]
+    # @raise [TemplateError] if neither addressing field was given.
+    def single_delete_params(name:, hsm_id:)
+      raise TemplateError, "#delete requires name, hsm_id or hsm_ids" if blank_value?(name) && blank_value?(hsm_id)
+
+      { name:, hsm_id: }.compact
+    end
+
+    # Graph API wants array filters as JSON arrays in the query string, not the
+    # `key[]=value` form an HTTP library would produce by default. `fields` is the
+    # exception: it is a comma-separated list.
+    # @return [Hash]
+    def encode_filters(filters)
+      filters.compact.to_h do |key, value|
+        [key, encode_filter_value(key, value)]
+      end
+    end
+
+    # @return [Object]
+    def encode_filter_value(key, value)
+      return value unless value.is_a?(Array)
+      return value.join(",") if Defaults::COMMA_JOINED_FILTERS.include?(key)
+
+      value.to_json
+    end
+
+    # @return [Boolean] The `{ "success": true }` flag, as {Whatsapp::Media#delete} does.
+    def success?(response)
+      parsed = parse_json(response)
+
+      parsed.is_a?(Hash) && parsed["success"] == true
+    end
+
+    # Plain-Ruby blank check; see the note in {ValueObject#blank_value?}.
+    # @return [Boolean]
+    def blank_value?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+  end
+end

data/lib/ruby/whatsapp/messages/address.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Address messages prompt a WhatsApp user to provide or confirm a delivery address.
+    # This feature is only available for businesses based in India (IN) and Singapore (SG).
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/address-messages
+    #
+    # Despite being a distinct message type in this library, address messages are sent
+    # over the wire as interactive messages (type: "interactive", interactive.type: "address_message").
+    class Address < Base
+      module Defaults
+        TYPE = "interactive"
+        INTERACTIVE_TYPE = "address_message"
+        ACTION_NAME = "address_message"
+      end
+
+      module Countries
+        IN = "IN"
+        SG = "SG"
+
+        ALL = [IN, SG].freeze
+      end
+
+      # @!attribute [rw] body
+      #   @return [String] The message body text shown above the address form.
+      attr_accessor :body
+
+      # @!attribute [rw] footer
+      #   @return [String, nil] Optional footer text.
+      attr_accessor :footer
+
+      # @!attribute [rw] country
+      #   @return [String] Country code. One of IN (India) or SG (Singapore).
+      attr_accessor :country
+
+      # @!attribute [rw] values
+      #   @return [Hash, nil] Pre-filled address field values shown in the form.
+      attr_accessor :values
+
+      # @!attribute [rw] saved_addresses
+      #   @return [Array<Hash>] Previously saved addresses the user can select from.
+      attr_accessor :saved_addresses
+
+      validates :body, presence: true
+      validates :country, presence: true, inclusion: { in: Countries::ALL }
+
+      # @param body [String] The message body text.
+      # @param country [String] Country code — "IN" for India, "SG" for Singapore.
+      # @param footer [String, nil] Optional footer text.
+      # @param values [Hash, nil] Pre-filled address fields (keys vary by country).
+      # @param saved_addresses [Array<Hash>] Previously saved addresses.
+      # @param kwargs [Hash] Additional keyword arguments passed to Base (:to).
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(body:, country:, footer: nil, values: nil, saved_addresses: [], **)
+        super(**)
+
+        @body = body
+        @footer = footer
+        @country = country
+        @values = values
+        @saved_addresses = saved_addresses
+
+        validate!
+      end
+
+      # Serializes the address message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized address message.
+      def serialize
+        envelope(type: Defaults::TYPE, interactive: interactive_payload)
+      end
+
+    private
+
+      # @return [Hash] The serialized interactive payload.
+      def interactive_payload
+        payload = {
+          type: Defaults::INTERACTIVE_TYPE,
+          body: { text: body },
+          action: action_payload,
+        }
+        payload[:footer] = { text: footer } if footer
+        payload
+      end
+
+      # @return [Hash] The serialized action payload.
+      def action_payload
+        {
+          name: Defaults::ACTION_NAME,
+          parameters: parameters_payload,
+        }
+      end
+
+      # @return [Hash] The serialized parameters payload.
+      def parameters_payload
+        params = { country: }
+        params[:values] = values if values
+        params[:saved_addresses] = saved_addresses if saved_addresses.any?
+        params
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/messages/audio.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Audio messages allow you to send an audio file to a WhatsApp user.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/audio-messages
+    #
+    # Audio messages do not support captions. To send audio you must either:
+    #   - Upload the audio via Whatsapp::Media#upload to obtain a media_id, then pass it as `id`
+    #   - Pass a publicly hosted URL as `link` (not recommended by Meta)
+    class Audio < Base
+      module Defaults
+        TYPE = "audio"
+      end
+
+      # @!attribute [rw] id
+      #   @return [String, nil]
+      attr_accessor :id
+
+      # @!attribute [rw] link
+      #   @return [String, nil]
+      attr_accessor :link
+
+      validate :validate_id_or_link
+
+      # @param id [String, nil] ID of the uploaded media asset (from Media#upload).
+      # @param link [String, nil] URL of the audio file hosted on a public server.
+      # @param kwargs [Hash] Additional keyword arguments passed to Base (:to).
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(id: nil, link: nil, **)
+        super(**)
+
+        @id = id
+        @link = link
+
+        validate!
+      end
+
+      # Serializes the audio message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized audio message.
+      def serialize
+        envelope(type: Defaults::TYPE, audio: audio_payload)
+      end
+
+    private
+
+      # @return [Hash] The serialized audio payload.
+      def audio_payload
+        {
+          id:,
+          link:,
+        }.compact
+      end
+
+      # Validates that either id or link is present.
+      # @return [void]
+      def validate_id_or_link
+        return if id.present? || link.present?
+
+        errors.add(:base, "Either id or link must be present")
+      end
+    end
+  end
+end