postproxy-sdk 1.12.0 → 1.14.0

data/lib/postproxy/resources/placements.rb

@@ -0,0 +1,35 @@
+module PostProxy
+  module Resources
+    # Account-wide API keys only — placements span profile groups.
+    class Placements
+      def initialize(client)
+        @client = client
+      end
+
+      def list(page: nil, per_page: nil)
+        params = {}
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+
+        result = @client.request(:get, "/placements", params: params.empty? ? nil : params)
+        placements = (result[:data] || []).map { |p| AccountPlacement.new(**p) }
+        PaginatedResponse.new(
+          data: placements,
+          total: result[:total],
+          page: result[:page],
+          per_page: result[:per_page]
+        )
+      end
+
+      # When the same placement is reachable through several connected
+      # profiles, choose which one PostProxy posts and reads through.
+      def set_active_profile(id, profile_id, idempotency_key: nil)
+        result = @client.request(:patch, "/placements/#{id}/set_active_profile",
+          json: { profile_id: profile_id },
+          idempotency_key: idempotency_key
+        )
+        AccountPlacement.new(**result)
+      end
+    end
+  end
+end

data/lib/postproxy/resources/posts.rb

@@ -28,13 +28,20 @@ module PostProxy
         Post.new(**result)
       end
 
+      # `media` items are URL strings or `{ url: }` hashes. A local
+      # `cover_file` in `platforms` (Instagram, TikTok, YouTube, Pinterest) is
+      # uploaded with the post, switching the request to multipart; a base64
+      # data URL is sent as-is. `skip_duplicate_check: true` publishes even if
+      # an identical post was just submitted (no ConflictError).
       def create(body, profiles:, media: nil, media_files: nil, platforms: nil,
                  thread: nil, scheduled_at: nil, draft: nil, queue_id: nil,
-                 queue_priority: nil, profile_group_id: nil, idempotency_key: nil)
+                 queue_priority: nil, profile_group_id: nil, idempotency_key: nil,
+                 skip_duplicate_check: nil)
         has_files = media_files && !media_files.empty?
         has_thread_files = thread&.any? { |t| t[:media_files]&.any? }
+        headers = skip_duplicate_check ? { "X-Skip-Duplicate-Check" => "true" } : nil
 
-        if has_files || has_thread_files
+        if has_files || has_thread_files || local_cover_file?(platforms)
           form_data = { "post[body]" => body }
           form_data["post[scheduled_at]"] = format_time(scheduled_at) if scheduled_at
           form_data["post[draft]"] = draft.to_s if !draft.nil?
@@ -48,17 +55,10 @@ module PostProxy
           end
 
           media&.each do |m|
-            files << ["media[]", nil, m, "text/plain"]
+            files << ["media[]", nil, media_url(m), "text/plain"]
           end
 
-          if platforms
-            params_hash = platforms.is_a?(PlatformParams) ? platforms.to_h : platforms
-            params_hash.each do |platform, platform_params|
-              platform_params.each do |key, value|
-                files << ["platforms[#{platform}][#{key}]", nil, value.to_s, "text/plain"]
-              end
-            end
-          end
+          append_platform_params(files, platforms) if platforms
 
           media_files&.each do |path|
             path = path.to_s
@@ -72,7 +72,7 @@ module PostProxy
             form_data["thread[#{i}][body]"] = t[:body] if t[:body]
 
             t[:media]&.each do |m|
-              files << ["thread[#{i}][media][]", nil, m, "text/plain"]
+              files << ["thread[#{i}][media][]", nil, media_url(m), "text/plain"]
             end
 
             t[:media_files]&.each do |path|
@@ -88,7 +88,8 @@ module PostProxy
             data: form_data,
             files: files,
             profile_group_id: profile_group_id,
-            idempotency_key: idempotency_key
+            idempotency_key: idempotency_key,
+            headers: headers
           )
         else
           post_payload = { body: body }
@@ -105,20 +106,25 @@ module PostProxy
           result = @client.request(:post, "/posts",
             json: json_body,
             profile_group_id: profile_group_id,
-            idempotency_key: idempotency_key
+            idempotency_key: idempotency_key,
+            headers: headers
           )
         end
 
         Post.new(**result)
       end
 
+      # On a published post only `body`, `platforms.youtube.title`,
+      # `platforms.pinterest.title` and `platforms.pinterest.destination_link`
+      # can change; the edit is pushed to the platforms in the background
+      # (`platform_post.edited` / `platform_post.edit_failed` webhooks).
       def update(id, body: nil, profiles: nil, media: nil, media_files: nil, platforms: nil,
                  thread: nil, scheduled_at: nil, draft: nil, queue_id: nil,
                  queue_priority: nil, profile_group_id: nil, idempotency_key: nil)
         has_files = media_files && !media_files.empty?
         has_thread_files = thread&.any? { |t| t[:media_files]&.any? }
 
-        if has_files || has_thread_files
+        if has_files || has_thread_files || local_cover_file?(platforms)
           form_data = {}
           form_data["post[body]"] = body if body
           form_data["post[scheduled_at]"] = format_time(scheduled_at) if scheduled_at
@@ -133,17 +139,10 @@ module PostProxy
           end
 
           media&.each do |m|
-            files << ["media[]", nil, m, "text/plain"]
+            files << ["media[]", nil, media_url(m), "text/plain"]
           end
 
-          if platforms
-            params_hash = platforms.is_a?(PlatformParams) ? platforms.to_h : platforms
-            params_hash.each do |platform, platform_params|
-              platform_params.each do |key, value|
-                files << ["platforms[#{platform}][#{key}]", nil, value.to_s, "text/plain"]
-              end
-            end
-          end
+          append_platform_params(files, platforms) if platforms
 
           media_files&.each do |path|
             path = path.to_s
@@ -157,7 +156,7 @@ module PostProxy
             form_data["thread[#{i}][body]"] = t[:body] if t[:body]
 
             t[:media]&.each do |m|
-              files << ["thread[#{i}][media][]", nil, m, "text/plain"]
+              files << ["thread[#{i}][media][]", nil, media_url(m), "text/plain"]
             end
 
             t[:media_files]&.each do |path|
@@ -249,6 +248,68 @@ module PostProxy
 
       private
 
+      def media_url(item)
+        return item unless item.is_a?(Hash)
+
+        item[:url] || item["url"]
+      end
+
+      # `cover_file` is a local path unless it's a base64 data URL, which the
+      # API takes as a plain string.
+      def local_cover_file_value?(key, value)
+        key.to_s == "cover_file" && value.is_a?(String) && !value.start_with?("data:")
+      end
+
+      def local_cover_file?(platforms)
+        return false unless platforms
+
+        params_hash = platforms.is_a?(PlatformParams) ? platforms.to_h : platforms
+        params_hash.any? do |_, platform_params|
+          platform_params = platform_params.to_h if platform_params.is_a?(Model)
+          platform_params.is_a?(Hash) && platform_params.any? { |k, v| local_cover_file_value?(k, v) }
+        end
+      end
+
+      # Platform params as flat form fields; a local `cover_file` is attached
+      # as a file.
+      def append_platform_params(files, platforms)
+        params_hash = platforms.is_a?(PlatformParams) ? platforms.to_h : platforms
+        params_hash.each do |platform, platform_params|
+          next if platform_params.nil?
+
+          platform_params = platform_params.to_h if platform_params.is_a?(Model)
+          platform_params.each do |key, value|
+            next if value.nil?
+
+            field = "platforms[#{platform}][#{key}]"
+            if local_cover_file_value?(key, value)
+              filename = File.basename(value)
+              files << [field, filename, File.open(value, "rb"), mime_type_for(filename)]
+            else
+              append_form_value(files, field, value)
+            end
+          end
+        end
+      end
+
+      def append_form_value(files, field, value)
+        case value
+        when Array
+          # Hashes (e.g. Instagram user tags) get an index so their fields stay
+          # grouped; Rails reads numeric keys back as an array.
+          value.each_with_index do |item, i|
+            nested = item.is_a?(Hash) || item.is_a?(Model)
+            append_form_value(files, nested ? "#{field}[#{i}]" : "#{field}[]", item)
+          end
+        when Hash
+          value.each { |k, v| append_form_value(files, "#{field}[#{k}]", v) unless v.nil? }
+        when Model
+          append_form_value(files, field, value.to_h)
+        else
+          files << [field, nil, value.to_s, "text/plain"]
+        end
+      end
+
       def format_time(value)
         return value if value.is_a?(String)
         value.iso8601

