sendly 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84b10285655be846bb857f5e11388a893d916838d480accfc46a646c16dd68a3
-  data.tar.gz: cfe12c76eeea0a6db834c09d97c7546260c4a313f5f6d9c64a549d467884ae3b
+  metadata.gz: 6e04f0698b7520abcb9cd17816198b7e728ab2ce6d2ed1d564195887334dca82
+  data.tar.gz: 9f26320067a3fe83a7035364cdf6682e03f9b93bf26996faf728cbfb9899065c
 SHA512:
-  metadata.gz: 5c528f37943ed1c30eb8b6929097cb167ba9be070e0a8b3ec6d69949e9710a38ccbf1bdb04ce57d92a569fabdb68e56df3e50104e3ffffb620d9c6962d3e4e73
-  data.tar.gz: 73c7ba0af6ac53f75b33759b2566292f64ee5199c13f088da4ebb3b8bf68afea4b00fdddb76a0e7f3a7a1fa1547162ab94fa81a119d0b18004bce650ca6ed434
+  metadata.gz: 2b3ec03a21b0eae75affd32ee962e3e33a4481f1b5b23e656d5633ebeef18f0302168343943a5b74f45176609566229dcccead196d939f73e43a7c19aa676c77
+  data.tar.gz: f7d9d7f44fd1fe7aa99d53dcfbfdba8be8fb25e15d0ccdefda67488d7ea5552c04199f5a91287bab73b703192b1ae5860bb6c80fe23085bc2d4bb98d28f5ba2a

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # sendly (Ruby)
 
+## 4.2.0
+
+### Minor Changes
+
+- **Voice configuration: `client.voice`.** Everything a phone call depends on is now configurable from code over the new `/api/v1/voice` routes. `client.voice.numbers` has `list`, `get(number)`, `update(number, voice_enabled:, voice_mode:, agent_id:)` and `register_emergency_address(number, street:, city:, state:, zip:, unit: nil, country: nil)`: switch voice on for a number, choose how it answers (`Sendly::VoiceNumber::VOICE_MODES`), and register the emergency address a US or Canadian number needs before it can place calls ($1.50 a month; registering again replaces the address without a second charge). `number` is the number's id or its E.164 phone number, and `agent_id: nil` clears the stored agent. `client.voice.agents` has `list`, `create(name:, ...)`, `get(id)`, `update(id, ...)` and `delete(id)` for the AI agents that answer and place calls (up to 20 per workspace, each holding its own scoped sending key); `tools:` takes `send_sms` and `transfer_to` in snake_case or camelCase. `client.voice.voices.list` lists the voices agents can speak with. Lists are Enumerable (`Sendly::VoiceNumberList`, `Sendly::VoiceAgentList`, `Sendly::VoiceList`); the models are `Sendly::VoiceNumber` (with `Sendly::VoiceNumberEmergencyAddress`, `Sendly::EmergencyAddress` and `Sendly::VoiceNumberRates`), `Sendly::VoiceAgent` (with `Sendly::VoiceAgentTools`), `Sendly::Voice` and `Sendly::DeletedVoiceAgent`. POSTs send the client's usual `Idempotency-Key`, and every write accepts `idempotency_key:`. Reads need the `calls:read` scope, writes `calls:write` and a live key; in a team workspace, number changes also need a role that can change settings and agent changes a role that can manage API keys. Deleting an agent that still answers a number raises `Sendly::APIError` (409 `agent_in_use`). `Sendly::Call::ERROR_CODES` gains `agent_in_use`, `agent_limit`, `invalid_voice_mode`, `invalid_address`, `e911_not_applicable`, `voice_attach_failed`, `carrier_refused`, `invalid_request` and `insufficient_permissions`.
+
+  ```ruby
+  agent = client.voice.agents.create(name: "Front desk", tools: { send_sms: true })
+  client.voice.numbers.update("+15555550188", voice_enabled: true, voice_mode: "agent", agent_id: agent.id)
+  ```
+
+- **`Sendly::Error#response_body`** is the parsed JSON body of the API error response, for refusals that carry more than a message: a 409 `agent_in_use` lists the numbers the agent still answers under `"numbers"`, and a 422 `invalid_address` carries a corrected address (or `nil`) under `"suggested"`. It is `nil` for errors raised before a request is sent.
+- **`Sendly::Client#delete` accepts `idempotency_key:`**, like `patch` and `put`.
+
+### Patch Changes
+
+- **The `Sendly::CallRecording` docstring had the channels the wrong way round.** Agent-handled calls are recorded with the agent on the left channel and the other party on the right.
+
 ## 4.1.0
 
 ### Minor Changes

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    sendly (4.1.0)
+    sendly (4.2.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.8)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     bigdecimal (3.3.1)
@@ -74,7 +74,7 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
     uri (1.1.1)
-    webmock (3.26.1)
+    webmock (3.26.4)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)

data/README.md

@@ -1175,10 +1175,12 @@ client.messages.send(
 ## Voice Calls
 
 Place phone calls that one of your AI agents handles, list and inspect
-calls, end a call early, and download recordings. Agents are configured in
-the dashboard under Calls, then Agents; the number you call from must have
-voice switched on there (Calls, then Settings) and an emergency address
-registered before it can place outbound calls. Each `Sendly::PhoneNumber`
+calls, end a call early, and download recordings. Agents are created with
+`client.voice.agents` or in the dashboard under Calls, then Agents; the
+number you call from must have voice switched on and an emergency address
+registered before it can place outbound calls (see
+[Configure voice](#configure-voice), or Calls, then Settings in the
+dashboard). Each `Sendly::PhoneNumber`
 from `client.numbers.list` carries `voice_enabled?` and `voice_mode`
 (`"none"`, `"ring_dashboard"` or `"agent"`) so you can pick a `from`:
 
@@ -1193,8 +1195,8 @@ are US and Canadian numbers. Reads need the `calls:read` scope; `create`
 and `hangup` need `calls:write` and a live key.
 
 > **Rolling out.** Voice is enabled workspace by workspace. Until it is on
-> for yours, every call method raises `Sendly::NotFoundError`
-> (`voice_not_enabled`).
+> for yours, every `client.calls` and `client.voice` method raises
+> `Sendly::NotFoundError` (`voice_not_enabled`).
 
 ```ruby
 # Place a call. Returns at once with the call ringing; the agent greets the
@@ -1228,7 +1230,8 @@ puts page.has_more?
 client.calls.hangup(call.id)
 
 # Recording. The URL is signed and valid for five minutes; it is nil until
-# the recording is ready. Ogg/Opus, dual channel on agent calls.
+# the recording is ready. Ogg/Opus; agent calls are dual channel, with the
+# agent on the left channel and the other party on the right.
 rec = client.calls.recording(call.id)
 if rec.ready?
   File.binwrite("#{call.id}.ogg", Net::HTTP.get(URI(rec.url)))
@@ -1254,6 +1257,88 @@ The full list is `Sendly::Call::ERROR_CODES`; the hangup vocabulary is
 the same object in snake_case (`handled_by`, `hangup_class`, `billing`,
 `metadata`, ...); `Sendly::Call.new(event.raw_object)` reads it.
 
+### Configure voice
+
+Everything a call depends on is configurable from code with `client.voice`:
+switch voice on for a number and choose how it answers, register the
+number's emergency address, and create the AI agents that talk. Reads need
+the `calls:read` scope; writes need `calls:write` and a live key. In a team
+workspace, changing a number or its emergency address also needs a role that
+can change settings, and managing agents a role that can manage API keys
+(each agent holds its own scoped sending key).
+
+```ruby
+# Numbers. Pass the number's id or its E.164 phone number.
+client.voice.numbers.list.each do |n|
+  puts "#{n.phone_number} #{n.voice_mode} #{n.emergency_address&.status || 'no emergency address'}"
+end
+number = client.voice.numbers.get("+15555550188")
+puts number.rate_per_minute.agent   # credits a minute when an agent answers
+
+# A US or Canadian number needs an emergency address before it can place
+# calls. The first registration adds $1.50 a month to the number;
+# registering again replaces the address without a second charge.
+number = client.voice.numbers.register_emergency_address(
+  "+15555550188",
+  street: "500 Example Ave",
+  unit: "Suite 2",
+  city: "Austin",
+  state: "TX",
+  zip: "78701"                      # country: defaults to "US"
+)
+puts number.emergency_address.status
+
+# Voices and agents. An agent answers real callers on any number pointed at it.
+client.voice.voices.list.each { |v| puts "#{v.id}: #{v.label}" }
+
+agent = client.voice.agents.create(
+  name: "Front desk",
+  voice: "ashley",
+  greeting: "Thanks for calling Acme, how can I help?",
+  instructions: "Answer questions about opening hours and take a message for anything else.",
+  tools: { send_sms: true }         # snake_case or camelCase keys
+)
+puts agent.can_send_sms?            # true once it holds its scoped sending key
+client.voice.agents.update(agent.id, greeting: "Thanks for calling Acme. How can I help today?")
+client.voice.agents.list.each { |a| puts "#{a.name}: #{a.calls_handled} calls" }
+
+# Switching voice on changes how real calls to the number are answered.
+client.voice.numbers.update("+15555550188", voice_enabled: true, voice_mode: "agent", agent_id: agent.id)
+client.voice.numbers.update("+15555550188", voice_mode: "ring_dashboard") # ring the team instead
+client.voice.numbers.update("+15555550188", voice_enabled: false)         # switch voice off
+
+# An agent that answers a number can't be deleted until the number is moved.
+begin
+  client.voice.agents.delete(agent.id)
+rescue Sendly::APIError => e
+  raise unless e.response_body&.dig("error") == "agent_in_use"
+
+  puts "Still answers #{e.response_body['numbers'].join(', ')}"
+end
+```
+
+A mode alone is enough: `voice_mode: "agent"` or `"ring_dashboard"` switches
+voice on, so it can fail the way switching on does, and `voice_mode: "none"`
+switches it off. `voice_enabled: false` wins over any mode, and
+`voice_enabled: true` with `"none"` answers in `"ring_dashboard"` mode.
+
+Configuration errors map the same way: `Sendly::NotFoundError` for
+`number_not_found` and `agent_not_found`; `Sendly::ValidationError` for
+`invalid_request` (for example an emergency address field that is not a
+string), `invalid_voice_mode`, `agent_required`,
+`e911_not_applicable` and `invalid_address` (a 422 `invalid_address` means
+the address could not be validated, and `e.response_body["suggested"]` holds
+a corrected address when one was found); `Sendly::APIError` with
+`status_code` 409 for `agent_disabled`, `agent_limit` (20 agents per
+workspace) and `agent_in_use`; and `Sendly::ServerError` for 502
+`voice_attach_failed` and `carrier_refused` and 503 `voice_unavailable`,
+raised after the client has already retried the 5xx on its own. Not every
+`carrier_refused` is worth retrying: when the message says the number
+couldn't be found for emergency registration, retrying won't help, so
+contact support. When it says the address couldn't be registered or
+emergency calling couldn't be switched on, try again later. Every API error
+keeps the parsed body on `e.response_body`.
+
 ## Error Handling
 
 ```ruby

data/lib/sendly/calls_resource.rb

@@ -58,6 +58,8 @@ module Sendly
       no_voice_number number_not_found destination_not_supported e911_required lines_busy
       daily_call_limit call_not_found live_key_required voice_internal_error
       insufficient_credits invalid_number rate_limit_exceeded forbidden
+      invalid_request insufficient_permissions agent_in_use agent_limit invalid_voice_mode
+      invalid_address e911_not_applicable voice_attach_failed carrier_refused
     ].freeze
 
     attr_reader :id, :object, :kind, :direction, :status, :handled_by, :agent_id,
@@ -182,8 +184,8 @@ module Sendly
   # call runs, "ready" once it can be fetched, or "failed". +url+ and
   # +expires_at+ are set only when {#ready?}: the URL is signed and valid for
   # five minutes. Recordings are Ogg/Opus (+content_type+ "audio/ogg");
-  # agent-handled calls are recorded dual-channel, caller left and agent
-  # right.
+  # agent-handled calls are recorded dual-channel, with the agent on the
+  # left channel and the other party on the right.
   class CallRecording
     STATUSES = %w[none recording ready failed].freeze
 
@@ -213,9 +215,10 @@ module Sendly
   # Calls resource: place phone calls handled by your AI agents, list and
   # inspect calls, end a call and fetch recordings.
   #
-  # A call placed over the API is answered by one of the AI agents you
-  # configure in the dashboard under Calls, then Agents; the +from+ number
-  # must have voice switched on in the dashboard. Calls are charged per
+  # A call placed over the API is answered by one of your AI agents
+  # (create them with {VoiceAgentsResource#create} or in the dashboard
+  # under Calls, then Agents); the +from+ number must have voice switched
+  # on ({VoiceNumbersResource#update} or the dashboard). Calls are charged per
   # started minute from your credit balance: 2 credits a minute outbound,
   # plus 8 a minute while an agent is on the call. Destinations are US and
   # Canadian numbers. Reads need the +calls:read+ scope, writes
@@ -278,7 +281,8 @@ module Sendly
     # @raise [Sendly::InsufficientCreditsError] HTTP 402 when the balance
     #   cannot cover one minute at the agent rate
     # @raise [Sendly::APIError] HTTP 428 +e911_required+ (register an
-    #   emergency address for the number first), 409 +agent_disabled+ /
+    #   emergency address for the number first with
+    #   {VoiceNumbersResource#register_emergency_address}), 409 +agent_disabled+ /
     #   +no_voice_number+ / +lines_busy+, 403 +live_key_required+
     # @raise [Sendly::RateLimitError] HTTP 429 +daily_call_limit+ / +rate_limit_exceeded+
     # @raise [Sendly::ServerError] HTTP 503 +voice_unavailable+ /

data/lib/sendly/client.rb

@@ -199,6 +199,17 @@ module Sendly
       @calls ||= CallsResource.new(self)
     end
 
+    # Access the Voice resource (numbers, AI agents and voices for phone calls)
+    #
+    # @return [Sendly::VoiceResource]
+    #
+    # @example
+    #   agent = client.voice.agents.create(name: "Front desk")
+    #   client.voice.numbers.update("+15555550188", voice_enabled: true, voice_mode: "agent", agent_id: agent.id)
+    def voice
+      @voice ||= VoiceResource.new(self)
+    end
+
     # Make a GET request
     #
     # @param path [String] API path
@@ -255,10 +266,14 @@ module Sendly
 
     # Make a DELETE request
     #
+    # No Idempotency-Key is generated for a DELETE; pass +idempotency_key+
+    # to send one (1-255 printable ASCII characters).
+    #
     # @param path [String] API path
+    # @param idempotency_key [String, nil] Caller-supplied idempotency key (optional)
     # @return [Hash] Response body
-    def delete(path)
-      request(:delete, path)
+    def delete(path, idempotency_key: nil)
+      request(:delete, path, idempotency_key: idempotency_key)
     end
 
     # Make a GET request against the API origin, bypassing the +/api/v1+ base.

data/lib/sendly/errors.rb

@@ -12,12 +12,30 @@ module Sendly
     # @return [Integer, nil] HTTP status code
     attr_reader :status_code
 
+    # @return [Hash, nil] The parsed JSON body of the API's error response,
+    #   or +nil+ for errors raised before a request was sent. The API's own
+    #   error code is under +"error"+, and some refusals carry more than a
+    #   message: a 409 +agent_in_use+ lists the numbers the agent still
+    #   answers under +"numbers"+, and a 422 +invalid_address+ carries a
+    #   corrected address (or +nil+) under +"suggested"+.
+    attr_reader :response_body
+
     def initialize(message = nil, code: nil, details: nil, status_code: nil)
       @code = code
       @details = details
       @status_code = status_code
       super(message)
     end
+
+    # Attach the parsed body of the API response this error came from.
+    #
+    # @api private
+    # @param body [Hash, nil]
+    # @return [self]
+    def with_response_body(body)
+      @response_body = body
+      self
+    end
   end
 
   # Raised when the API key is invalid or missing
@@ -101,23 +119,24 @@ module Sendly
       code = body["code"]
       details = body["details"]
 
-      case status
-      when 400, 422
-        ValidationError.new(message, details: details, field_errors: body["errors"])
-      when 401
-        AuthenticationError.new(message)
-      when 402
-        InsufficientCreditsError.new(message)
-      when 404
-        NotFoundError.new(message)
-      when 429
-        retry_after = body["retry_after"] || body["retryAfter"]
-        RateLimitError.new(message, retry_after: retry_after)
-      when 500..599
-        ServerError.new(message, status_code: status)
-      else
-        APIError.new(message, status_code: status, code: code, details: details)
-      end
+      error = case status
+              when 400, 422
+                ValidationError.new(message, details: details, field_errors: body["errors"])
+              when 401
+                AuthenticationError.new(message)
+              when 402
+                InsufficientCreditsError.new(message)
+              when 404
+                NotFoundError.new(message)
+              when 429
+                retry_after = body["retry_after"] || body["retryAfter"]
+                RateLimitError.new(message, retry_after: retry_after)
+              when 500..599
+                ServerError.new(message, status_code: status)
+              else
+                APIError.new(message, status_code: status, code: code, details: details)
+              end
+      error.with_response_body(body)
     end
   end
 end

data/lib/sendly/numbers_resource.rb

@@ -55,7 +55,8 @@ module Sendly
                 # ISO-8601 timestamp string, or nil when no release is scheduled.
                 :scheduled_release_at,
                 # true when the number can place and receive phone calls
-                # (switched on in the dashboard under Calls, then Settings).
+                # (switched on with {VoiceNumbersResource#update} or in the
+                # dashboard under Calls, then Settings).
                 :voice_enabled,
                 # One of {VOICE_MODES}: "none" when voice is off, "ring_dashboard"
                 # when inbound calls ring the team, "agent" when an AI agent answers.

data/lib/sendly/templates_resource.rb

@@ -222,10 +222,6 @@ module Sendly
     end
 
     # Copy an existing template into a new draft.
-    #
-    # @note Not available yet: the versioned API serves no clone route, so
-    #   this call fails with a 404. To copy a template today, read it with
-    #   {#get} and pass its {Template#text} to {#create}.
     def clone(id, name: nil)
       body = {}
       body[:name] = name if name

data/lib/sendly/version.rb

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

data/lib/sendly/voice_resource.rb

@@ -0,0 +1,721 @@
+# frozen_string_literal: true
+
+module Sendly
+  # A street address registered for emergency calls. +unit+ is +nil+ when
+  # there is none, +state+ is the two-letter state or province code and
+  # +country+ is "US" or "CA".
+  class EmergencyAddress
+    attr_reader :street, :unit, :city, :state, :zip, :country
+
+    def initialize(data)
+      data ||= {}
+      @street = data["street"]
+      @unit = data["unit"]
+      @city = data["city"]
+      @state = data["state"]
+      @zip = data["zip"]
+      @country = data["country"]
+    end
+
+    def to_h
+      { street: street, unit: unit, city: city, state: state, zip: zip, country: country }.compact
+    end
+  end
+
+  # A number's emergency address registration. +status+ is "provisioning"
+  # while the registration is being switched on, "active" once it is in
+  # place, and otherwise the failure status as recorded. +address+ is +nil+
+  # when no address is on file.
+  class VoiceNumberEmergencyAddress
+    attr_reader :status, :address
+
+    def initialize(data)
+      data ||= {}
+      @status = data["status"]
+      @address = data["address"] ? EmergencyAddress.new(data["address"]) : nil
+    end
+
+    def active?
+      status == "active"
+    end
+
+    def to_h
+      { status: status, address: address&.to_h }.compact
+    end
+  end
+
+  # Credits charged per started minute on a number. +inbound+ is an inbound
+  # call the team answers in the dashboard, +outbound+ an outbound call (an
+  # agent on the call adds its own per-minute charge) and +agent+ an inbound
+  # call an AI agent answers, agent included.
+  class VoiceNumberRates
+    attr_reader :inbound, :outbound, :agent
+
+    def initialize(data)
+      data ||= {}
+      @inbound = data["inbound"]
+      @outbound = data["outbound"]
+      @agent = data["agent"]
+    end
+
+    def to_h
+      { inbound: inbound, outbound: outbound, agent: agent }.compact
+    end
+  end
+
+  # A number in your workspace with its voice settings.
+  #
+  # +voice_mode+ is one of {VOICE_MODES} and reports how inbound calls are
+  # answered: "none" when calls are not answered (always so when voice is off),
+  # "ring_dashboard" when calls ring the team in the dashboard, and "agent"
+  # when an AI agent answers. +agent_id+ is the agent that answers in
+  # "agent" mode; in the other modes it is whichever agent was last stored,
+  # or +nil+. +emergency_address+ is +nil+ until one is registered.
+  # +phone_number_type+ (for example "local") and +country_code+ can be
+  # +nil+.
+  class VoiceNumber
+    VOICE_MODES = %w[none ring_dashboard agent].freeze
+
+    attr_reader :id, :object, :phone_number, :phone_number_type, :country_code,
+                :is_default, :voice_enabled, :voice_mode, :agent_id,
+                :emergency_address, :rate_per_minute
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
+
+    def initialize(data)
+      data ||= {}
+      @raw = data
+      @id = data["id"]
+      @object = data["object"] || "voice_number"
+      @phone_number = data["phoneNumber"] || data["phone_number"]
+      @phone_number_type = data["phoneNumberType"] || data["phone_number_type"]
+      @country_code = data["countryCode"] || data["country_code"]
+      @is_default = data.key?("isDefault") ? data["isDefault"] : data["is_default"]
+      @voice_enabled = data.key?("voiceEnabled") ? data["voiceEnabled"] : data["voice_enabled"]
+      @voice_mode = data["voiceMode"] || data["voice_mode"]
+      @agent_id = data["agentId"] || data["agent_id"]
+      address = data["emergencyAddress"] || data["emergency_address"]
+      @emergency_address = address ? VoiceNumberEmergencyAddress.new(address) : nil
+      rates = data["ratePerMinute"] || data["rate_per_minute"]
+      @rate_per_minute = rates ? VoiceNumberRates.new(rates) : nil
+    end
+
+    # @return [Boolean] Whether this is the workspace's default sending number
+    def default?
+      is_default == true
+    end
+
+    # @return [Boolean] Whether the number takes and places phone calls
+    def voice_enabled?
+      voice_enabled == true
+    end
+
+    def to_h
+      {
+        id: id, object: object, phone_number: phone_number,
+        phone_number_type: phone_number_type, country_code: country_code,
+        is_default: is_default, voice_enabled: voice_enabled, voice_mode: voice_mode,
+        agent_id: agent_id, emergency_address: emergency_address&.to_h,
+        rate_per_minute: rate_per_minute&.to_h
+      }.compact
+    end
+  end
+
+  # What an agent may do on a call.
+  #
+  # +send_sms+ is true when the agent may text the caller; it confirms the
+  # number back to them before sending. +transfer_to+ is an E.164 number
+  # for callers who need a person, or +nil+. Agents cannot transfer calls
+  # yet and never dial or read out this number: while it is set, a caller
+  # who asks for a person is told their message will be passed on, and the
+  # agent takes their name and number.
+  class VoiceAgentTools
+    attr_reader :send_sms, :transfer_to
+
+    def initialize(data)
+      data ||= {}
+      @send_sms = data.key?("sendSms") ? data["sendSms"] : data["send_sms"]
+      @transfer_to = data["transferTo"] || data["transfer_to"]
+    end
+
+    def send_sms?
+      send_sms == true
+    end
+
+    def to_h
+      { send_sms: send_sms, transfer_to: transfer_to }.compact
+    end
+  end
+
+  # An AI agent that answers and places phone calls.
+  #
+  # +voice+ is a voice id from {VoiceVoicesResource#list} and +voice_label+
+  # its readable name. +greeting+ and +instructions+ are +""+ when unset.
+  # +can_send_sms+ is true when the agent holds its own scoped sending key,
+  # which +tools.send_sms+ needs to actually send. +calls_handled+ and
+  # +avg_duration_secs+ are the agent's call stats. Timestamps are ISO 8601
+  # strings.
+  class VoiceAgent
+    attr_reader :id, :object, :name, :enabled, :voice, :voice_label, :language,
+                :greeting, :instructions, :tools, :can_send_sms, :calls_handled,
+                :avg_duration_secs, :created_at, :updated_at
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
+
+    def initialize(data)
+      data ||= {}
+      @raw = data
+      @id = data["id"]
+      @object = data["object"] || "voice_agent"
+      @name = data["name"]
+      @enabled = data["enabled"]
+      @voice = data["voice"]
+      @voice_label = data["voiceLabel"] || data["voice_label"]
+      @language = data["language"]
+      @greeting = data["greeting"]
+      @instructions = data["instructions"]
+      @tools = VoiceAgentTools.new(data["tools"])
+      @can_send_sms = data.key?("canSendSms") ? data["canSendSms"] : data["can_send_sms"]
+      @calls_handled = data["callsHandled"] || data["calls_handled"] || 0
+      @avg_duration_secs = data["avgDurationSecs"] || data["avg_duration_secs"] || 0
+      @created_at = data["createdAt"] || data["created_at"]
+      @updated_at = data["updatedAt"] || data["updated_at"]
+    end
+
+    # @return [Boolean] Whether the agent is switched on. A switched-off agent
+    #   can't be pointed at a number or put on a call.
+    def enabled?
+      enabled == true
+    end
+
+    # @return [Boolean] Whether the agent holds its scoped sending key
+    def can_send_sms?
+      can_send_sms == true
+    end
+
+    def to_h
+      {
+        id: id, object: object, name: name, enabled: enabled, voice: voice,
+        voice_label: voice_label, language: language, greeting: greeting,
+        instructions: instructions, tools: tools.to_h, can_send_sms: can_send_sms,
+        calls_handled: calls_handled, avg_duration_secs: avg_duration_secs,
+        created_at: created_at, updated_at: updated_at
+      }.compact
+    end
+  end
+
+  # A voice an agent can speak with. Pass +id+ as +voice:+ when creating or
+  # updating an agent; +language+ is the language it speaks, e.g. "en".
+  class Voice
+    attr_reader :id, :label, :language
+
+    def initialize(data)
+      data ||= {}
+      @id = data["id"]
+      @label = data["label"]
+      @language = data["language"]
+    end
+
+    def to_h
+      { id: id, label: label, language: language }.compact
+    end
+  end
+
+  # The confirmation {VoiceAgentsResource#delete} returns.
+  class DeletedVoiceAgent
+    attr_reader :id, :object, :deleted
+
+    def initialize(data)
+      data ||= {}
+      @id = data["id"]
+      @object = data["object"] || "voice_agent"
+      @deleted = data["deleted"] == true
+    end
+
+    def deleted?
+      deleted
+    end
+
+    def to_h
+      { id: id, object: object, deleted: deleted }
+    end
+  end
+
+  # The +data+ array a voice list method returns, as an Enumerable of
+  # model objects.
+  class VoiceDataList
+    include Enumerable
+
+    attr_reader :data
+
+    def initialize(response, model)
+      @data = ((response || {})["data"] || []).map { |item| model.new(item) }
+    end
+
+    def each(&block)
+      data.each(&block)
+    end
+
+    def size
+      data.length
+    end
+
+    alias length size
+
+    def empty?
+      data.empty?
+    end
+
+    def last
+      data.last
+    end
+  end
+
+  # The workspace's active numbers with their voice settings, as {VoiceNumber}s.
+  class VoiceNumberList < VoiceDataList
+    def initialize(response)
+      super(response, VoiceNumber)
+    end
+  end
+
+  # The workspace's AI agents, as {VoiceAgent}s.
+  class VoiceAgentList < VoiceDataList
+    def initialize(response)
+      super(response, VoiceAgent)
+    end
+  end
+
+  # The voices an agent can speak with, as {Voice}s.
+  class VoiceList < VoiceDataList
+    def initialize(response)
+      super(response, Voice)
+    end
+  end
+
+  # Shapes voice input before it leaves the process.
+  #
+  # @api private
+  module VoiceInput
+    OMIT = Object.new.freeze
+    TOOL_KEYS = { "send_sms" => "sendSms", "transfer_to" => "transferTo" }.freeze
+
+    module_function
+
+    def require_text!(value, message)
+      raise ValidationError, message if value.nil? || value.to_s.strip.empty?
+    end
+
+    def number_path(number)
+      require_text!(number, "number is required")
+      "/voice/numbers/#{URI.encode_www_form_component(number)}"
+    end
+
+    def agent_path(id)
+      require_text!(id, "Agent ID is required")
+      "/voice/agents/#{URI.encode_www_form_component(id)}"
+    end
+
+    def tools_body(tools)
+      return tools unless tools.is_a?(Hash)
+
+      tools.each_with_object({}) { |(key, value), out| out[TOOL_KEYS.fetch(key.to_s, key.to_s)] = value }
+    end
+
+    def agent_body(name:, enabled:, voice:, language:, greeting:, instructions:, tools:)
+      body = {}
+      body[:name] = name unless name.nil?
+      body[:enabled] = enabled unless enabled.nil?
+      body[:voice] = voice unless voice.nil?
+      body[:language] = language unless language.nil?
+      body[:greeting] = greeting unless greeting.nil?
+      body[:instructions] = instructions unless instructions.nil?
+      body[:tools] = tools_body(tools) unless tools.nil?
+      body
+    end
+  end
+
+  # Voice settings for the numbers in your workspace: switch voice on for a
+  # number, choose how it answers, and register its emergency address.
+  # Reached as +client.voice.numbers+.
+  class VoiceNumbersResource
+    def initialize(client)
+      @client = client
+    end
+
+    # List the workspace's active numbers with their voice settings, in the
+    # same order as the dashboard. Requires the +calls:read+ scope.
+    #
+    # @return [Sendly::VoiceNumberList]
+    #
+    # @example
+    #   client.voice.numbers.list.each do |n|
+    #     puts "#{n.phone_number} #{n.voice_mode} #{n.emergency_address&.status || 'no emergency address'}"
+    #   end
+    def list
+      response = @client.get("/voice/numbers")
+      VoiceNumberList.new(response)
+    end
+
+    # Fetch one number's voice settings. Requires the +calls:read+ scope.
+    #
+    # @param number [String] The number's id or its E.164 phone number
+    # @return [Sendly::VoiceNumber]
+    # @raise [Sendly::ValidationError] If +number+ is blank
+    # @raise [Sendly::NotFoundError] HTTP 404 +number_not_found+ when the
+    #   number is not active in your workspace
+    #
+    # @example
+    #   number = client.voice.numbers.get("+15555550188")
+    #   puts number.voice_mode
+    #   puts number.rate_per_minute.agent
+    def get(number)
+      response = @client.get(VoiceInput.number_path(number))
+      VoiceNumber.new(response)
+    end
+
+    # Change how a number answers phone calls. Requires the +calls:write+
+    # scope and a live key; in a team workspace, also a role that can change
+    # settings.
+    #
+    # This changes what happens when real people call the number. Turning
+    # voice on connects the number for calls before the change is saved and
+    # answers in "ring_dashboard" mode unless +voice_mode+ is "agent".
+    # A mode alone is enough: +voice_mode: "ring_dashboard"+ or +"agent"+
+    # switches voice on, and +voice_mode: "none"+ switches it off.
+    # +voice_enabled: false+ wins over any mode, and +voice_enabled: true+
+    # with "none" answers in "ring_dashboard" mode.
+    #
+    # @param number [String] The number's id or its E.164 phone number
+    # @param voice_enabled [Boolean, nil] Switch voice on or off
+    # @param voice_mode [String, nil] One of {VoiceNumber::VOICE_MODES}
+    # @param agent_id [String, nil] The agent that answers in "agent" mode.
+    #   Needed (here or already stored) for "agent" mode, and the agent must
+    #   be switched on. Pass +nil+ to clear the stored agent; leave it out to
+    #   keep it.
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [Sendly::VoiceNumber] The number after the change
+    # @raise [Sendly::ValidationError] If +number+ is blank, or HTTP 400
+    #   +invalid_request+ (a wrongly typed field), +invalid_voice_mode+ or
+    #   +agent_required+ ("agent" mode with no agent)
+    # @raise [Sendly::NotFoundError] HTTP 404 +number_not_found+ / +agent_not_found+
+    # @raise [Sendly::APIError] HTTP 409 +agent_disabled+ (the agent is
+    #   switched off), 403 +forbidden+ / +live_key_required+
+    # @raise [Sendly::ServerError] HTTP 502 +voice_attach_failed+ (voice could
+    #   not be switched on; try again) or 503 +voice_unavailable+, after the
+    #   client's automatic retries. Either can follow a mode alone on a number
+    #   whose voice is off.
+    #
+    # @example Have an agent answer
+    #   client.voice.numbers.update(
+    #     "+15555550188",
+    #     voice_enabled: true,
+    #     voice_mode: "agent",
+    #     agent_id: "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b"
+    #   )
+    #
+    # @example Ring the team in the dashboard instead
+    #   client.voice.numbers.update("+15555550188", voice_mode: "ring_dashboard")
+    def update(number, voice_enabled: nil, voice_mode: nil, agent_id: VoiceInput::OMIT, idempotency_key: nil)
+      path = VoiceInput.number_path(number)
+      body = {}
+      body[:voiceEnabled] = voice_enabled unless voice_enabled.nil?
+      body[:voiceMode] = voice_mode unless voice_mode.nil?
+      body[:agentId] = agent_id unless VoiceInput::OMIT.equal?(agent_id)
+
+      response = @client.patch(path, body, idempotency_key: idempotency_key)
+      VoiceNumber.new(response)
+    end
+
+    # Register the street address emergency services are sent to when
+    # someone calls them from this number. Requires the +calls:write+ scope
+    # and a live key; in a team workspace, also a role that can change
+    # settings.
+    #
+    # A US or Canadian number needs one before it can place calls. The first
+    # registration adds $1.50 a month to the number; registering again
+    # replaces the address without adding the charge a second time.
+    #
+    # @param number [String] The number's id or its E.164 phone number
+    # @param street [String] Street address
+    # @param city [String] City
+    # @param state [String] Two-letter state or province code, e.g. "TX"
+    # @param zip [String] Five-digit ZIP (or ZIP+4) in the US, a postal code
+    #   like "A1A 1A1" in Canada
+    # @param unit [String, nil] Apartment, suite or floor
+    # @param country [String, nil] "US" or "CA" (the API defaults to "US")
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [Sendly::VoiceNumber] The number with its +emergency_address+
+    # @raise [Sendly::ValidationError] If +number+, +street+, +city+, +state+
+    #   or +zip+ is blank; HTTP 400 +invalid_request+ (a field that is not a
+    #   string, such as +zip: 78701+), +invalid_address+ (a malformed field)
+    #   or +e911_not_applicable+ (a number outside the US and Canada); or HTTP
+    #   422 +invalid_address+ when the address could not be validated, with a
+    #   corrected address (or +nil+) in +e.response_body["suggested"]+
+    # @raise [Sendly::NotFoundError] HTTP 404 +number_not_found+
+    # @raise [Sendly::ServerError] HTTP 502 +carrier_refused+ when the
+    #   registration was refused, raised after the client has already retried
+    #   the 5xx on its own. When the message says the number couldn't be
+    #   found for emergency registration, retrying won't help: contact
+    #   support. When it says the address couldn't be registered or emergency
+    #   calling couldn't be switched on, try again later.
+    #
+    # @example
+    #   number = client.voice.numbers.register_emergency_address(
+    #     "+15555550188",
+    #     street: "500 Example Ave",
+    #     unit: "Suite 2",
+    #     city: "Austin",
+    #     state: "TX",
+    #     zip: "78701"
+    #   )
+    #   puts number.emergency_address.status
+    def register_emergency_address(number, street:, city:, state:, zip:, unit: nil, country: nil,
+                                   idempotency_key: nil)
+      path = "#{VoiceInput.number_path(number)}/emergency-address"
+      VoiceInput.require_text!(street, "street is required")
+      VoiceInput.require_text!(city, "city is required")
+      VoiceInput.require_text!(state, "state is required")
+      VoiceInput.require_text!(zip, "zip is required")
+
+      body = { street: street }
+      body[:unit] = unit unless unit.nil?
+      body[:city] = city
+      body[:state] = state
+      body[:zip] = zip
+      body[:country] = country unless country.nil?
+
+      response = @client.post(path, body, idempotency_key: idempotency_key)
+      VoiceNumber.new(response)
+    end
+  end
+
+  # The AI agents that answer and place your phone calls. Reached as
+  # +client.voice.agents+.
+  class VoiceAgentsResource
+    def initialize(client)
+      @client = client
+    end
+
+    # List the workspace's AI agents with their call stats. Requires the
+    # +calls:read+ scope.
+    #
+    # @return [Sendly::VoiceAgentList]
+    #
+    # @example
+    #   client.voice.agents.list.each do |agent|
+    #     puts "#{agent.name} (#{agent.voice_label}) #{agent.calls_handled} calls"
+    #   end
+    def list
+      response = @client.get("/voice/agents")
+      VoiceAgentList.new(response)
+    end
+
+    # Create an AI agent. Requires the +calls:write+ scope and a live key; in
+    # a team workspace, also a role that can manage API keys.
+    #
+    # The agent answers real callers on any number pointed at it and talks on
+    # the calls you place with it. Each agent gets its own scoped sending key
+    # so it can text callers; {VoiceAgent#can_send_sms?} says whether it has
+    # one. A workspace can have up to 20 agents.
+    #
+    # @param name [String] 1-80 characters
+    # @param enabled [Boolean, nil] Whether the agent is switched on (the API
+    #   defaults to +true+)
+    # @param voice [String, nil] A voice id from {VoiceVoicesResource#list};
+    #   an unknown id falls back to the default voice
+    # @param language [String, nil] Language tag, up to 16 characters (the
+    #   API defaults to "en-US")
+    # @param greeting [String, nil] What the agent says when it picks up, up
+    #   to 500 characters
+    # @param instructions [String, nil] Business instructions the agent
+    #   follows, up to 4000 characters
+    # @param tools [Hash, nil] +send_sms:+ and +transfer_to:+ (see
+    #   {VoiceAgentTools}); camelCase keys are accepted too. +send_sms+
+    #   defaults to +true+ and +transfer_to+ to +nil+.
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [Sendly::VoiceAgent] The new agent
+    # @raise [Sendly::ValidationError] If +name+ is blank, or HTTP 400
+    #   +invalid_request+ naming the field the API rejected
+    # @raise [Sendly::APIError] HTTP 409 +agent_limit+ when the workspace
+    #   already has 20 agents, 403 +forbidden+ / +live_key_required+
+    #
+    # @example
+    #   agent = client.voice.agents.create(
+    #     name: "Front desk",
+    #     voice: "ashley",
+    #     greeting: "Thanks for calling Acme, how can I help?",
+    #     instructions: "Answer questions about opening hours and take a message for anything else.",
+    #     tools: { send_sms: true }
+    #   )
+    #   puts agent.id
+    def create(name:, enabled: nil, voice: nil, language: nil, greeting: nil, instructions: nil,
+               tools: nil, idempotency_key: nil)
+      VoiceInput.require_text!(name, "name is required")
+
+      body = VoiceInput.agent_body(
+        name: name, enabled: enabled, voice: voice, language: language,
+        greeting: greeting, instructions: instructions, tools: tools
+      )
+      response = @client.post("/voice/agents", body, idempotency_key: idempotency_key)
+      VoiceAgent.new(response)
+    end
+
+    # Fetch one agent. Requires the +calls:read+ scope.
+    #
+    # @param id [String] Agent identifier
+    # @return [Sendly::VoiceAgent]
+    # @raise [Sendly::ValidationError] If +id+ is blank
+    # @raise [Sendly::NotFoundError] HTTP 404 +agent_not_found+ when the
+    #   agent is not in your workspace
+    #
+    # @example
+    #   agent = client.voice.agents.get("3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b")
+    #   puts agent.greeting
+    def get(id)
+      response = @client.get(VoiceInput.agent_path(id))
+      VoiceAgent.new(response)
+    end
+
+    # Update an agent. Requires the +calls:write+ scope and a live key; in a
+    # team workspace, also a role that can manage API keys. Pass only what
+    # changes; +tools+ keys you leave out keep their current values.
+    #
+    # @param id [String] Agent identifier
+    # @param name [String, nil] 1-80 characters
+    # @param enabled [Boolean, nil] Switch the agent on or off
+    # @param voice [String, nil] A voice id from {VoiceVoicesResource#list};
+    #   an unknown id falls back to the default voice
+    # @param language [String, nil] Language tag, up to 16 characters; +""+
+    #   resets it to "en-US"
+    # @param greeting [String, nil] Up to 500 characters; +""+ clears it
+    # @param instructions [String, nil] Up to 4000 characters; +""+ clears it
+    # @param tools [Hash, nil] Tool settings to change (+send_sms:+,
+    #   +transfer_to:+); +transfer_to: nil+ clears the number
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [Sendly::VoiceAgent] The agent after the change
+    # @raise [Sendly::ValidationError] If +id+ is blank, or HTTP 400
+    #   +invalid_request+ naming the field the API rejected
+    # @raise [Sendly::NotFoundError] HTTP 404 +agent_not_found+
+    #
+    # @example
+    #   client.voice.agents.update(
+    #     "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
+    #     greeting: "Thanks for calling Acme. How can I help today?",
+    #     tools: { send_sms: false }
+    #   )
+    def update(id, name: nil, enabled: nil, voice: nil, language: nil, greeting: nil, instructions: nil,
+               tools: nil, idempotency_key: nil)
+      path = VoiceInput.agent_path(id)
+      body = VoiceInput.agent_body(
+        name: name, enabled: enabled, voice: voice, language: language,
+        greeting: greeting, instructions: instructions, tools: tools
+      )
+
+      response = @client.patch(path, body, idempotency_key: idempotency_key)
+      VoiceAgent.new(response)
+    end
+
+    # Delete an agent and revoke its sending key. Requires the +calls:write+
+    # scope and a live key; in a team workspace, also a role that can manage
+    # API keys.
+    #
+    # An agent that answers a number can't be deleted: the API responds 409
+    # +agent_in_use+ and +e.response_body["numbers"]+ lists those numbers.
+    # Point them at another agent or back to the team first with
+    # {VoiceNumbersResource#update}.
+    #
+    # @param id [String] Agent identifier
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [Sendly::DeletedVoiceAgent]
+    # @raise [Sendly::ValidationError] If +id+ is blank
+    # @raise [Sendly::NotFoundError] HTTP 404 +agent_not_found+
+    # @raise [Sendly::APIError] HTTP 409 +agent_in_use+
+    #
+    # @example
+    #   begin
+    #     client.voice.agents.delete(agent.id)
+    #   rescue Sendly::APIError => e
+    #     raise unless e.response_body&.dig("error") == "agent_in_use"
+    #
+    #     e.response_body["numbers"].each do |number|
+    #       client.voice.numbers.update(number, voice_mode: "ring_dashboard")
+    #     end
+    #     client.voice.agents.delete(agent.id)
+    #   end
+    def delete(id, idempotency_key: nil)
+      response = @client.delete(VoiceInput.agent_path(id), idempotency_key: idempotency_key)
+      DeletedVoiceAgent.new(response)
+    end
+  end
+
+  # The voices an agent can speak with. Reached as +client.voice.voices+.
+  class VoiceVoicesResource
+    def initialize(client)
+      @client = client
+    end
+
+    # List the voices an agent can speak with. Requires the +calls:read+
+    # scope.
+    #
+    # @return [Sendly::VoiceList]
+    #
+    # @example
+    #   client.voice.voices.list.each { |v| puts "#{v.id}: #{v.label}" }
+    def list
+      response = @client.get("/voice/voices")
+      VoiceList.new(response)
+    end
+  end
+
+  # Voice resource: configure everything a phone call depends on, from code.
+  # {#numbers} switches voice on for a number, chooses how it answers and
+  # registers its emergency address; {#agents} manages the AI agents that
+  # talk on calls; {#voices} lists the voices those agents can use.
+  #
+  # Reads need the +calls:read+ scope; writes need +calls:write+ and a live
+  # API key (+sk_live_v1_xxx+). In a team workspace, number and emergency
+  # address changes also need a role that can change settings, and agent
+  # changes a role that can manage API keys (each agent holds its own scoped
+  # sending key); otherwise the API responds 403 +forbidden+.
+  #
+  # Voice is enabled workspace by workspace. Until it is on for yours,
+  # every method here raises {Sendly::NotFoundError} (+voice_not_enabled+).
+  #
+  # Error codes map onto the usual classes: {Sendly::NotFoundError} for
+  # +voice_not_enabled+, +number_not_found+ and +agent_not_found+;
+  # {Sendly::ValidationError} for +invalid_request+, +invalid_voice_mode+,
+  # +agent_required+, +invalid_address+ (400 and 422) and
+  # +e911_not_applicable+; {Sendly::APIError} with the HTTP status for
+  # +agent_disabled+ / +agent_limit+ / +agent_in_use+ (409) and +forbidden+
+  # / +live_key_required+ / +insufficient_permissions+ (403); and
+  # {Sendly::ServerError} (not an +APIError+) for +voice_attach_failed+ /
+  # +carrier_refused+ (502), +voice_unavailable+ (503) and
+  # +voice_internal_error+ (500). Every API error keeps the parsed body on
+  # {Sendly::Error#response_body}. The full list is {Call::ERROR_CODES}.
+  #
+  # @example Have a new agent answer a number
+  #   agent = client.voice.agents.create(name: "Front desk", greeting: "Thanks for calling Acme, how can I help?")
+  #   client.voice.numbers.register_emergency_address(
+  #     "+15555550188", street: "500 Example Ave", city: "Austin", state: "TX", zip: "78701"
+  #   )
+  #   client.voice.numbers.update("+15555550188", voice_enabled: true, voice_mode: "agent", agent_id: agent.id)
+  class VoiceResource
+    # @return [VoiceNumbersResource] Voice settings and emergency addresses for your numbers
+    attr_reader :numbers
+
+    # @return [VoiceAgentsResource] The AI agents that talk on calls
+    attr_reader :agents
+
+    # @return [VoiceVoicesResource] The voices agents can speak with
+    attr_reader :voices
+
+    def initialize(client)
+      @client = client
+      @numbers = VoiceNumbersResource.new(client)
+      @agents = VoiceAgentsResource.new(client)
+      @voices = VoiceVoicesResource.new(client)
+    end
+  end
+end

data/lib/sendly.rb

@@ -28,6 +28,7 @@ require_relative "sendly/links_resource"
 require_relative "sendly/whatsapp_resource"
 require_relative "sendly/rcs_resource"
 require_relative "sendly/calls_resource"
+require_relative "sendly/voice_resource"
 
 # Sendly Ruby SDK
 #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendly
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Sendly
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -146,6 +146,7 @@ files:
 - lib/sendly/types.rb
 - lib/sendly/verify.rb
 - lib/sendly/version.rb
+- lib/sendly/voice_resource.rb
 - lib/sendly/webhooks.rb
 - lib/sendly/webhooks_resource.rb
 - lib/sendly/whatsapp_resource.rb