sendly 3.37.0 → 3.38.0

data/lib/sendly/messages.rb

@@ -10,14 +10,66 @@ module Sendly
       @client = client
     end
 
-    # Send an SMS message
+    # Send an SMS, WhatsApp, or RCS message
+    #
+    # Pass +channel: "whatsapp"+ to send on WhatsApp. WhatsApp sends require
+    # a live API key and a +from+ number with an active WhatsApp connection
+    # (see +client.whatsapp.signup+). Provide exactly one of +text+
+    # (free-form, max 4096 bytes), +media_urls+ (a single attachment;
+    # optional +text+ becomes its caption, max 1024 bytes), or +template+
+    # (an approved template). Free-form text and media only deliver inside
+    # an open 24-hour customer-service window — outside it the API responds
+    # 422 +whatsapp_window_closed+; send a template instead (check with
+    # +client.whatsapp.window+).
+    #
+    # Pass +channel: "rcs"+ to send on RCS. RCS sends require a live API key
+    # and a sendable RCS agent on your workspace (see +client.rcs.agents+).
+    # Provide exactly one of +text+ (free-form, optionally with
+    # +suggestions+ — suggested replies and URL actions) or +card+ (a rich
+    # card). +agent_id+ picks the sending agent when your workspace has more
+    # than one. Recipients that can't receive RCS get +text+ delivered as
+    # plain SMS (billed as SMS) unless +fallback_to_sms+ is false — the
+    # returned {Sendly::RcsMessage} discloses which channel delivered.
     #
     # @param to [String] Recipient phone number in E.164 format
-    # @param text [String] Message content (max 1600 characters)
-    # @param from [String] Sender ID or phone number (optional)
-    # @param message_type [String] Message type: "marketing" (default) or "transactional"
+    # @param text [String] Message content (max 1600 characters for SMS);
+    #   for WhatsApp, optional free-form text or the media caption
+    # @param from [String] Sender ID or phone number (optional for SMS);
+    #   required for WhatsApp — must be a WhatsApp-connected number
+    # @param message_type [String] Message type: "marketing" (default) or "transactional" (SMS only)
     # @param metadata [Hash] Custom JSON metadata to attach to the message (max 4KB)
-    # @return [Sendly::Message] The sent message
+    # @param media_urls [Array<String>] Media URLs to attach (WhatsApp accepts exactly one)
+    # @param channel [String] Message channel: omit (or "sms") for SMS,
+    #   "whatsapp" for WhatsApp, "rcs" for RCS
+    # @param template [Hash] WhatsApp only: approved template to send, with
+    #   :name, :language, and optional :variables ({ "1" => "Acme" }) and
+    #   :buttons ([{ index: 0, variables: { "1" => "4821" } }]). Works
+    #   regardless of the 24-hour window.
+    # @param agent_id [String] RCS only: the agent to send from. Optional
+    #   when your workspace has exactly one sendable agent; required (the
+    #   API responds 400 +rcs_agent_ambiguous+) when it has more.
+    # @param card [Hash] RCS only: a rich card, with :title, :description,
+    #   and optional :mediaUrl (a public JPEG, PNG, or GIF), :orientation
+    #   ("vertical" or "horizontal"), and :suggestions. Passed through
+    #   verbatim, so use the camelCase keys shown. Cards have no SMS form
+    #   and only deliver to RCS-capable recipients.
+    # @param suggestions [Array<Hash>] RCS only, alongside +text+: suggested
+    #   replies and actions, each either
+    #   { reply: { text: ..., postbackData: ... } } or
+    #   { action: { text: ..., postbackData: ..., url: ... } }. Passed
+    #   through verbatim, so use the camelCase keys shown. Suggestions have
+    #   no SMS form and are dropped on a fallback.
+    # @param fallback_to_sms [Boolean] RCS only: deliver +text+ as plain SMS
+    #   when the recipient can't receive RCS (default true). Pass false to
+    #   fail with 422 +rcs_not_supported_for_recipient+ instead.
+    # @param idempotency_key [String] Idempotency key for this operation
+    #   (1-255 printable ASCII characters). The SDK already generates a key
+    #   per logical request automatically, so the server can dedupe the
+    #   SDK's own retries. Supply your own key when you need idempotency
+    #   across process restarts or your own retry loops — repeating a
+    #   request with the same key within 24 hours returns the original
+    #   response instead of executing again.
+    # @return [Sendly::Message, Sendly::WhatsAppMessage, Sendly::RcsMessage] The sent message
     #
     # @raise [Sendly::ValidationError] If parameters are invalid
     # @raise [Sendly::InsufficientCreditsError] If account has no credits
