sendly 3.38.0 → 3.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76b3722f8971a04363ce5a5ea47d61eba59db05698652f21cd5ab347c24c74c1
-  data.tar.gz: 478881a38dac65c6f9696d0de53114fadc10651152304542519616794ed64bfe
+  metadata.gz: c474ade97511ceecadbff15268b602edb67953395417996e9c1ac8b7626e68ff
+  data.tar.gz: b034a8b316eab9f85e98de49e31db3045326662beeefbafb306844302a147037
 SHA512:
-  metadata.gz: db802e6f2ac77bd0978de8a043b8a34488168e820e8b2e6ad3aca7033f43377b1524ccdee742077471486013d6f6e8607465b1fbaf68038dfb8d37d3f119915c
-  data.tar.gz: 33103fdeb0adf5816c3ffcdc23c4107eb52cc814ed904ae2b9d64f314d8fb88bbf2f0e837c0d4bd66781903710c7ffab770da166e5372eebe79d8522c3ace7d8
+  metadata.gz: 10f0a1eecb587b5c0b801c1abb5366d41caaa4fecf7e274ac3a37860d82bbdf92ca644280a419626391d0fce53679c35172a66aca3f26893d780bb499321c15c
+  data.tar.gz: 0221a6cfd5de361ff4648b4b4e0256ceccf4bab50e3b44b2616cd2200c136c2acd27409c3b20a99f2f81176663e0e272664a07d07f113d29d2b2064a0546bd33

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # sendly (Ruby)
 