data/lib/postproxy/resources/profile_groups.rb

@@ -30,9 +30,16 @@ module PostProxy
       end
 
       # OAuth flow. BlueSky and Telegram use their dedicated helpers below.
-      def initialize_connection(id, platform:, redirect_url: nil)
+      #
+      # `onboarding` picks the flow: Instagram "instagram" (default) or
+      # "facebook" (Facebook login — needed for reel music); WhatsApp "api" or
+      # "business_app". `refresh_connection: true` re-authorizes an existing
+      # profile.
+      def initialize_connection(id, platform:, redirect_url: nil, onboarding: nil, refresh_connection: nil)
         body = { platform: platform }
         body[:redirect_url] = redirect_url if redirect_url
+        body[:onboarding] = onboarding if onboarding
+        body[:refresh_connection] = refresh_connection unless refresh_connection.nil?
         result = @client.request(:post, "/profile_groups/#{id}/initialize_connection", json: body)
         ConnectionResponse.new(**result)
       end

data/lib/postproxy/resources/profiles.rb

@@ -1,3 +1,5 @@
+require "erb"
+
 module PostProxy
   module Resources
     class Profiles
@@ -36,6 +38,97 @@ module PostProxy
         ProfileStatsResponse.new(data: result[:data])
       end
 
+      # Per-day series. `attribution: "publish"` attributes post metrics to the
+      # day the post was published instead of the day they were received.
+      def daily_stats(id, placement_id: nil, from: nil, to: nil, attribution: nil, profile_group_id: nil)
+        params = {}
+        params[:placement_id] = placement_id if placement_id
+        params[:from] = from if from
+        params[:to] = to if to
+        params[:attribution] = attribution if attribution
+
+        result = @client.request(:get, "/profiles/#{id}/daily_stats",
+          params: params.empty? ? nil : params,
+          profile_group_id: profile_group_id
+        )
+        DailyStatsResponse.new(data: result[:data])
+      end
+
+      def follower_history(id, placement_id: nil, from: nil, to: nil, profile_group_id: nil)
+        params = {}
+        params[:placement_id] = placement_id if placement_id
+        params[:from] = from if from
+        params[:to] = to if to
+
+        result = @client.request(:get, "/profiles/#{id}/follower_history",
+          params: params.empty? ? nil : params,
+          profile_group_id: profile_group_id
+        )
+        FollowerHistoryResponse.new(data: result[:data])
+      end
+
+      # Instagram only: whether a DM participant is verified and follows you.
+      def participant_status(id, user_id, profile_group_id: nil)
+        result = @client.request(:get, "/profiles/#{id}/participants/#{ERB::Util.url_encode(user_id.to_s)}",
+          profile_group_id: profile_group_id
+        )
+        ParticipantStatus.new(**result)
+      end
+
+      # LinkedIn only: resolve a company page URL (or vanity name) to the URN
+      # used to @-mention it in a post.
+      def resolve_mention(id, url, profile_group_id: nil)
+        result = @client.request(:get, "/profiles/#{id}/resolve_mention",
+          params: { url: url },
+          profile_group_id: profile_group_id
+        )
+        ResolvedMention.new(**result)
+      end
+
+      # Music and original sounds an Instagram reel can attach via
+      # `platforms.instagram.audio_id`. Profiles connected via Facebook login
+      # only. `audio_type` is "music" or "original_sound". Returns the
+      # response hash (`data` plus paging).
+      def instagram_available_audio(id, audio_type: nil, search_query: nil, profile_group_id: nil)
+        params = {}
+        params[:audio_type] = audio_type if audio_type
+        params[:search_query] = search_query if search_query
+
+        @client.request(:get, "/profiles/#{id}/instagram/available_audio",
+          params: params.empty? ? nil : params,
+          profile_group_id: profile_group_id
+        )
+      end
+
+      # Facebook only. `page_id` is the placement id from #placements. Returns
+      # the Page fields as a hash.
+      def facebook_page(id, page_id, fields: nil, profile_group_id: nil)
+        params = { page_id: page_id }
+        params[:fields] = fields if fields
+
+        @client.request(:get, "/profiles/#{id}/facebook/page", params: params, profile_group_id: profile_group_id)
+      end
+
+      # Update the Page's about / contact fields, e.g. `about` (255 characters
+      # or fewer), `description`, `website`, `phone`, `emails`.
+      def update_facebook_page(id, page_id, fields, profile_group_id: nil, idempotency_key: nil)
+        @client.request(:patch, "/profiles/#{id}/facebook/update_page",
+          json: fields.merge(page_id: page_id),
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
+      end
+
+      # Moves the profile (with its placements) to another profile group.
+      def assign_to_group(id, target_profile_group_id, profile_group_id: nil, idempotency_key: nil)
+        result = @client.request(:patch, "/profiles/#{id}/assign_to_group",
+          json: { target_profile_group_id: target_profile_group_id },
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
+        Profile.new(**result)
+      end
+
       # Moves a placement (e.g. a Facebook Page or Telegram channel) to another
       # profile group. `placement_id` is the placement's external ID as
       # returned by #placements.
@@ -97,6 +190,44 @@ module PostProxy
         PostSync.new(**result)
       end
 
+      # Imports DM history back to `from`. Like #backfill_posts, runs in the
+      # background and only one runs per profile.
+      def backfill_chats(id, from:, profile_group_id: nil, idempotency_key: nil)
+        result = @client.request(:post, "/profiles/#{id}/backfill_chats",
+          json: { from: from },
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
+        ChatSync.new(**result)
+      end
+
+      def chat_syncs(id, trigger: nil, status: nil, page: nil, per_page: nil, profile_group_id: nil)
+        params = {}
+        params[:trigger] = trigger if trigger
+        params[:status] = status if status
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+
+        result = @client.request(:get, "/profiles/#{id}/chat_syncs",
+          params: params.empty? ? nil : params,
+          profile_group_id: profile_group_id
+        )
+        syncs = (result[:data] || []).map { |s| ChatSync.new(**s) }
+        PaginatedResponse.new(
+          data: syncs,
+          total: result[:total],
+          page: result[:page],
+          per_page: result[:per_page]
+        )
+      end
+
+      def chat_sync(id, chat_sync_id, profile_group_id: nil)
+        result = @client.request(:get, "/profiles/#{id}/chat_syncs/#{chat_sync_id}",
+          profile_group_id: profile_group_id
+        )
+        ChatSync.new(**result)
+      end
+
       # Lists DM ice breakers. Supported for Instagram profiles only.
       def ice_breakers(id, profile_group_id: nil)
         result = @client.request(:get, "/profiles/#{id}/ice_breakers", profile_group_id: profile_group_id)

data/lib/postproxy/resources/whatsapp.rb

@@ -0,0 +1,278 @@
+module PostProxy
+  module Resources
+    # WhatsApp number administration: registration, business profile, display
+    # name, username, blocked users, groups and conversion events. Responses
+    # are Meta's payloads, returned as plain hashes.
+    #
+    # `phone_number_id` is the placement id from
+    # `profiles.placements(profile_id)`. Dataset and conversion calls are
+    # account-level and don't take one.
+    class WhatsApp
+      def initialize(client)
+        @client = client
+      end
+
+      # --- Phone number ---
+
+      def number_info(profile_id, phone_number_id, profile_group_id: nil)
+        call(:get, profile_id, "number_info", { phone_number_id: phone_number_id }, profile_group_id)
+      end
+
+      # `pin` is the 6-digit two-step verification PIN.
+      def register_phone_number(profile_id, phone_number_id, pin, profile_group_id: nil, idempotency_key: nil)
+        call(:post, profile_id, "register_phone_number",
+          { phone_number_id: phone_number_id, pin: pin }, profile_group_id, idempotency_key)
+      end
+
+      # `method` is "SMS" or "VOICE".
+      def request_verification_code(profile_id, phone_number_id, method: nil, language: nil, profile_group_id: nil,
+        idempotency_key: nil)
+        call(:post, profile_id, "request_verification_code",
+          { phone_number_id: phone_number_id, method: method, language: language }, profile_group_id, idempotency_key)
+      end
+
+      def verify_phone_number(profile_id, phone_number_id, code, profile_group_id: nil, idempotency_key: nil)
+        call(:post, profile_id, "verify_phone_number",
+          { phone_number_id: phone_number_id, code: code }, profile_group_id, idempotency_key)
+      end
+
+      # --- Business profile ---
+
+      def business_profile(profile_id, phone_number_id, profile_group_id: nil)
+        call(:get, profile_id, "business_profile", { phone_number_id: phone_number_id }, profile_group_id)
+      end
+
+      def update_business_profile(profile_id, phone_number_id, about: nil, address: nil, description: nil,
+        email: nil, websites: nil, vertical: nil, profile_group_id: nil, idempotency_key: nil)
+        call(:patch, profile_id, "update_business_profile", {
+          phone_number_id: phone_number_id,
+          about: about,
+          address: address,
+          description: description,
+          email: email,
+          websites: websites,
+          vertical: vertical
+        }, profile_group_id, idempotency_key)
+      end
+
+      # Pass a public `url`, or base64 `data` with its `content_type`
+      # (image/jpeg or image/png).
+      def update_business_profile_photo(profile_id, phone_number_id, url: nil, data: nil, content_type: nil,
+        profile_group_id: nil, idempotency_key: nil)
+        call(:post, profile_id, "update_business_profile_photo", {
+          phone_number_id: phone_number_id,
+          url: url,
+          data: data,
+          content_type: content_type
+        }, profile_group_id, idempotency_key)
+      end
+
+      # --- Display name ---
+
+      def display_name(profile_id, phone_number_id, profile_group_id: nil)
+        call(:get, profile_id, "display_name", { phone_number_id: phone_number_id }, profile_group_id)
+      end
+
+      # Meta reviews the new name; the outcome arrives as the
+      # `placement.name_status_updated` webhook.
+      def request_display_name_change(profile_id, phone_number_id, display_name, profile_group_id: nil,
+        idempotency_key: nil)
+        call(:post, profile_id, "request_display_name_change",
+          { phone_number_id: phone_number_id, display_name: display_name }, profile_group_id, idempotency_key)
+      end
+
+      # --- Username ---
+
+      def username(profile_id, phone_number_id, profile_group_id: nil)
+        call(:get, profile_id, "username", { phone_number_id: phone_number_id }, profile_group_id)
+      end
+
+      # `transfer_action` is "none" or "force_transfer".
+      def set_username(profile_id, phone_number_id, username, transfer_action: nil, profile_group_id: nil,
+        idempotency_key: nil)
+        call(:put, profile_id, "set_username",
+          { phone_number_id: phone_number_id, username: username, transfer_action: transfer_action },
+          profile_group_id, idempotency_key)
+      end
+
+      def delete_username(profile_id, phone_number_id, profile_group_id: nil, idempotency_key: nil)
+        call(:delete, profile_id, "delete_username", { phone_number_id: phone_number_id }, profile_group_id,
+          idempotency_key)
+      end
+
+      def username_suggestions(profile_id, phone_number_id, profile_group_id: nil)
+        call(:get, profile_id, "username_suggestions", { phone_number_id: phone_number_id }, profile_group_id)
+      end
+
+      # --- Blocked users ---
+
+      def blocked_users(profile_id, phone_number_id, limit: nil, after: nil, profile_group_id: nil)
+        call(:get, profile_id, "blocked_users",
+          { phone_number_id: phone_number_id, limit: limit, after: after }, profile_group_id)
+      end
+
+      def blocked_user_status(profile_id, phone_number_id, user, profile_group_id: nil)
+        call(:get, profile_id, "blocked_user_status", { phone_number_id: phone_number_id, user: user },
+          profile_group_id)
+      end
+
+      # `users` are phone numbers or WhatsApp ids.
+      def block_users(profile_id, phone_number_id, users, profile_group_id: nil, idempotency_key: nil)
+        call(:post, profile_id, "block_users", { phone_number_id: phone_number_id, users: users },
+          profile_group_id, idempotency_key)
+      end
+
+      def unblock_users(profile_id, phone_number_id, users, profile_group_id: nil, idempotency_key: nil)
+        call(:post, profile_id, "unblock_users", { phone_number_id: phone_number_id, users: users },
+          profile_group_id, idempotency_key)
+      end
+
+      # --- Groups ---
+
+      def groups(profile_id, phone_number_id, limit: nil, after: nil, profile_group_id: nil)
+        call(:get, profile_id, "groups", { phone_number_id: phone_number_id, limit: limit, after: after },
+          profile_group_id)
+      end
+
+      # `join_approval_mode` is "approval_required" or "auto_approve".
+      def create_group(profile_id, phone_number_id, subject, description: nil, join_approval_mode: nil,
+        profile_group_id: nil, idempotency_key: nil)
+        call(:post, profile_id, "create_group", {
+          phone_number_id: phone_number_id,
+          subject: subject,
+          description: description,
+          join_approval_mode: join_approval_mode
+        }, profile_group_id, idempotency_key)
+      end
+
+      def group(profile_id, phone_number_id, group_id, profile_group_id: nil)
+        call(:get, profile_id, "group", { phone_number_id: phone_number_id, group_id: group_id }, profile_group_id)
+      end
+
+      def update_group(profile_id, phone_number_id, group_id, subject: nil, description: nil,
+        join_approval_mode: nil, profile_group_id: nil, idempotency_key: nil)
+        call(:patch, profile_id, "update_group", {
+          phone_number_id: phone_number_id,
+          group_id: group_id,
+          subject: subject,
+          description: description,
+          join_approval_mode: join_approval_mode
+        }, profile_group_id, idempotency_key)
+      end
+
+      def delete_group(profile_id, phone_number_id, group_id, profile_group_id: nil, idempotency_key: nil)
+        call(:delete, profile_id, "delete_group", { phone_number_id: phone_number_id, group_id: group_id },
+          profile_group_id, idempotency_key)
+      end
+
+      def add_group_participants(profile_id, phone_number_id, group_id, phone_numbers, profile_group_id: nil,
+        idempotency_key: nil)
+        group_members(:post, profile_id, "add_group_participants", phone_number_id, group_id, phone_numbers,
+          profile_group_id, idempotency_key)
+      end
+
+      def remove_group_participants(profile_id, phone_number_id, group_id, phone_numbers, profile_group_id: nil,
+        idempotency_key: nil)
+        group_members(:post, profile_id, "remove_group_participants", phone_number_id, group_id, phone_numbers,
+          profile_group_id, idempotency_key)
+      end
+
+      def create_group_invite_link(profile_id, phone_number_id, group_id, profile_group_id: nil,
+        idempotency_key: nil)
+        call(:post, profile_id, "create_group_invite_link",
+          { phone_number_id: phone_number_id, group_id: group_id }, profile_group_id, idempotency_key)
+      end
+
+      def group_join_requests(profile_id, phone_number_id, group_id, profile_group_id: nil)
+        call(:get, profile_id, "group_join_requests", { phone_number_id: phone_number_id, group_id: group_id },
+          profile_group_id)
+      end
+
+      def approve_group_join_requests(profile_id, phone_number_id, group_id, phone_numbers, profile_group_id: nil,
+        idempotency_key: nil)
+        group_members(:post, profile_id, "approve_group_join_requests", phone_number_id, group_id, phone_numbers,
+          profile_group_id, idempotency_key)
+      end
+
+      def reject_group_join_requests(profile_id, phone_number_id, group_id, phone_numbers, profile_group_id: nil,
+        idempotency_key: nil)
+        group_members(:post, profile_id, "reject_group_join_requests", phone_number_id, group_id, phone_numbers,
+          profile_group_id, idempotency_key)
+      end
+
+      # --- Conversions (account-level) ---
+
+      def dataset(profile_id, profile_group_id: nil)
+        call(:get, profile_id, "dataset", {}, profile_group_id)
+      end
+
+      def create_dataset(profile_id, profile_group_id: nil, idempotency_key: nil)
+        call(:post, profile_id, "create_dataset", {}, profile_group_id, idempotency_key)
+      end
+
+      # Report a conversion (e.g. Purchase, LeadSubmitted) back to Meta for a
+      # click-to-WhatsApp ad. Identify the person by `chat_id` or `phone`.
+      def send_conversion_event(profile_id, event_name:, event_id:, chat_id: nil, phone: nil, dataset_id: nil,
+        event_time: nil, email: nil, external_id: nil, currency: nil, value: nil, content_ids: nil,
+        test_code: nil, profile_group_id: nil, idempotency_key: nil)
+        call(:post, profile_id, "send_conversion_event", {
+          event_name: event_name,
+          event_id: event_id,
+          chat_id: chat_id,
+          phone: phone,
+          dataset_id: dataset_id,
+          event_time: event_time,
+          email: email,
+          external_id: external_id,
+          currency: currency,
+          value: value,
+          content_ids: content_ids,
+          test_code: test_code
+        }, profile_group_id, idempotency_key)
+      end
+
+      # --- Media ---
+
+      # Download an inbound media file (e.g. from a message attachment's
+      # `external_id`). Returns a RawResponse: `data` holds the raw bytes,
+      # `content_type` the MIME type.
+      def media(profile_id, phone_number_id, media_id, profile_group_id: nil)
+        @client.request(:get, "/profiles/#{profile_id}/whatsapp/media",
+          params: { phone_number_id: phone_number_id, media_id: media_id },
+          profile_group_id: profile_group_id,
+          raw: true
+        )
+      end
+
+      private
+
+      # Reads and deletes send their arguments as query params; everything
+      # else as a JSON body. Nil values are dropped.
+      def call(http_method, profile_id, action, data, profile_group_id, idempotency_key = nil)
+        path = "/profiles/#{profile_id}/whatsapp/#{action}"
+        compact = data.compact
+
+        if %i[get delete].include?(http_method)
+          @client.request(http_method, path,
+            params: compact.empty? ? nil : compact,
+            profile_group_id: profile_group_id,
+            idempotency_key: idempotency_key
+          )
+        else
+          @client.request(http_method, path,
+            json: compact,
+            profile_group_id: profile_group_id,
+            idempotency_key: idempotency_key
+          )
+        end
+      end
+
+      def group_members(http_method, profile_id, action, phone_number_id, group_id, phone_numbers,
+        profile_group_id, idempotency_key)
+        call(http_method, profile_id, action,
+          { phone_number_id: phone_number_id, group_id: group_id, phone_numbers: phone_numbers },
+          profile_group_id, idempotency_key)
+      end
+    end
+  end
+end