@@ -37,8 +89,93 @@ module Sendly
     #     text: "Your verification code is 123456",
     #     message_type: "transactional"
     #   )
-    def send(to:, text:, from: nil, message_type: nil, metadata: nil, media_urls: nil)
+    #
+    # @example WhatsApp free-form reply inside an open 24h window
+    #   message = client.messages.send(
+    #     channel: "whatsapp",
+    #     to: "+15551234567",
+    #     from: "+15559876543",
+    #     text: "Your table is ready!"
+    #   )
+    #
+    # @example WhatsApp template send — works regardless of the window
+    #   message = client.messages.send(
+    #     channel: "whatsapp",
+    #     to: "+15551234567",
+    #     from: "+15559876543",
+    #     template: {
+    #       name: "order_shipped",
+    #       language: "en_US",
+    #       variables: { "1" => "Acme Inc", "2" => "#4821" }
+    #     }
+    #   )
+    #   puts message.whatsapp.kind   # "template"
+    #   puts message.credits_used    # priced by country + category
+    #
+    # @example RCS text with suggested replies and actions
+    #   message = client.messages.send(
+    #     channel: "rcs",
+    #     to: "+15551234567",
+    #     text: "Your order has shipped! Want live updates?",
+    #     suggestions: [
+    #       { reply: { text: "Yes, notify me", postbackData: "notify_yes" } },
+    #       { action: { text: "Track order", postbackData: "track",
+    #                   url: "https://acme.example/orders/4821" } }
+    #     ]
+    #   )
+    #   puts message.channel      # "rcs", or "sms" when it fell back
+    #   puts message.fell_back?   # true when delivered as plain SMS
+    #
+    # @example RCS rich card (RCS-capable recipients only)
+    #   client.messages.send(
+    #     channel: "rcs",
+    #     to: "+15551234567",
+    #     card: {
+    #       title: "Spring collection",
+    #       description: "New arrivals are in - take a look.",
+    #       mediaUrl: "https://example.com/spring.jpg",
+    #       orientation: "vertical"
+    #     }
+    #   )
+    def send(to:, text: nil, from: nil, message_type: nil, metadata: nil, media_urls: nil,
+             channel: nil, template: nil, agent_id: nil, card: nil, suggestions: nil,
+             fallback_to_sms: nil, idempotency_key: nil)
       validate_phone!(to)
+
+      if channel.to_s == "rcs"
+        has_text = !(text.nil? || text.to_s.empty?)
+        has_card = !card.nil?
+        raise ValidationError, "Provide exactly one of 'text' or 'card'" if has_text == has_card
+
+        body = { channel: "rcs", to: to }
+        body[:agentId] = agent_id if agent_id
+        body[:text] = text if has_text
+        body[:card] = card if has_card
+        body[:suggestions] = suggestions if suggestions
+        body[:fallbackToSms] = fallback_to_sms unless fallback_to_sms.nil?
+        body[:metadata] = metadata if metadata
+
+        response = client.post("/messages", body, idempotency_key: idempotency_key)
+        return RcsMessage.new(response)
+      end
+
+      if channel.to_s == "whatsapp"
+        validate_phone!(from)
+        has_media = media_urls.is_a?(Array) && !media_urls.empty?
+        if (text.nil? || text.empty?) && !has_media && template.nil?
+          raise ValidationError, "Provide 'text', 'media_urls', or 'template'"
+        end
+
+        body = { channel: "whatsapp", to: to, from: from }
+        body[:text] = text unless text.nil?
+        body[:mediaUrls] = media_urls if has_media
+        body[:template] = template if template
+        body[:metadata] = metadata if metadata
+
+        response = client.post("/messages", body, idempotency_key: idempotency_key)
+        return WhatsAppMessage.new(response)
+      end
+
       validate_text!(text)
 
       body = { to: to, text: text }
@@ -47,7 +184,7 @@ module Sendly
       body[:metadata] = metadata if metadata
       body[:mediaUrls] = media_urls if media_urls
 
-      response = client.post("/messages", body)
+      response = client.post("/messages", body, idempotency_key: idempotency_key)
       # API returns message directly at top level
       Message.new(response)
     end
@@ -65,6 +202,8 @@ module Sendly
     # @param from [String] Sender ID or phone number (optional)
     # @param media_urls [Array<String>] Media URLs to attach (required unless text is provided)
     # @param message_type [String] Message type: "transactional" (default) or "marketing"
+    # @param idempotency_key [String] Idempotency key for this operation
+    #   (1-255 printable ASCII characters, optional)
     # @return [Sendly::GroupMessage] The sent group message, including a group_message_id
     #
     # @raise [Sendly::ValidationError] If fewer than 2 / more than 8 recipients, or no body
@@ -77,7 +216,7 @@ module Sendly
     #   )
     #   puts group.id
     #   puts group.group_message_id
-    def send_group(to:, text: nil, from: nil, media_urls: nil, message_type: nil)
+    def send_group(to:, text: nil, from: nil, media_urls: nil, message_type: nil, idempotency_key: nil)
       unless to.is_a?(Array) && to.length >= 2
         raise ValidationError, "Group messaging requires at least 2 recipients in 'to'"
       end
@@ -94,7 +233,7 @@ module Sendly
       body[:mediaUrls] = media_urls if has_media
       body[:messageType] = message_type if message_type
 
-      response = client.post("/messages/group", body)
+      response = client.post("/messages/group", body, idempotency_key: idempotency_key)
       GroupMessage.new(response)
     end
 
@@ -218,6 +357,8 @@ module Sendly
     # @param from [String] Sender ID or phone number (optional)
     # @param message_type [String] Message type: "marketing" (default) or "transactional"
     # @param metadata [Hash] Custom JSON metadata to attach to the message (max 4KB)
+    # @param idempotency_key [String] Idempotency key for this operation
+    #   (1-255 printable ASCII characters, optional)
     # @return [Hash] The scheduled message
     #
     # @raise [Sendly::ValidationError] If parameters are invalid
@@ -229,7 +370,7 @@ module Sendly
     #     scheduled_at: "2025-01-20T10:00:00Z"
     #   )
     #   puts scheduled["id"]
-    def schedule(to:, text:, scheduled_at:, from: nil, message_type: nil, metadata: nil)
+    def schedule(to:, text:, scheduled_at:, from: nil, message_type: nil, metadata: nil, idempotency_key: nil)
       validate_phone!(to)
       validate_text!(text)
       raise ValidationError, "scheduled_at is required" if scheduled_at.nil? || scheduled_at.empty?
@@ -239,7 +380,7 @@ module Sendly
       body[:messageType] = message_type if message_type
       body[:metadata] = metadata if metadata
 
-      client.post("/messages/schedule", body)
+      client.post("/messages/schedule", body, idempotency_key: idempotency_key)
     end
 
     # List scheduled messages
@@ -303,6 +444,8 @@ module Sendly
     # @param from [String] Sender ID or phone number (optional, applies to all)
     # @param message_type [String] Message type: "marketing" (default) or "transactional"
     # @param metadata [Hash] Shared metadata for all messages (max 4KB). Each message can also have its own metadata hash which takes priority.
+    # @param idempotency_key [String] Idempotency key for this operation
+    #   (1-255 printable ASCII characters, optional)
     # @return [Hash] Batch response with batch_id and status
     #
     # @raise [Sendly::ValidationError] If parameters are invalid
@@ -316,7 +459,7 @@ module Sendly
     #     ]
     #   )
     #   puts "Batch #{result['batchId']}: #{result['queued']} queued"
-    def send_batch(messages:, from: nil, message_type: nil, metadata: nil)
+    def send_batch(messages:, from: nil, message_type: nil, metadata: nil, idempotency_key: nil)
       raise ValidationError, "Messages array is required" if messages.nil? || messages.empty?
 
       messages.each_with_index do |msg, i|
@@ -334,7 +477,11 @@ module Sendly
       body[:messageType] = message_type if message_type
       body[:metadata] = metadata if metadata
 