+## Unreleased
+
+### Minor Changes
+
+- **`Sendly::ValidationError#field_errors` is now populated.** It was always `nil` before, because the API path never passed it. It now carries the response body's `errors` array on any 400 or 422, on every resource rather than just RCS: `client.contacts.import` already returns one, for example. Each entry is a Hash. Code that treats a truthy `field_errors` as "this only happens for X" should be rechecked.
+
+
+- **RCS agent registration is self-serve from the SDK.** `client.rcs` gains `registration.get`, `dossier.get`, `brands.create` / `brands.update`, and `agents.create` / `get` / `update` / `set_test_devices` / `submit` / `request_launch`, mirroring the dashboard: draft the brand and agent, submit them for Sendly's review, invite test devices once the agent is in testing, then request launch. Reads need the `rcs:read` scope and writes `rcs:write`; test and live keys both work. Nested hashes (address, contact, basics, campaign, testing) accept snake_case or camelCase keys. Logo, hero and call-to-action media must be public `https://` URLs; assets cannot be uploaded over the API. New models: `Sendly::RcsRegistration` (with `CUSTOMER_STAGES`, `REVIEW_STATUSES` and `ERROR_CODES`), `Sendly::RcsDossier`, `Sendly::RcsBrand`, `Sendly::RcsAddress`, `Sendly::RcsContact`, `Sendly::RcsAgentRegistration`, `Sendly::RcsAgentBasics`, `Sendly::RcsAgentCampaign`, `Sendly::RcsCampaignInteraction`, `Sendly::RcsConsentSettings`, `Sendly::RcsOptInMethod`, `Sendly::RcsAgentTesting` and `Sendly::RcsTestDevice`. `Sendly::RcsAgent` (from `agents.list`) gains `stage`. Every route stays behind the RCS rollout: while it is off for your account these calls raise `Sendly::NotFoundError` with `rcs_not_enabled`.
+
+  ```ruby
+  dossier = client.rcs.dossier.get
+  brand = client.rcs.brands.create(**dossier.brand)
+  agent = client.rcs.agents.create(brand_id: brand.id, display_name: "Acme Coffee",
+                                   use_case: "MULTI_USE",
+                                   basics: { logo_url: "https://acme.example/rcs/logo.png" })
+  client.rcs.agents.submit(agent.id, idempotency_key: "rcs-submit-#{agent.id}")
+  ```
+
+- **`client.patch` and `client.put` accept `idempotency_key:`.** Neither generates a key on its own (unchanged), but a key you pass is now sent, so the RCS `update` and `set_test_devices` calls can be replayed safely.
+
+- **`Sendly::ValidationError#field_errors` carries the API's `errors` list** (`[{ "path", "message" }, ...]`) when a 400 or 422 response includes one, instead of always being `nil`. RCS registration uses it to say which brand, agent, campaign or device field needs attention.
+
 ## 3.38.0
 
 ### Minor Changes

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sendly (3.38.0)
+    sendly (3.39.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 

data/README.md

@@ -280,6 +280,32 @@ puts result.explanation  # what changed and why
 puts result.model        # model used (when available)
 ```
 
+## Idempotency
+
+Every POST carries an automatically generated `Idempotency-Key` header, held
+across the client's own rate-limit retries, so a retry of a request that
+already reached the API returns the original result instead of sending and
+charging again. Pass your own key (1-255 printable ASCII characters) when the
+guarantee needs to outlive the process, such as a job queue that re-runs after
+a crash or your own retry loop; `idempotency_key:` is accepted on
+`messages.send`, `send_group`, `schedule`, and `send_batch`.
+
+```ruby
+message = client.messages.send(
+  to: "+15551234567",
+  text: "Your order has shipped!",
+  idempotency_key: "order-4821-shipped"
+)
+```
+
+Repeating a request with the same key within 24 hours returns the original
+response; `send_batch` sends no automatic key, because the API already
+deduplicates identical batches by their contents. Note this client raises
+`Sendly::TimeoutError` instead of retrying a timeout, so a timeout is exactly
+when to retry with your own key.
+
+Full details: https://sendly.live/docs/idempotency
+
 ## Webhooks
 
 ```ruby
@@ -846,9 +872,108 @@ recipients.
 
 The RCS channel is being rolled out gradually and is not yet generally
 available; until it is enabled for your account the endpoints read as
-absent and calls raise `Sendly::NotFoundError` (HTTP 404). RCS sends and
-capability checks require a live API key. RCS agents are registered by
-Sendly for your brand — contact support to set one up.
+absent and calls raise `Sendly::NotFoundError` (HTTP 404: `not_found` on
+sends and listing, `rcs_not_enabled` on registration). RCS sends and
+capability checks require a live API key.
+
+### Registering an agent
+
+Registration is self-serve, from the dashboard or the API. Draft the
+brand (the business) and the agent (what recipients see), submit them for
+Sendly's review, and once approved they go on to the carrier network for
+brand verification and agent review. The agent then reaches invited test
+devices only; when you have tested it, request launch and Sendly reviews
+the campaign before sending the launch on to the carrier network. Watch
+`customer_stage` (one of `Sendly::RcsRegistration::CUSTOMER_STAGES`) to
+see where a registration is.
+
+Registration reads need the `rcs:read` scope and writes `rcs:write`; test
+and live keys both work, since drafting is not carrier-backed. Logo, hero
+and call-to-action media must be public `https://` URLs: assets cannot be
+uploaded over the API, only from the dashboard. Nested hashes (address,
+contact, basics, campaign, testing) accept snake_case or camelCase keys.
+Every write accepts `idempotency_key:`; `POST`s get an auto-generated key
+as usual, while `PATCH` and `PUT` send one only when you pass it.
+
+```ruby
+# Where is the registration at?
+reg = client.rcs.registration.get
+puts reg.stage  # "draft" until something is submitted
+
+# Seed the brand from details Sendly already holds (your 10DLC brand or
+# toll-free verification), then fill in the rest
+dossier = client.rcs.dossier.get
+brand = client.rcs.brands.create(**dossier.brand)  # dossier.source: "tendlc", "verification" or "none"
+client.rcs.brands.update(brand.id,
+  display_name: "Acme Coffee",
+  legal_entity_type: "LIMITED_LIABILITY_COMPANY",
+  contact: { first_name: "Sam", last_name: "Lee", email: "sam@acme.example",
+             phone_number: "+15551234567" }
+)
+
+# Draft the agent. Media must be public https URLs.
+agent = client.rcs.agents.create(
+  brand_id: brand.id,
+  display_name: "Acme Coffee",
+  use_case: "MULTI_USE",
+  basics: {
+    description: "Order updates and offers from Acme Coffee",
+    logo_url: "https://acme.example/rcs/logo.png",
+    hero_url: "https://acme.example/rcs/hero.png",
+    brand_color: "#5B3A29",
+    privacy_policy_url: "https://acme.example/privacy",
+    terms_and_conditions_url: "https://acme.example/terms",
+    phone_number: { number: "+15551234567", label: "Support" }
+  }
+)
+
+# Submit for Sendly's review. Pass your own key if you may retry: a replay
+# returns the original response without submitting again.
+agent = client.rcs.agents.submit(agent.id, idempotency_key: "rcs-submit-#{agent.id}")
+puts agent.review_status  # "awaiting_review"
+
+# Later: poll, and act on a review note
+agent = client.rcs.agents.get(agent.id)
+if agent.changes_requested?
+  puts agent.review_note
+  client.rcs.agents.update(agent.id, basics: { hero_url: "https://acme.example/rcs/hero-v2.png" })
+end
+
+# Once the agent is in testing, invite devices, describe the campaign,
+# then request launch
+client.rcs.agents.set_test_devices(agent.id, devices: [
+  { phone_number: "+15557654321", label: "Sam's Pixel" }
+])
+client.rcs.agents.update(agent.id,
+  campaign: {
+    company_overview: "Specialty coffee roaster with three cafes in Austin",
+    agent_overview: "Order updates, pickup alerts and support replies",
+    interactions: [{ interaction_type: "TRANSACTIONAL_UPDATES",
+                     description: "Order and pickup status" }],
+    message_examples: ["Your order #4821 has shipped!",
+                       "Your latte is ready for pickup at 5th St",
+                       "Reply HELP for support or STOP to opt out"],
+    consent_settings: {
+      opt_in_methods: [{ method_type: "WEBSITE", description: "Checkbox at checkout" }],
+      call_to_action: "Get order updates by RCS",
+      call_to_action_url: "https://acme.example/updates",
+      double_opt_in: false,
+      help_response: "Acme Coffee: reply STOP to opt out, or email help@acme.example",
+      opt_out_response: "You're opted out of Acme Coffee updates."
+    }
+  }
+)
+client.rcs.agents.request_launch(agent.id, test_url: "https://acme.example/rcs-test")
+```
+
+Registration errors map onto the usual classes: `Sendly::NotFoundError`
+for `rcs_not_enabled` and `rcs_not_found`; `Sendly::ValidationError` for
+`rcs_us_only` and `rcs_invalid_content`, whose `field_errors` is the API's
+list of `{ "path", "message" }` hashes; and `Sendly::APIError` with
+`status_code` 409 for `rcs_field_locked`, `rcs_brand_not_verified` and
+`rcs_launch_not_ready`, or 403 for a key missing the scope.
+
+### Sending
 
 ```ruby
 # Discover your RCS agents ("testing" reaches invited test devices only;

data/lib/sendly/client.rb

@@ -222,20 +222,28 @@ module Sendly
 
     # Make a PATCH request
     #
+    # No Idempotency-Key is generated for a PATCH; pass +idempotency_key+
+    # to send one (1-255 printable ASCII characters).
+    #
     # @param path [String] API path
     # @param body [Hash] Request body
+    # @param idempotency_key [String, nil] Caller-supplied idempotency key (optional)
     # @return [Hash] Response body
-    def patch(path, body = {})
-      request(:patch, path, body: body)
+    def patch(path, body = {}, idempotency_key: nil)
+      request(:patch, path, body: body, idempotency_key: idempotency_key)
     end
 
     # Make a PUT request
     #
+    # No Idempotency-Key is generated for a PUT; pass +idempotency_key+
+    # to send one (1-255 printable ASCII characters).
+    #
     # @param path [String] API path
     # @param body [Hash] Request body
+    # @param idempotency_key [String, nil] Caller-supplied idempotency key (optional)
     # @return [Hash] Response body
-    def put(path, body = {})
-      request(:put, path, body: body)
+    def put(path, body = {}, idempotency_key: nil)
+      request(:put, path, body: body, idempotency_key: idempotency_key)
     end
 
     # Make a DELETE request

data/lib/sendly/errors.rb

@@ -47,7 +47,9 @@ module Sendly
 
   # Raised when the request contains invalid parameters
   class ValidationError < Error
-    # @return [Hash, nil] Field-specific validation errors
+    # @return [Array<Hash>, Hash, nil] Field-specific validation errors. For
+    #   API responses this is the +errors+ list from the body when present,
+    #   e.g. +[{ "path" => "brand.ein", "message" => "Enter a 9-digit EIN" }]+
     attr_reader :field_errors
 
     def initialize(message = "Validation failed", field_errors: nil, details: nil)
@@ -101,7 +103,7 @@ module Sendly
 
       case status
       when 400, 422
-        ValidationError.new(message, details: details)
+        ValidationError.new(message, details: details, field_errors: body["errors"])
       when 401
         AuthenticationError.new(message)
       when 402

data/lib/sendly/rcs_resource.rb

@@ -6,8 +6,10 @@ module Sendly
   # +"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.
+  # +stage+ is the registration stage, one of
+  # {RcsRegistration::CUSTOMER_STAGES}.
   class RcsAgent
-    attr_reader :id, :name, :status, :use_case, :sendable, :created_at
+    attr_reader :id, :name, :status, :use_case, :sendable, :stage, :created_at
 
     STATUSES = %w[draft submitted testing approved suspended].freeze
 
@@ -17,6 +19,7 @@ module Sendly
       @status = data["status"]
       @use_case = data["useCase"] || data["use_case"]
       @sendable = data["sendable"] || false
+      @stage = data["stage"]
       @created_at = data["createdAt"] || data["created_at"]
     end
 
@@ -31,7 +34,7 @@ module Sendly
     def to_h
       {
         id: id, name: name, status: status, use_case: use_case,
-        sendable: sendable, created_at: created_at
+        sendable: sendable, stage: stage, created_at: created_at
       }.compact
     end
   end
@@ -135,14 +138,703 @@ module Sendly
     end
   end
 
-  # List the RCS agents registered for your workspace.
+  # Shapes RCS registration input before it leaves the process. Nested
+  # hashes (address, contact, basics, campaign, testing, devices) accept
+  # either snake_case or camelCase keys; keys are camelised and values are
+  # passed through untouched.
+  #
+  # @api private
+  module RcsRegistrationInput
+    OMIT = Object.new.freeze
+
+    module_function
+
+    def omitted?(value)
+      OMIT.equal?(value)
+    end
+
+    def camelize(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), out| out[camel_key(k)] = camelize(v) }
+      when Array
+        value.map { |v| camelize(v) }
+      else
+        value
+      end
+    end
+
+    def underscore(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), out| out[snake_key(k)] = underscore(v) }
+      when Array
+        value.map { |v| underscore(v) }
+      else
+        value
+      end
+    end
+
+    def camel_key(key)
+      key.to_s.gsub(/_([a-z0-9])/) { Regexp.last_match(1).upcase }.to_sym
+    end
+
+    def snake_key(key)
+      key.to_s.gsub(/([A-Z])/) { "_#{Regexp.last_match(1).downcase}" }.to_sym
+    end
+
+    def encode_id!(id, label)
+      raise ValidationError, "#{label} is required" if id.nil? || id.to_s.empty?
+
+      URI.encode_www_form_component(id)
+    end
+  end
+
+  # A postal address on an RCS brand. +country_code+ is always "US": RCS
+  # registration is open to US businesses for now.
+  class RcsAddress
+    attr_reader :line1, :line2, :city, :state, :postal_code, :country_code
+
+    def initialize(data)
+      data ||= {}
+      @line1 = data["line1"]
+      @line2 = data["line2"]
+      @city = data["city"]
+      @state = data["state"]
+      @postal_code = data["postalCode"] || data["postal_code"]
+      @country_code = data["countryCode"] || data["country_code"]
+    end
+
+    def to_h
+      {
+        line1: line1, line2: line2, city: city, state: state,
+        postal_code: postal_code, country_code: country_code
+      }.compact
+    end
+  end
+
+  # The business contact on an RCS brand.
+  class RcsContact
+    attr_reader :first_name, :last_name, :title, :email, :phone_number
+
+    def initialize(data)
+      data ||= {}
+      @first_name = data["firstName"] || data["first_name"]
+      @last_name = data["lastName"] || data["last_name"]
+      @title = data["title"]
+      @email = data["email"]
+      @phone_number = data["phoneNumber"] || data["phone_number"]
+    end
+
+    def to_h
+      {
+        first_name: first_name, last_name: last_name, title: title,
+        email: email, phone_number: phone_number
+      }.compact
+    end
+  end
+
+  # The business behind an RCS agent. +review_status+ starts +"draft"+,
+  # becomes +"awaiting_review"+ once an agent under it is submitted, and
+  # moves to +"approved_for_carrier"+ (Sendly approved it and sent it on to
+  # the carrier network), +"changes_requested"+ (see +review_note+) or
+  # +"rejected"+ (see +rejection_reason+). +verified_at+ is set once the
+  # carrier network has verified the business. +customer_stage+ is the
+  # same lifecycle summarised as one of {RcsRegistration::CUSTOMER_STAGES}.
+  class RcsBrand
+    LEGAL_ENTITY_TYPES = %w[LIMITED_LIABILITY_COMPANY SOLE_PROPRIETORSHIP PARTNERSHIP
+                            CORPORATION S_CORPORATION].freeze
+    ORGANIZATION_TYPES = %w[PRIVATE_PROFIT PUBLIC_PROFIT NON_PROFIT GOVERNMENT UNKNOWN].freeze
+
+    attr_reader :id, :review_status, :customer_stage, :display_name,
+                :legal_name, :legal_entity_type, :organization_type,
+                :stock_symbol, :website_url, :ein, :address, :contact,
+                :review_note, :rejection_reason, :submitted_for_review_at,
+                :sent_to_carrier_at, :verified_at, :created_at, :updated_at
+
+    def initialize(data)
+      @id = data["id"]
+      @review_status = data["reviewStatus"] || data["review_status"]
+      @customer_stage = data["customerStage"] || data["customer_stage"]
+      @display_name = data["displayName"] || data["display_name"]
+      @legal_name = data["legalName"] || data["legal_name"]
+      @legal_entity_type = data["legalEntityType"] || data["legal_entity_type"]
+      @organization_type = data["organizationType"] || data["organization_type"]
+      @stock_symbol = data["stockSymbol"] || data["stock_symbol"]
+      @website_url = data["websiteUrl"] || data["website_url"]
+      @ein = data["ein"]
+      @address = data["address"] ? RcsAddress.new(data["address"]) : nil
+      @contact = data["contact"] ? RcsContact.new(data["contact"]) : nil
+      @review_note = data["reviewNote"] || data["review_note"]
+      @rejection_reason = data["rejectionReason"] || data["rejection_reason"]
+      @submitted_for_review_at = data["submittedForReviewAt"] || data["submitted_for_review_at"]
+      @sent_to_carrier_at = data["sentToCarrierAt"] || data["sent_to_carrier_at"]
+      @verified_at = data["verifiedAt"] || data["verified_at"]
+      @created_at = data["createdAt"] || data["created_at"]
+      @updated_at = data["updatedAt"] || data["updated_at"]
+    end
+
+    def draft?
+      review_status == "draft"
+    end
+
+    def awaiting_review?
+      review_status == "awaiting_review"
+    end
+
+    def changes_requested?
+      review_status == "changes_requested"
+    end
+
+    def rejected?
+      review_status == "rejected"
+    end
+
+    def verified?
+      !verified_at.nil?
+    end
+
+    # True while the brand can still be edited (draft or changes requested).
+    def editable?
+      draft? || changes_requested?
+    end
+
+    def to_h
+      {
+        id: id, review_status: review_status, customer_stage: customer_stage,
+        display_name: display_name, legal_name: legal_name,
+        legal_entity_type: legal_entity_type, organization_type: organization_type,
+        stock_symbol: stock_symbol, website_url: website_url, ein: ein,
+        address: address&.to_h, contact: contact&.to_h,
+        review_note: review_note, rejection_reason: rejection_reason,
+        submitted_for_review_at: submitted_for_review_at,
+        sent_to_carrier_at: sent_to_carrier_at, verified_at: verified_at,
+        created_at: created_at, updated_at: updated_at
+      }.compact
+    end
+  end
+
+  # A phone that can receive an agent's messages while it is in testing.
+  # +invite_status+ is nil until the carrier network has been asked to
+  # invite the device.
+  class RcsTestDevice
+    attr_reader :id, :phone_number, :label, :invite_status, :created_at
+
+    def initialize(data)
+      @id = data["id"]
+      @phone_number = data["phoneNumber"] || data["phone_number"]
+      @label = data["label"]
+      @invite_status = data["inviteStatus"] || data["invite_status"]
+      @created_at = data["createdAt"] || data["created_at"]
+    end
+
+    def invited?
+      !invite_status.nil?
+    end
+
+    def to_h
+      {
+        id: id, phone_number: phone_number, label: label,
+        invite_status: invite_status, created_at: created_at
+      }.compact
+    end
+  end
+
+  # What recipients see of an agent: name, use case, description, logo and
+  # hero images, colour, policy links and contact entries. +phone_number+,
+  # +website+ and +email+ are hashes as stored (+"number"+ / +"url"+ /
+  # +"address"+ plus +"label"+). +logo_url+ and +hero_url+ must be public
+  # https URLs; assets cannot be uploaded over the API.
+  class RcsAgentBasics
+    attr_reader :display_name, :use_case, :hosting_region, :description,
+                :logo_url, :hero_url, :brand_color, :privacy_policy_url,
+                :terms_and_conditions_url, :phone_number, :website, :email
+
+    def initialize(data)
+      data ||= {}
+      @display_name = data["displayName"] || data["display_name"]
+      @use_case = data["useCase"] || data["use_case"]
+      @hosting_region = data["hostingRegion"] || data["hosting_region"]
+      @description = data["description"]
+      @logo_url = data["logoUrl"] || data["logo_url"]
+      @hero_url = data["heroUrl"] || data["hero_url"]
+      @brand_color = data["brandColor"] || data["brand_color"]
+      @privacy_policy_url = data["privacyPolicyUrl"] || data["privacy_policy_url"]
+      @terms_and_conditions_url = data["termsAndConditionsUrl"] || data["terms_and_conditions_url"]
+      @phone_number = data["phoneNumber"] || data["phone_number"]
+      @website = data["website"]
+      @email = data["email"]
+    end
+
+    def to_h
+      {
+        display_name: display_name, use_case: use_case,
+        hosting_region: hosting_region, description: description,
+        logo_url: logo_url, hero_url: hero_url, brand_color: brand_color,
+        privacy_policy_url: privacy_policy_url,
+        terms_and_conditions_url: terms_and_conditions_url,
+        phone_number: phone_number, website: website, email: email
+      }.compact
+    end
+  end
+
+  # One kind of conversation the agent will have with recipients.
+  class RcsCampaignInteraction
+    INTERACTION_TYPES = %w[TRANSACTIONAL_UPDATES CUSTOMER_SUPPORT LOYALTY_OR_REWARD
+                           MARKETING_OR_PROMOTIONAL ACCOUNT_ALERTS TWO_WAY_CONVERSATION
+                           OTHER].freeze
+
+    attr_reader :interaction_type, :description
+
+    def initialize(data)
+      data ||= {}
+      @interaction_type = data["interactionType"] || data["interaction_type"]
+      @description = data["description"]
+    end
+
+    def to_h
+      { interaction_type: interaction_type, description: description }.compact
+    end
+  end
+
+  # One way recipients opt in to the agent's messages.
+  class RcsOptInMethod
+    METHOD_TYPES = %w[SMS WEBSITE MOBILE_APP QR_CODE SALE_POINT OTHER].freeze
+
+    attr_reader :method_type, :description
+
+    def initialize(data)
+      data ||= {}
+      @method_type = data["methodType"] || data["method_type"]
+      @description = data["description"]
+    end
+
+    def to_h
+      { method_type: method_type, description: description }.compact
+    end
+  end
+
+  # How recipients consent to, get help with, and stop the agent's
+  # messages. +call_to_action_media_url+ must be a public https URL.
+  class RcsConsentSettings
+    attr_reader :opt_in_methods, :call_to_action, :call_to_action_url,
+                :call_to_action_media_url, :double_opt_in,
+                :double_opt_in_message, :opt_in_message, :help_response,
+                :opt_out_response
+
+    def initialize(data)
+      data ||= {}
+      methods = data["optInMethods"] || data["opt_in_methods"]
+      @opt_in_methods = methods ? methods.map { |m| RcsOptInMethod.new(m) } : nil
+      @call_to_action = data["callToAction"] || data["call_to_action"]
+      @call_to_action_url = data["callToActionUrl"] || data["call_to_action_url"]
+      @call_to_action_media_url = data["callToActionMediaUrl"] || data["call_to_action_media_url"]
+      @double_opt_in = data.key?("doubleOptIn") ? data["doubleOptIn"] : data["double_opt_in"]
+      @double_opt_in_message = data["doubleOptInMessage"] || data["double_opt_in_message"]
+      @opt_in_message = data["optInMessage"] || data["opt_in_message"]
+      @help_response = data["helpResponse"] || data["help_response"]
+      @opt_out_response = data["optOutResponse"] || data["opt_out_response"]
+    end
+
+    def to_h
+      {
+        opt_in_methods: opt_in_methods&.map(&:to_h), call_to_action: call_to_action,
+        call_to_action_url: call_to_action_url,
+        call_to_action_media_url: call_to_action_media_url,
+        double_opt_in: double_opt_in, double_opt_in_message: double_opt_in_message,
+        opt_in_message: opt_in_message, help_response: help_response,
+        opt_out_response: opt_out_response
+      }.compact
+    end
+  end
+
+  # The agent's campaign: what the business does, what the agent sends,
+  # example messages and consent settings. Reviewed before launch.
+  class RcsAgentCampaign
+    attr_reader :company_overview, :agent_overview, :additional_information,
+                :interactions, :message_examples, :consent_settings
+
+    def initialize(data)
+      data ||= {}
+      @company_overview = data["companyOverview"] || data["company_overview"]
+      @agent_overview = data["agentOverview"] || data["agent_overview"]
+      @additional_information = data["additionalInformation"] || data["additional_information"]
+      interactions = data["interactions"]
+      @interactions = interactions ? interactions.map { |i| RcsCampaignInteraction.new(i) } : nil
+      @message_examples = data["messageExamples"] || data["message_examples"]
+      consent = data["consentSettings"] || data["consent_settings"]
+      @consent_settings = consent ? RcsConsentSettings.new(consent) : nil
+    end
+
+    def to_h
+      {
+        company_overview: company_overview, agent_overview: agent_overview,
+        additional_information: additional_information,
+        interactions: interactions&.map(&:to_h),
+        message_examples: message_examples,
+        consent_settings: consent_settings&.to_h
+      }.compact
+    end
+  end
+
+  # How the agent was tested on an invited device before launch.
+  class RcsAgentTesting
+    attr_reader :test_url, :message_id, :additional_information
+
+    def initialize(data)
+      data ||= {}
+      @test_url = data["testUrl"] || data["test_url"]
+      @message_id = data["messageId"] || data["message_id"]
+      @additional_information = data["additionalInformation"] || data["additional_information"]
+    end
+
+    def to_h
+      {
+        test_url: test_url, message_id: message_id,
+        additional_information: additional_information
+      }.compact
+    end
+  end
+
+  # The full registration record of an RCS agent: its basics, campaign,
+  # testing details, test devices and review state. +status+ is the send
+  # status also shown by {RcsAgentsResource#list} ("draft", "submitted",
+  # "testing", "approved", "suspended"); +review_status+ tracks the
+  # registration itself, one of {RcsRegistration::REVIEW_STATUSES}, and
+  # +customer_stage+ summarises both with the brand as one of
+  # {RcsRegistration::CUSTOMER_STAGES}. +review_note+ carries Sendly's
+  # note when changes are requested and +rejection_reason+ the carrier
+  # network's reason when it rejects the agent.
+  class RcsAgentRegistration
+    USE_CASES = %w[MULTI_USE PROMOTIONAL TRANSACTIONAL OTP].freeze
+
+    attr_reader :id, :brand_id, :status, :review_status, :customer_stage,
+                :display_name, :use_case, :hosting_region, :basics,
+                :campaign, :testing, :review_note, :rejection_reason,
+                :test_devices, :submitted_for_review_at,
+                :basics_submitted_at, :launch_submitted_at, :live_at,
+                :created_at, :updated_at
+
+    def initialize(data)
+      @id = data["id"]
+      @brand_id = data["brandId"] || data["brand_id"]
+      @status = data["status"]
+      @review_status = data["reviewStatus"] || data["review_status"]
+      @customer_stage = data["customerStage"] || data["customer_stage"]
+      @display_name = data["displayName"] || data["display_name"]
+      @use_case = data["useCase"] || data["use_case"]
+      @hosting_region = data["hostingRegion"] || data["hosting_region"]
+      @basics = data["basics"] ? RcsAgentBasics.new(data["basics"]) : nil
+      @campaign = data["campaign"] ? RcsAgentCampaign.new(data["campaign"]) : nil
+      @testing = data["testing"] ? RcsAgentTesting.new(data["testing"]) : nil
+      @review_note = data["reviewNote"] || data["review_note"]
+      @rejection_reason = data["rejectionReason"] || data["rejection_reason"]
+      devices = data["testDevices"] || data["test_devices"] || []
+      @test_devices = devices.map { |d| RcsTestDevice.new(d) }
+      @submitted_for_review_at = data["submittedForReviewAt"] || data["submitted_for_review_at"]
+      @basics_submitted_at = data["basicsSubmittedAt"] || data["basics_submitted_at"]
+      @launch_submitted_at = data["launchSubmittedAt"] || data["launch_submitted_at"]
+      @live_at = data["liveAt"] || data["live_at"]
+      @created_at = data["createdAt"] || data["created_at"]
+      @updated_at = data["updatedAt"] || data["updated_at"]
+    end
+
+    def draft?
+      review_status == "draft"
+    end
+
+    def awaiting_review?
+      review_status == "awaiting_review"
+    end
+
+    def changes_requested?
+      review_status == "changes_requested"
+    end
+
+    def approved_for_carrier?
+      review_status == "approved_for_carrier"
+    end
+
+    def launch_requested?
+      review_status == "launch_requested"
+    end
+
+    def launch_rejected?
+      review_status == "launch_rejected"
+    end
+
+    def rejected?
+      review_status == "rejected"
+    end
+
+    # True while the agent reaches invited test devices only.
+    def testing?
+      status == "testing"
+    end
+
+    def live?
+      customer_stage == "live"
+    end
+
+    # True while the agent's basics can still be edited and it can be
+    # submitted for review.
+    def editable?
+      draft? || changes_requested?
+    end
+
+    def to_h
+      {
+        id: id, brand_id: brand_id, status: status,
+        review_status: review_status, customer_stage: customer_stage,
+        display_name: display_name, use_case: use_case,
+        hosting_region: hosting_region, basics: basics&.to_h,
+        campaign: campaign&.to_h, testing: testing&.to_h,
+        review_note: review_note, rejection_reason: rejection_reason,
+        test_devices: test_devices.map(&:to_h),
+        submitted_for_review_at: submitted_for_review_at,
+        basics_submitted_at: basics_submitted_at,
+        launch_submitted_at: launch_submitted_at, live_at: live_at,
+        created_at: created_at, updated_at: updated_at
+      }.compact
+    end
+  end
+
+  # The workspace's RCS registration at a glance: the newest agent, its
+  # brand and test devices, and the +stage+ they are at together. +brand+
+  # and +agent+ are nil until something has been drafted, and +stage+ is
+  # then "draft". +us_eligible+ is false when something on file names a
+  # non-US country.
+  class RcsRegistration
+    CUSTOMER_STAGES = %w[draft in_review changes_requested rejected brand_verification
+                         agent_review testing launch_review launching launch_rejected
+                         live suspended failed].freeze
+    REVIEW_STATUSES = %w[draft awaiting_review changes_requested approved_for_carrier
+                         rejected launch_requested launch_submitted launch_rejected
+                         failed].freeze
+    ERROR_CODES = %w[rcs_not_enabled rcs_not_found rcs_field_locked rcs_us_only
+                     rcs_invalid_content rcs_brand_not_verified rcs_launch_not_ready
+                     rcs_internal_error].freeze
+
+    attr_reader :brand, :agent, :devices, :stage, :us_eligible
+
+    def initialize(data)
+      @brand = data["brand"] ? RcsBrand.new(data["brand"]) : nil
+      @agent = data["agent"] ? RcsAgentRegistration.new(data["agent"]) : nil
+      @devices = (data["devices"] || []).map { |d| RcsTestDevice.new(d) }
+      @stage = data["stage"]
+      @us_eligible = data.key?("usEligible") ? data["usEligible"] : data["us_eligible"]
+    end
+
+    def us_eligible?
+      us_eligible == true
+    end
+
+    def live?
+      stage == "live"
+    end
+
+    def to_h
+      {
+        brand: brand&.to_h, agent: agent&.to_h,
+        devices: devices.map(&:to_h), stage: stage, us_eligible: us_eligible
+      }.compact
+    end
+  end
+
+  # Business details Sendly already holds for the workspace, ready to seed
+  # an RCS brand. +brand+ is a snake_case hash of only the fields on file
+  # (+legal_name+, +display_name+, +ein+, +organization_type+,
+  # +website_url+, +address+, +contact+), so it can be passed straight to
+  # {RcsBrandsResource#create} with +**dossier.brand+. +source+ says where
+  # the details came from: "tendlc" (the workspace's newest 10DLC brand),
+  # "verification" (its active toll-free verification) or "none".
+  class RcsDossier
+    SOURCES = %w[tendlc verification none].freeze
+
+    attr_reader :brand, :us_eligible, :source
+
+    def initialize(data)
+      @brand = RcsRegistrationInput.underscore(data["brand"] || {})
+      @us_eligible = data.key?("usEligible") ? data["usEligible"] : data["us_eligible"]
+      @source = data["source"]
+    end
+
+    def us_eligible?
+      us_eligible == true
+    end
+
+    def prefilled?
+      !brand.empty?
+    end
+
+    def to_h
+      { brand: brand, us_eligible: us_eligible, source: source }.compact
+    end
+  end
+
+  # Read the workspace's RCS registration as a whole.
+  class RcsRegistrationResource
+    def initialize(client)
+      @client = client
+    end
+
+    # Fetch the registration: the newest agent, its brand and test devices,
+    # and the stage they are at. Requires the +rcs:read+ scope.
+    #
+    # @return [RcsRegistration]
+    #
+    # @example
+    #   reg = client.rcs.registration.get
+    #   puts reg.stage                # "draft" until something is submitted
+    #   puts reg.agent&.review_status # e.g. "awaiting_review"
+    def get
+      response = @client.get("/rcs/registration")
+      RcsRegistration.new(response)
+    end
+  end
+
+  # Business details already on file, to seed an RCS brand from.
+  class RcsDossierResource
+    def initialize(client)
+      @client = client
+    end
+
+    # Fetch the details Sendly already holds for this workspace (from its
+    # 10DLC brand or toll-free verification), compacted to the fields that
+    # are set. Requires the +rcs:read+ scope.
+    #
+    # @return [RcsDossier]
+    #
+    # @example Seed a brand from the dossier
+    #   dossier = client.rcs.dossier.get
+    #   brand = client.rcs.brands.create(**dossier.brand) if dossier.prefilled?
+    def get
+      response = @client.get("/rcs/dossier")
+      RcsDossier.new(response)
+    end
+  end
+
+  # Draft and edit the business behind your RCS agents.
+  class RcsBrandsResource
+    def initialize(client)
+      @client = client
+    end
+
+    # Draft a brand. Every field is optional here; required fields are
+    # checked when an agent under the brand is submitted for review. The
+    # address must be in the US. Requires the +rcs:write+ scope.
+    #
+    # Nested hashes accept snake_case or camelCase keys.
+    #
+    # @param display_name [String, nil] The brand name recipients see
+    # @param legal_name [String, nil] Registered legal name
+    # @param legal_entity_type [String, nil] One of {RcsBrand::LEGAL_ENTITY_TYPES}
+    # @param organization_type [String, nil] One of {RcsBrand::ORGANIZATION_TYPES}
+    # @param website_url [String, nil] Public https website
+    # @param ein [String, nil] Employer identification number ("12-3456789" or "123456789")
+    # @param stock_symbol [String, nil] "EXCHANGE:TICKER" for public companies
+    # @param address [Hash, nil] +{ line1:, line2:, city:, state:, postal_code:, country_code: "US" }+
+    # @param contact [Hash, nil] +{ first_name:, last_name:, title:, email:, phone_number: }+ (E.164 phone)
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [RcsBrand]
+    # @raise [Sendly::ValidationError] HTTP 422 +rcs_us_only+ when the address is outside the US
+    #
+    # @example
+    #   brand = client.rcs.brands.create(
+    #     display_name: "Acme Coffee",
+    #     legal_name: "Acme Holdings LLC",
+    #     legal_entity_type: "LIMITED_LIABILITY_COMPANY",
+    #     organization_type: "PRIVATE_PROFIT",
+    #     website_url: "https://acme.example",
+    #     ein: "12-3456789",
+    #     address: { line1: "1 Main St", city: "Austin", state: "TX",
+    #                postal_code: "78701", country_code: "US" },
+    #     contact: { first_name: "Sam", last_name: "Lee", email: "sam@acme.example",
+    #                phone_number: "+15551234567" }
+    #   )
+    def create(display_name: nil, legal_name: nil, legal_entity_type: nil,
+               organization_type: nil, website_url: nil, ein: nil,
+               stock_symbol: nil, address: nil, contact: nil,
+               idempotency_key: nil)
+      body = {}
+      body[:displayName] = display_name unless display_name.nil?
+      body[:legalName] = legal_name unless legal_name.nil?
+      body[:legalEntityType] = legal_entity_type unless legal_entity_type.nil?
+      body[:organizationType] = organization_type unless organization_type.nil?
+      body[:websiteUrl] = website_url unless website_url.nil?
+      body[:ein] = ein unless ein.nil?
+      body[:stockSymbol] = stock_symbol unless stock_symbol.nil?
+      body[:address] = RcsRegistrationInput.camelize(address) unless address.nil?
+      body[:contact] = RcsRegistrationInput.camelize(contact) unless contact.nil?
+
+      response = @client.post("/rcs/brands", body, idempotency_key: idempotency_key)
+      RcsBrand.new(response["brand"] || {})
+    end
+
+    # Edit a brand that is still editable (draft or changes requested).
+    # Only the fields you pass are changed; pass +nil+ to clear a nullable
+    # field. +address+ and +contact+ may be partial hashes. Requires the
+    # +rcs:write+ scope.
+    #
+    # @param id [String] Brand identifier
+    # @param display_name [String, nil]
+    # @param legal_name [String, nil]
+    # @param legal_entity_type [String, nil] One of {RcsBrand::LEGAL_ENTITY_TYPES}
+    # @param organization_type [String, nil] One of {RcsBrand::ORGANIZATION_TYPES}
+    # @param website_url [String, nil]
+    # @param ein [String, nil]
+    # @param stock_symbol [String, nil]
+    # @param address [Hash, nil] Partial address; +country_code+, when present, must be "US"
+    # @param contact [Hash, nil] Partial contact
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [RcsBrand] The updated brand
+    # @raise [Sendly::ValidationError] If no field is given, or HTTP 422
+    #   (+rcs_us_only+, +rcs_invalid_content+ with +field_errors+)
+    # @raise [Sendly::NotFoundError] HTTP 404 +rcs_not_found+ when the brand isn't in this workspace
+    # @raise [Sendly::APIError] HTTP 409 +rcs_field_locked+ while the brand is under review
+    #
+    # @example
+    #   client.rcs.brands.update(brand.id, website_url: "https://acme.example",
+    #                                      address: { line2: "Suite 4" })
+    def update(id, display_name: RcsRegistrationInput::OMIT,
+               legal_name: RcsRegistrationInput::OMIT,
+               legal_entity_type: RcsRegistrationInput::OMIT,
+               organization_type: RcsRegistrationInput::OMIT,
+               website_url: RcsRegistrationInput::OMIT,
+               ein: RcsRegistrationInput::OMIT,
+               stock_symbol: RcsRegistrationInput::OMIT,
+               address: RcsRegistrationInput::OMIT,
+               contact: RcsRegistrationInput::OMIT,
+               idempotency_key: nil)
+      encoded_id = RcsRegistrationInput.encode_id!(id, "Brand ID")
+
+      body = {}
+      body[:displayName] = display_name unless RcsRegistrationInput.omitted?(display_name)
+      body[:legalName] = legal_name unless RcsRegistrationInput.omitted?(legal_name)
+      body[:legalEntityType] = legal_entity_type unless RcsRegistrationInput.omitted?(legal_entity_type)
+      body[:organizationType] = organization_type unless RcsRegistrationInput.omitted?(organization_type)
+      body[:websiteUrl] = website_url unless RcsRegistrationInput.omitted?(website_url)
+      body[:ein] = ein unless RcsRegistrationInput.omitted?(ein)
+      body[:stockSymbol] = stock_symbol unless RcsRegistrationInput.omitted?(stock_symbol)
+      body[:address] = RcsRegistrationInput.camelize(address) unless RcsRegistrationInput.omitted?(address)
+      body[:contact] = RcsRegistrationInput.camelize(contact) unless RcsRegistrationInput.omitted?(contact)
+      raise ValidationError, "Provide at least one brand field to update" if body.empty?
+
+      response = @client.patch("/rcs/brands/#{encoded_id}", body, idempotency_key: idempotency_key)
+      RcsBrand.new(response["brand"] || {})
+    end
+  end
+
+  # Draft, edit, test, submit and launch the RCS agents registered for
+  # your workspace, and list them.
   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.
+    # List your RCS agents, newest first. An empty list means no agent has
+    # been drafted yet: register one with {#create} or from the dashboard.
+    # +stage+ on each agent is its registration stage.
     #
     # @return [Hash] +{ agents: Array<RcsAgent> }+
     #
@@ -155,16 +847,245 @@ module Sendly
       agents = (response["agents"] || []).map { |a| RcsAgent.new(a) }
       { agents: agents }
     end
+
+    # Draft an agent under a brand. Everything but +brand_id+ is optional
+    # here; required fields are checked when you {#submit}. Nested hashes
+    # accept snake_case or camelCase keys. Logo, hero and call-to-action
+    # media must already be public https URLs: assets cannot be uploaded
+    # over the API, only from the dashboard. Requires the +rcs:write+ scope.
+    #
+    # @param brand_id [String] The brand this agent belongs to
+    # @param display_name [String, nil] The agent name recipients see
+    # @param use_case [String, nil] One of {RcsAgentRegistration::USE_CASES}
+    # @param basics [Hash, nil] +{ description:, logo_url:, hero_url:, brand_color:,
+    #   privacy_policy_url:, terms_and_conditions_url:, phone_number: { number:, label: },
+    #   website: { url:, label: }, email: { address:, label: } }+
+    # @param campaign [Hash, nil] +{ company_overview:, agent_overview:, additional_information:,
+    #   interactions: [{ interaction_type:, description: }], message_examples: [...],
+    #   consent_settings: { opt_in_methods: [{ method_type:, description: }], call_to_action:,
+    #   call_to_action_url:, call_to_action_media_url:, double_opt_in:, double_opt_in_message:,
+    #   opt_in_message:, help_response:, opt_out_response: } }+
+    # @param testing [Hash, nil] +{ test_url:, message_id:, additional_information: }+
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [RcsAgentRegistration]
+    # @raise [Sendly::NotFoundError] HTTP 404 +rcs_not_found+ when the brand isn't in this workspace
+    # @raise [Sendly::ValidationError] HTTP 422 +rcs_invalid_content+ (see +field_errors+)
+    #
+    # @example
+    #   agent = client.rcs.agents.create(
+    #     brand_id: brand.id,
+    #     display_name: "Acme Coffee",
+    #     use_case: "MULTI_USE",
+    #     basics: {
+    #       description: "Order updates and offers from Acme Coffee",
+    #       logo_url: "https://acme.example/rcs/logo.png",
+    #       hero_url: "https://acme.example/rcs/hero.png",
+    #       brand_color: "#5B3A29",
+    #       privacy_policy_url: "https://acme.example/privacy",
+    #       terms_and_conditions_url: "https://acme.example/terms",
+    #       phone_number: { number: "+15551234567", label: "Support" }
+    #     }
+    #   )
+    def create(brand_id:, display_name: nil, use_case: nil, basics: nil,
+               campaign: nil, testing: nil, idempotency_key: nil)
+      raise ValidationError, "brand_id is required" if brand_id.nil? || brand_id.to_s.empty?
+
+      body = { brandId: brand_id }
+      body[:displayName] = display_name unless display_name.nil?
+      body[:useCase] = use_case unless use_case.nil?
+      body[:basics] = RcsRegistrationInput.camelize(basics) unless basics.nil?
+      body[:campaign] = RcsRegistrationInput.camelize(campaign) unless campaign.nil?
+      body[:testing] = RcsRegistrationInput.camelize(testing) unless testing.nil?
+
+      response = @client.post("/rcs/agents", body, idempotency_key: idempotency_key)
+      RcsAgentRegistration.new(response["agent"] || {})
+    end
+
+    # Fetch one agent's full registration record, including its test
+    # devices and review state. Requires the +rcs:read+ scope.
+    #
+    # @param id [String] Agent identifier
+    # @return [RcsAgentRegistration]
+    # @raise [Sendly::NotFoundError] HTTP 404 +rcs_not_found+ when the agent isn't in this workspace
+    #
+    # @example
+    #   agent = client.rcs.agents.get("rca_abc123")
+    #   puts agent.customer_stage
+    #   puts agent.review_note if agent.changes_requested?
+    def get(id)
+      encoded_id = RcsRegistrationInput.encode_id!(id, "Agent ID")
+      response = @client.get("/rcs/agents/#{encoded_id}")
+      RcsAgentRegistration.new(response["agent"] || {})
+    end
+
+    # Edit an agent that is still editable. Only the groups you pass are
+    # changed: +display_name+, +use_case+ and +basics+ are merged into the
+    # basics, +campaign+ and +testing+ are merged section-wise, and
+    # +campaign: nil+ or +testing: nil+ clears that section. The same
+    # public-https rule applies to logo, hero and call-to-action media.
+    # Requires the +rcs:write+ scope.
+    #
+    # @param id [String] Agent identifier
+    # @param display_name [String, nil]
+    # @param use_case [String, nil] One of {RcsAgentRegistration::USE_CASES}
+    # @param basics [Hash, nil] Partial basics (see {#create})
+    # @param campaign [Hash, nil] Partial campaign, or +nil+ to clear it
+    # @param testing [Hash, nil] Partial testing details, or +nil+ to clear them
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [RcsAgentRegistration] The updated agent
+    # @raise [Sendly::ValidationError] If no field is given, or HTTP 422
+    #   +rcs_invalid_content+ (see +field_errors+)
+    # @raise [Sendly::NotFoundError] HTTP 404 +rcs_not_found+
+    # @raise [Sendly::APIError] HTTP 409 +rcs_field_locked+ while the agent is under review
+    #
+    # @example
+    #   client.rcs.agents.update(agent.id,
+    #     campaign: {
+    #       agent_overview: "Order updates, delivery alerts and support replies",
+    #       interactions: [{ interaction_type: "TRANSACTIONAL_UPDATES",
+    #                        description: "Order and delivery status" }],
+    #       message_examples: ["Your order #4821 has shipped!",
+    #                          "Your barista is ready for pickup",
+    #                          "Reply HELP for support or STOP to opt out"]
+    #     }
+    #   )
+    def update(id, display_name: RcsRegistrationInput::OMIT,
+               use_case: RcsRegistrationInput::OMIT,
+               basics: RcsRegistrationInput::OMIT,
+               campaign: RcsRegistrationInput::OMIT,
+               testing: RcsRegistrationInput::OMIT,
+               idempotency_key: nil)
+      encoded_id = RcsRegistrationInput.encode_id!(id, "Agent ID")
+
+      body = {}
+      body[:displayName] = display_name unless RcsRegistrationInput.omitted?(display_name)
+      body[:useCase] = use_case unless RcsRegistrationInput.omitted?(use_case)
+      body[:basics] = RcsRegistrationInput.camelize(basics) unless RcsRegistrationInput.omitted?(basics)
+      body[:campaign] = RcsRegistrationInput.camelize(campaign) unless RcsRegistrationInput.omitted?(campaign)
+      body[:testing] = RcsRegistrationInput.camelize(testing) unless RcsRegistrationInput.omitted?(testing)
+      raise ValidationError, "Provide at least one agent field to update" if body.empty?
+
+      response = @client.patch("/rcs/agents/#{encoded_id}", body, idempotency_key: idempotency_key)
+      RcsAgentRegistration.new(response["agent"] || {})
+    end
+
+    # Replace the agent's test devices: the phones that can receive its
+    # messages while it is in testing. The list is authoritative, so
+    # numbers left out are removed and new ones are invited. Up to 20
+    # devices. Requires the +rcs:write+ scope.
+    #
+    # @param id [String] Agent identifier
+    # @param devices [Array<String, Hash>] E.164 numbers, or
+    #   +{ phone_number:, label: }+ hashes
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [Hash] +{ devices: Array<RcsTestDevice> }+ — the full list after the change
+    # @raise [Sendly::ValidationError] If +devices+ isn't an array, or HTTP 422
+    #   +rcs_invalid_content+ (bad number, more than 20 devices)
+    # @raise [Sendly::APIError] HTTP 409 +rcs_field_locked+ while the agent is under review
+    #
+    # @example
+    #   client.rcs.agents.set_test_devices(agent.id, devices: [
+    #     { phone_number: "+15551234567", label: "Sam's Pixel" },
+    #     "+15557654321"
+    #   ])
+    def set_test_devices(id, devices:, idempotency_key: nil)
+      encoded_id = RcsRegistrationInput.encode_id!(id, "Agent ID")
+      raise ValidationError, "devices must be an array" unless devices.is_a?(Array)
+
+      body = {
+        devices: devices.map do |device|
+          device.is_a?(Hash) ? RcsRegistrationInput.camelize(device) : { phoneNumber: device }
+        end
+      }
+      response = @client.put("/rcs/agents/#{encoded_id}/test-devices", body,
+                             idempotency_key: idempotency_key)
+      list = (response["devices"] || []).map { |d| RcsTestDevice.new(d) }
+      { devices: list }
+    end
+
+    # Submit the agent and its brand for Sendly's review. Once approved
+    # they go on to the carrier network for brand verification and agent
+    # review; watch +customer_stage+ with {#get}. Requires the +rcs:write+
+    # scope.
+    #
+    # Pass your own +idempotency_key+ if you may retry: a replay returns
+    # the original response without submitting again.
+    #
+    # @param id [String] Agent identifier
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [RcsAgentRegistration] The agent, now +awaiting_review?+
+    # @raise [Sendly::ValidationError] HTTP 422 +rcs_invalid_content+ when the
+    #   brand or agent basics are incomplete (+field_errors+ lists
+    #   +brand.<field>+ / +agent.<field>+ paths)
+    # @raise [Sendly::APIError] HTTP 409 +rcs_field_locked+ when already
+    #   submitted, or +rcs_brand_not_verified+ when the brand failed verification
+    #
+    # @example
+    #   agent = client.rcs.agents.submit(agent.id, idempotency_key: "rcs-submit-#{agent.id}")
+    #   puts agent.review_status # "awaiting_review"
+    def submit(id, idempotency_key: nil)
+      encoded_id = RcsRegistrationInput.encode_id!(id, "Agent ID")
+      response = @client.post("/rcs/agents/#{encoded_id}/submit", {}, idempotency_key: idempotency_key)
+      RcsAgentRegistration.new(response["agent"] || {})
+    end
+
+    # Ask to launch an agent that has been tested on an invited device.
+    # Sendly reviews the campaign and testing details, then sends the
+    # launch on to the carrier network. Requires the +rcs:write+ scope.
+    #
+    # @param id [String] Agent identifier
+    # @param test_url [String, nil] Where the test conversation can be seen; stored
+    #   into the agent's testing details first
+    # @param testing_additional_information [String, nil] Anything else the
+    #   reviewer should know about the test
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [RcsAgentRegistration] The agent, now +launch_requested?+
+    # @raise [Sendly::ValidationError] HTTP 422 +rcs_invalid_content+ when the
+    #   campaign or testing details are incomplete (+field_errors+ lists
+    #   +campaign.<field>+ / +testing.<field>+ paths)
+    # @raise [Sendly::APIError] HTTP 409 +rcs_launch_not_ready+ until the agent
+    #   is in testing, or +rcs_field_locked+ while a request is pending
+    #
+    # @example
+    #   client.rcs.agents.request_launch(agent.id,
+    #     test_url: "https://acme.example/rcs-test",
+    #     testing_additional_information: "Tested on two invited devices"
+    #   )
+    def request_launch(id, test_url: nil, testing_additional_information: nil,
+                       idempotency_key: nil)
+      encoded_id = RcsRegistrationInput.encode_id!(id, "Agent ID")
+
+      body = {}
+      body[:testUrl] = test_url unless test_url.nil?
+      body[:testingAdditionalInformation] = testing_additional_information unless testing_additional_information.nil?
+
+      response = @client.post("/rcs/agents/#{encoded_id}/request-launch", body,
+                              idempotency_key: idempotency_key)
+      RcsAgentRegistration.new(response["agent"] || {})
+    end
   end
 
-  # RCS resource — discover your RCS agents and pre-flight recipient
-  # capability.
+  # RCS resource — register your RCS agent, discover your 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}.
+  # +client.messages.send(channel: "rcs", ...)+.
+  #
+  # Registration is self-serve, from the dashboard or this API: draft the
+  # brand ({RcsBrandsResource#create}) and the agent
+  # ({RcsAgentsResource#create}), submit them for Sendly's review
+  # ({RcsAgentsResource#submit}), and once approved they go on to the
+  # carrier network for brand verification and agent review. The agent
+  # then reaches invited test devices only
+  # ({RcsAgentsResource#set_test_devices}); when you have tested it,
+  # {RcsAgentsResource#request_launch} asks Sendly to review the campaign
+  # and send the launch on to the carrier network. {RcsRegistrationResource#get}
+  # shows where the registration is, and {RcsDossierResource#get} seeds
+  # the brand from details Sendly already holds. Logo, hero and
+  # call-to-action media must be public https URLs; assets cannot be
+  # uploaded over the API, only from the dashboard. Registration reads
+  # need the +rcs:read+ scope and writes +rcs:write+.
   #
   # Delivery is per-recipient: not every device or network supports RCS.
   # Text messages fall back to plain SMS automatically (billed as SMS)
@@ -185,12 +1106,24 @@ module Sendly
   #     )
   #   end
   class RcsResource
-    # @return [RcsAgentsResource] List registered agents
+    # @return [RcsAgentsResource] Register and list agents
     attr_reader :agents
 
+    # @return [RcsRegistrationResource] The registration at a glance
+    attr_reader :registration
+
+    # @return [RcsDossierResource] Business details on file, to seed a brand
+    attr_reader :dossier
+
+    # @return [RcsBrandsResource] Draft and edit brands
+    attr_reader :brands
+
     def initialize(client)
       @client = client
       @agents = RcsAgentsResource.new(client)
+      @registration = RcsRegistrationResource.new(client)
+      @dossier = RcsDossierResource.new(client)
+      @brands = RcsBrandsResource.new(client)
     end
 
     # Check whether a recipient can receive RCS.

data/lib/sendly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sendly
-  VERSION = "3.38.0"
+  VERSION = "3.39.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendly
 version: !ruby/object:Gem::Version
-  version: 3.38.0
+  version: 3.39.0
 platform: ruby
 authors:
 - Sendly
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-08-31 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday