postproxy-sdk 1.12.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fabdc6a06ca3cef409cf88533c925ff183e3e1c7089fd53aa541c09bff0aa6f
-  data.tar.gz: 7b4245a53e37aab93f006d408430676dbe3352a8815e5479de765946d941e20e
+  metadata.gz: a6be6a31464b3afaf473473d94fd639b2553782cf0494e87ccfebb3e5e2e5e4a
+  data.tar.gz: 0ff052e8410c536e2938cf6887cecee713f615afa11207c88f733c29b6770d07
 SHA512:
-  metadata.gz: 97e32211fa2f54a2a28b506333108a484153083efcf9272bcf23fc821e27e6e2e88be7dd7d166acf6f9cd339a69a07afd1fb9b9f3c271a860b8ec9f5b41b7a9e
-  data.tar.gz: 3217e3f75dd540a6c13215dc5a5b7830d483ebd38f4cd30433162e7c732f69b214b06e3f73ccfbe5683f953a9c57133bf9dd1de4bdaf4ffe5dc3a631c15a132e
+  metadata.gz: 2a67b96326d47a4c33463c10b5346ff28debf6e4faf7ef11a297fded79abf9cac4b062099cc1e1cf6002e6e9f2bc4b9e641dbf26537552f8d2041310598a8163
+  data.tar.gz: cf8c37298d421c37886440e75819a9a1462d34ccadad79e4623cbb2cb431292e4ead2e1ba0014bd13b522c9c0e62737eeb524987bde5a97f99404e3416686950

data/README.md

@@ -464,6 +464,73 @@ message = client.comments.private_reply("post-id", "comment-id", profile_id: "pr
 puts message.chat_id, message.status
 ```
 
+### Quick replies and buttons (Facebook & Instagram)
+
+Meta's two interactive primitives. **Quick replies** are chips above the participant's
+composer that disappear once tapped; **buttons** are attached to the message and stay in
+the thread. Telegram's equivalent is `reply_markup` above — passing `quick_replies` or
+`buttons` on a Telegram or Bluesky chat returns `422`.
+
+Each param accepts model instances or plain hashes, whichever you prefer:
+
+```ruby
+# Quick replies — up to 13. title ≤ 20 chars, payload ≤ 1000.
+client.messages.send(
+  chat.id,
+  body: "What can I help with?",
+  quick_replies: [
+    PostProxy::QuickReply.new(title: "Track order", payload: "TRACK"),
+    { title: "Talk to support", payload: "HELP" }
+  ]
+)
+
+# Buttons — up to 3, each either web_url or postback. card is optional and
+# requires buttons.
+client.messages.send(
+  chat.id,
+  body: "Your order shipped",
+  buttons: [
+    PostProxy::MessageButton.new(type: "web_url", title: "Track", url: "https://shop.example.com/o/123"),
+    PostProxy::MessageButton.new(type: "postback", title: "Cancel", payload: "CANCEL:123")
+  ],
+  card: PostProxy::MessageCard.new(
+    subtitle: "Arriving Friday",
+    image_url: "https://cdn.example.com/shoe.png",
+    default_action: { type: "web_url", url: "https://shop.example.com/o/123" }
+  )
+)
+```
+
+Buttons are delivered as a Meta generic template and your `body` becomes the template's
+element title — so **`body` is capped at 80 characters when buttons are present**. That is
+Meta's limit, not PostProxy's, and a longer body is rejected with a `422` naming the
+length. Buttons cannot be combined with media. Instagram is stricter than Messenger: it
+delivers quick replies only on a plain-text message, so `quick_replies` with media or with
+`buttons` returns `422` on Instagram while both are accepted on Facebook.
+
+Validation happens server-side and names the offending index — `buttons[1].url must be an
+https:// URL` — surfacing as the SDK's usual error for a `422`.
+
+> The new params are sent on the JSON path only. To combine quick replies with an
+> attachment, pass `media` as a hosted URL rather than uploading via `media_files`.
+
+A tap comes back as an **inbound message** carrying `tapped_action`:
+
+```ruby
+inbound = client.messages.list(chat.id, direction: "inbound")
+inbound.data.each do |msg|
+  next unless msg.tapped_action
+
+  # kind: "quick_reply", "postback", or "callback_query"
+  puts "#{msg.tapped_action.kind}: #{msg.tapped_action.payload}"
+end
+```
+
+Subscribe to `message.received` to react to taps as they happen — the same field is on the
+webhook payload. `tapped_action` is derived rather than stored, so it also resolves for
+taps recorded before PostProxy exposed it, including Instagram ice-breaker taps and
+Telegram callback queries (`kind` `"callback_query"`). A tap also opens the 24h window.
+
 ## Profile comments (Google Business reviews)
 
 Profile-level comments expose Google Business reviews and replies. Reviews are user-generated — the SDK lets you list/get them and reply to or delete your own replies. Reviews sync twice daily.

data/lib/postproxy/resources/messages.rb

@@ -22,9 +22,16 @@ module PostProxy
         )
       end
 
+      # quick_replies, buttons, and card are Facebook and Instagram only — they
+      # return 422 on Telegram and Bluesky, where reply_markup is the
+      # equivalent. They are sent on the JSON path only, so pass media as hosted
+      # URLs rather than media_files when combining with an attachment.
+      #
+      # Each accepts model instances or plain hashes.
       def send_message(chat_id, body: nil, media: nil, media_files: nil, tag: nil,
-                       reply_to_external_id: nil, reply_markup: nil, profile_group_id: nil,
-                       idempotency_key: nil)
+                       reply_to_external_id: nil, reply_markup: nil,
+                       quick_replies: nil, buttons: nil, card: nil,
+                       profile_group_id: nil, idempotency_key: nil)
         has_files = media_files && !media_files.empty?
 
         if has_files
@@ -58,6 +65,9 @@ module PostProxy
           json_body[:tag] = tag if tag
           json_body[:reply_to_external_id] = reply_to_external_id if reply_to_external_id
           json_body[:reply_markup] = reply_markup if reply_markup
+          json_body[:quick_replies] = quick_replies.map { |q| serialize_interactive(q) } if quick_replies
+          json_body[:buttons] = buttons.map { |b| serialize_interactive(b) } if buttons
+          json_body[:card] = serialize_interactive(card) if card
 
           result = @client.request(:post, "/chats/#{chat_id}/messages",
             json: json_body,
@@ -111,6 +121,13 @@ module PostProxy
 
       private
 
+      # Interactive params accept model instances or plain hashes. Models expose
+      # to_h with nils dropped, so an omitted content_type stays omitted rather
+      # than being sent as null.
+      def serialize_interactive(value)
+        value.respond_to?(:to_h) && !value.is_a?(Hash) ? value.to_h : value
+      end
+
       def mime_type_for(filename)
         case File.extname(filename).downcase
         when ".jpg", ".jpeg" then "image/jpeg"

data/lib/postproxy/types.rb

@@ -429,11 +429,94 @@ module PostProxy
     end
   end
 
+  # A tappable chip above the participant's composer, gone once tapped.
+  # Facebook and Instagram only; up to 13 per send. +content_type+ is optional
+  # on send (only "text" is accepted) and always present on responses.
+  class QuickReply < Model
+    attr_accessor :content_type, :title, :payload
+
+    def initialize(**attrs)
+      @content_type = nil
+      super
+    end
+
+    def to_h
+      { content_type: @content_type, title: @title, payload: @payload }.compact
+    end
+  end
+
+  # A button attached to the message, delivered as a Meta generic template.
+  # Facebook and Instagram only; up to 3 per send. +url+ is required and must be
+  # https when +type+ is "web_url"; +payload+ is required when +type+ is
+  # "postback". +type+ is a plain string rather than an enum so a new Meta
+  # button type needs no SDK release.
+  class MessageButton < Model
+    attr_accessor :type, :title, :url, :payload
+
+    def initialize(**attrs)
+      @url = nil
+      @payload = nil
+      super
+    end
+
+    def to_h
+      { type: @type, title: @title, url: @url, payload: @payload }.compact
+    end
+  end
+
+  class CardDefaultAction < Model
+    attr_accessor :type, :url
+
+    def to_h
+      { type: @type, url: @url }.compact
+    end
+  end
+
+  # Extra fields for the generic-template element that carries +buttons+.
+  # Requires +buttons+. +subtitle+ is capped at 80 characters, and both URLs
+  # must be https.
+  class MessageCard < Model
+    attr_accessor :subtitle, :image_url, :default_action
+
+    def initialize(**attrs)
+      @subtitle = nil
+      @image_url = nil
+      @default_action = nil
+      super
+      if @default_action && !@default_action.is_a?(CardDefaultAction)
+        @default_action = CardDefaultAction.new(**@default_action.transform_keys(&:to_sym))
+      end
+    end
+
+    def to_h
+      {
+        subtitle: @subtitle,
+        image_url: @image_url,
+        default_action: @default_action&.to_h
+      }.compact
+    end
+  end
+
+  # Set on inbound messages created by a tap on an element you sent. Derived
+  # from platform_data rather than stored, so it also resolves for taps ingested
+  # before PostProxy exposed this field. +kind+ is one of "quick_reply",
+  # "postback", or "callback_query" — the last is Telegram, so this is not
+  # Meta-only even though the send params are.
+  class TappedAction < Model
+    attr_accessor :kind, :payload, :title
+
+    def initialize(**attrs)
+      @title = nil
+      super
+    end
+  end
+
   class Message < Model
     attr_accessor :id, :chat_id, :external_id, :direction, :body, :status,
                   :tag, :external_comment_id, :error_message, :platform_data,
                   :external_posted_at, :external_delivered_at, :external_read_at,
                   :external_edited_at, :reply_to_external_id, :reply_markup,
+                  :quick_replies, :buttons, :card, :tapped_action,
                   :external_deleted_at, :reactions, :attachments,
                   :is_unsupported, :created_at
 
@@ -450,6 +533,10 @@ module PostProxy
       @external_edited_at = nil
       @reply_to_external_id = nil
       @reply_markup = nil
+      @quick_replies = nil
+      @buttons = nil
+      @card = nil
+      @tapped_action = nil
       @external_deleted_at = nil
       @reactions = []
       @attachments = []
@@ -467,6 +554,20 @@ module PostProxy
       @attachments = (@attachments || []).map do |a|
         a.is_a?(Attachment) ? a : Attachment.new(**a.transform_keys(&:to_sym))
       end
+      # Left nil rather than [] when absent — the API omits these on non-Meta
+      # networks, and an empty array would read as "sent with none".
+      @quick_replies = @quick_replies&.map do |q|
+        q.is_a?(QuickReply) ? q : QuickReply.new(**q.transform_keys(&:to_sym))
+      end
+      @buttons = @buttons&.map do |b|
+        b.is_a?(MessageButton) ? b : MessageButton.new(**b.transform_keys(&:to_sym))
+      end
+      if @card && !@card.is_a?(MessageCard)
+        @card = MessageCard.new(**@card.transform_keys(&:to_sym))
+      end
+      if @tapped_action && !@tapped_action.is_a?(TappedAction)
+        @tapped_action = TappedAction.new(**@tapped_action.transform_keys(&:to_sym))
+      end
     end
 
     private

data/lib/postproxy/version.rb

@@ -1,3 +1,3 @@
 module PostProxy
-  VERSION = "1.12.0"
+  VERSION = "1.13.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: postproxy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 1.13.0
 platform: ruby
 authors:
 - PostProxy