-      client.post("/messages/batch", body)
+      # The batch endpoint dedupes header-less retries server-side by hashing
+      # the request content; an auto-generated key would bypass that net for
+      # identical cross-process re-runs, so only caller-supplied keys are sent.
+      client.post("/messages/batch", body, idempotency_key: idempotency_key,
+                                           auto_idempotency_key: false)
     end
 
     # Get batch status by ID

data/lib/sendly/rcs_resource.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Sendly
+  # An RCS agent registered for your workspace — the branded identity your
+  # RCS messages come from. +status+ moves +"draft"+ → +"submitted"+ →
+  # +"testing"+ (can send, but only to invited test devices) → +"approved"+
+  # (can send to everyone); +"suspended"+ agents cannot send. +sendable+ is
+  # true when the agent is fully provisioned and its status allows sending.
+  class RcsAgent
+    attr_reader :id, :name, :status, :use_case, :sendable, :created_at
+
+    STATUSES = %w[draft submitted testing approved suspended].freeze
+
+    def initialize(data)
+      @id = data["id"]
+      @name = data["name"]
+      @status = data["status"]
+      @use_case = data["useCase"] || data["use_case"]
+      @sendable = data["sendable"] || false
+      @created_at = data["createdAt"] || data["created_at"]
+    end
+
+    def sendable?
+      sendable
+    end
+
+    def approved?
+      status == "approved"
+    end
+
+    def to_h
+      {
+        id: id, name: name, status: status, use_case: use_case,
+        sendable: sendable, created_at: created_at
+      }.compact
+    end
+  end
+
+  # Whether a recipient's device and network can receive RCS. When
+  # +capable+ is false, a text send to this recipient falls back to plain
+  # SMS (unless the fallback is disabled) and a card send fails. +features+
+  # lists the feature tags the device reports.
+  class RcsCapability
+    attr_reader :to, :agent_id, :capable, :features
+
+    def initialize(data)
+      @to = data["to"]
+      @agent_id = data["agentId"] || data["agent_id"]
+      @capable = data["capable"] || false
+      @features = data["features"] || []
+    end
+
+    def capable?
+      capable
+    end
+
+    def to_h
+      { to: to, agent_id: agent_id, capable: capable, features: features }.compact
+    end
+  end
+
+  # RCS-specific details on a sent message. On a native RCS delivery +kind+
+  # is what was sent ("text" or "card") and +agent_name+ is the brand name
+  # recipients see. On an SMS fallback +requested_channel+ is "rcs" and
+  # +suggestions_dropped+ is true when suggested replies/actions were
+  # dropped (they have no SMS form).
+  class RcsMessageDetails
+    attr_reader :kind, :agent_id, :agent_name, :requested_channel,
+                :suggestions_dropped
+
+    KINDS = %w[text card].freeze
+
+    def initialize(data)
+      @kind = data["kind"]
+      @agent_id = data["agentId"] || data["agent_id"]
+      @agent_name = data["agentName"] || data["agent_name"]
+      @requested_channel = data["requestedChannel"] || data["requested_channel"]
+      @suggestions_dropped = data["suggestionsDropped"] || data["suggestions_dropped"] || false
+    end
+
+    def to_h
+      {
+        kind: kind, agent_id: agent_id, agent_name: agent_name,
+        requested_channel: requested_channel,
+        suggestions_dropped: suggestions_dropped
+      }.compact
+    end
+  end
+
+  # A message sent through the RCS channel. +channel+ is "rcs" when it was
+  # delivered as RCS, or "sms" when the recipient couldn't receive RCS and
+  # the message fell back to plain SMS — check with {#fell_back?}. On a
+  # fallback +fell_back_to+ is "sms" and +segments+/+credits_used+ are
+  # billed as SMS; +rcs+ carries the channel-specific details either way.
+  class RcsMessage
+    attr_reader :id, :channel, :fell_back_to, :message_format, :to, :from,
+                :text, :status, :segments, :credits_used, :rcs, :created_at,
+                :metadata
+
+    def initialize(data)
+      @id = data["id"]
+      @channel = data["channel"] || "rcs"
+      @fell_back_to = data["fellBackTo"] || data["fell_back_to"]
+      @message_format = data["message_format"] || data["messageFormat"] || @channel
+      @to = data["to"]
+      @from = data["from"]
+      @text = data["text"]
+      @status = data["status"]
+      @segments = data["segments"] || 1
+      @credits_used = data["creditsUsed"] || data["credits_used"] || 0
+      @rcs = data["rcs"] ? RcsMessageDetails.new(data["rcs"]) : nil
+      @created_at = data["createdAt"] || data["created_at"]
+      @metadata = data["metadata"]
+    end
+
+    def fell_back?
+      fell_back_to == "sms"
+    end
+
+    def delivered?
+      status == "delivered"
+    end
+
+    def failed?
+      status == "failed"
+    end
+
+    def to_h
+      {
+        id: id, channel: channel, fell_back_to: fell_back_to,
+        message_format: message_format, to: to, from: from, text: text,
+        status: status, segments: segments, credits_used: credits_used,
+        rcs: rcs&.to_h, created_at: created_at, metadata: metadata
+      }.compact
+    end
+  end
+
+  # List the RCS agents registered for your workspace.
+  class RcsAgentsResource
+    def initialize(client)
+      @client = client
+    end
+
+    # List your RCS agents, newest first. An empty list means no agent is
+    # set up yet — contact support to register an RCS agent for your brand.
+    #
+    # @return [Hash] +{ agents: Array<RcsAgent> }+
+    #
+    # @example
+    #   client.rcs.agents.list[:agents].each do |a|
+    #     puts "#{a.name} — #{a.status}#{a.sendable? ? ' (sendable)' : ''}"
+    #   end
+    def list
+      response = @client.get("/rcs/agents")
+      agents = (response["agents"] || []).map { |a| RcsAgent.new(a) }
+      { agents: agents }
+    end
+  end
+
+  # RCS resource — discover your RCS agents and pre-flight recipient
+  # capability.
+  #
+  # RCS is a first-class Sendly channel: send branded rich messages — text
+  # with suggested replies and actions, or rich cards — via
+  # +client.messages.send(channel: "rcs", ...)+. RCS agents are registered
+  # by Sendly for your brand; contact support to set one up, then discover
+  # it with {RcsAgentsResource#list}.
+  #
+  # Delivery is per-recipient: not every device or network supports RCS.
+  # Text messages fall back to plain SMS automatically (billed as SMS)
+  # unless you pass +fallback_to_sms: false+; rich cards have no SMS form
+  # and only deliver to RCS-capable recipients. Use {#capability} to check
+  # a recipient before sending.
+  #
+  # RCS sends and capability checks require a live API key
+  # (+sk_live_v1_xxx+).
+  #
+  # @example Check capability, then send
+  #   cap = client.rcs.capability(to: "+15551234567")
+  #   if cap.capable?
+  #     client.messages.send(
+  #       channel: "rcs",
+  #       to: "+15551234567",
+  #       text: "Your order has shipped!"
+  #     )
+  #   end
+  class RcsResource
+    # @return [RcsAgentsResource] List registered agents
+    attr_reader :agents
+
+    def initialize(client)
+      @client = client
+      @agents = RcsAgentsResource.new(client)
+    end
+
+    # Check whether a recipient can receive RCS.
+    #
+    # Probes the recipient's device and network. When the recipient is not
+    # capable, a text send falls back to plain SMS (unless the fallback is
+    # disabled) and a card send fails with
+    # +rcs_not_supported_for_recipient+.
+    #
+    # @param to [String] The recipient's number, in E.164 format
+    # @param agent_id [String, nil] The agent to probe with. Optional when
+    #   your workspace has exactly one sendable agent; required (the API
+    #   responds 400 +rcs_agent_ambiguous+) when it has more.
+    # @return [RcsCapability]
+    #
+    # @example
+    #   cap = client.rcs.capability(to: "+15551234567")
+    #   puts cap.capable?
+    #   puts cap.features.inspect
+    def capability(to:, agent_id: nil)
+      raise ValidationError, "to is required" if to.nil? || to.to_s.empty?
+
+      params = { to: to }
+      params[:agentId] = agent_id if agent_id
+      response = @client.get("/rcs/capability", params)
+      RcsCapability.new(response)
+    end
+  end
+end