sendly 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40344d4fa41e8c72544b0b5327b7bc4d717285c38d244397bf0f93ad21ce5b1a
-  data.tar.gz: d0bf2bd2c6256ccdbdea1f8c9319c5891b5a030b798a091e7afc59d33752b543
+  metadata.gz: 84b10285655be846bb857f5e11388a893d916838d480accfc46a646c16dd68a3
+  data.tar.gz: cfe12c76eeea0a6db834c09d97c7546260c4a313f5f6d9c64a549d467884ae3b
 SHA512:
-  metadata.gz: 20aa959ad9bd7f630c1e26b0a511648aecbfb02d095a789d2d17500e2e035eb02b79fad1c9ae6dc9e0959c41dda68d73c97b1a3d1a795f2dedacd41f8ef03262
-  data.tar.gz: 70f56c72f0b628b86e5ea964de3653b7e16d00fa9c4a5214ef14038dbf3da30feedf84b3b489bbfdfd316c42d70f4116ff6b914fe358d7204498d41601a8213a
+  metadata.gz: 5c528f37943ed1c30eb8b6929097cb167ba9be070e0a8b3ec6d69949e9710a38ccbf1bdb04ce57d92a569fabdb68e56df3e50104e3ffffb620d9c6962d3e4e73
+  data.tar.gz: 73c7ba0af6ac53f75b33759b2566292f64ee5199c13f088da4ebb3b8bf68afea4b00fdddb76a0e7f3a7a1fa1547162ab94fa81a119d0b18004bce650ca6ed434

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # sendly (Ruby)
 
+## 4.1.0
+
+### Minor Changes
+
+- **Voice calls: `client.calls`.** Place phone calls handled by your AI agents, list and inspect them, end one early and fetch recordings, over the new `/api/v1/calls` routes. `create(to:, agent_id:, from: nil, context: nil, metadata: nil)` returns a `Sendly::Call` that is `ringing`; `list` takes `limit:`, `offset:`, `status:`, `direction:`, `kind:`, `agent_id:`, `to:` and `from:` and returns an Enumerable `Sendly::CallList` with `total`, `limit`, `offset` and `has_more?`; `get(id)` adds the `transcript` (an array of `Sendly::CallTranscriptLine`) on agent-handled calls and leaves it `nil` otherwise; `hangup(id)` cancels a ringing call or completes an active one and returns an already-ended call unchanged; `recording(id)` returns a `Sendly::CallRecording` whose signed `url` is set only while `ready?` and expires after five minutes. `create` and `hangup` send the client's usual `Idempotency-Key` and accept `idempotency_key:`. `Sendly::Call` also reads the snake_case object carried by the `call.started`, `call.completed` and `call.recording.ready` webhooks, including the new `billing` and `metadata` keys. Vocabularies are published as `Sendly::Call::STATUSES`, `::HANGUP_CLASSES` and `::ERROR_CODES`. `Sendly::PhoneNumber` gains `voice_enabled` (with `voice_enabled?`), `voice_mode` (`Sendly::PhoneNumber::VOICE_MODES`) and `raw`, so `client.numbers.list` can pick the `from` number for a call. Reads need the `calls:read` scope; writes need `calls:write` and a live key. Voice is enabled workspace by workspace: until it is on for yours the routes answer 404 `voice_not_enabled`, which raises `Sendly::NotFoundError`.
+
+  ```ruby
+  call = client.calls.create(
+    to: "+15555550123",
+    agent_id: "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
+    context: "Confirm the 3pm appointment on Tuesday."
+  )
+  call = client.calls.get(call.id)
+  call.transcript&.each { |line| puts "#{line.speaker}: #{line.text}" }
+  ```
+
 ## 4.0.0
 
 **Upgrading from 3.40.0:** that release already contained the breaking changes below, published by mistake as a minor version. 4.0.0 carries them under the correct major. Relative to 3.40.0, the only new changes are under **Security**.

data/Gemfile.lock

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

data/README.md

@@ -802,6 +802,7 @@ end
 # Get one number you own (includes is_default, which the list omits)
 number = client.numbers.get('num_abc123')
 puts "#{number.phone_number} — default sender: #{number.is_default}"
+puts "voice: #{number.voice_enabled?} (#{number.voice_mode})"
 
 # Update a number — make it the default sender (must be active),
 # and/or cancel a scheduled release ("keep this number")
@@ -1171,6 +1172,88 @@ 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`
+from `client.numbers.list` carries `voice_enabled?` and `voice_mode`
+(`"none"`, `"ring_dashboard"` or `"agent"`) so you can pick a `from`:
+
+```ruby
+from = client.numbers.list[:numbers].find(&:voice_enabled?)&.phone_number
+```
+
+Calls are prepaid from your credit balance per started minute: 2 credits a
+minute outbound, plus 8 a minute while an AI agent is on the call (10 in
+total for an API-placed call). Unanswered calls cost nothing. Destinations
+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`).
+
+```ruby
+# Place a call. Returns at once with the call ringing; the agent greets the
+# callee when they answer and uses `context` for this call only.
+call = client.calls.create(
+  to: "+15555550123",
+  agent_id: "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
+  from: "+15555550188",                # optional when you have one voice number
+  context: "Confirm the 3pm appointment on Tuesday.",
+  metadata: { "crmId" => "lead_8812" } # up to 20 string pairs, echoed everywhere
+)
+puts call.id
+puts call.status        # "ringing"
+puts call.handled_by    # "agent"
+
+# Follow it. Agent-handled calls include a transcript once fetched by id.
+call = client.calls.get(call.id)
+puts call.status        # "ringing" -> "active" -> "completed" (or no_answer, busy, ...)
+puts call.hangup_class  # why it ended, e.g. "agent_agent_hangup"
+puts call.credits_charged
+call.transcript&.each { |line| puts "#{line.speaker}: #{line.text}" }
+
+# List (newest first; limit 1-100, default 50)
+page = client.calls.list(status: "completed", direction: "outbound", agent_id: call.agent_id, limit: 20)
+page.each { |c| puts "#{c.to} #{c.duration_secs}s #{c.credits_charged} credits" }
+puts page.total
+puts page.has_more?
+
+# End a call. Ringing -> "cancelled", active -> "completed"; a call that
+# has already ended comes back unchanged.
+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.
+rec = client.calls.recording(call.id)
+if rec.ready?
+  File.binwrite("#{call.id}.ogg", Net::HTTP.get(URI(rec.url)))
+end
+```
+
+Call errors map onto the usual classes: `Sendly::InsufficientCreditsError`
+when the balance cannot cover one minute at the agent rate;
+`Sendly::NotFoundError` for `voice_not_enabled`, `outbound_calls_not_enabled`,
+`agent_not_found`, `number_not_found` and `call_not_found`;
+`Sendly::ValidationError` for `invalid_number`, `destination_not_supported`,
+`agent_required`, `invalid_metadata` and `from_number_required`;
+`Sendly::RateLimitError` for `daily_call_limit`; `Sendly::APIError` with
+`status_code` 428 for `e911_required` (register an emergency address for the
+number), 409 for `agent_disabled`, `no_voice_number` and `lines_busy` (retry
+shortly), or 403 for `live_key_required` and a key missing the scope; and
+`Sendly::ServerError` (a sibling of `APIError`, not a subclass) for 503
+`voice_unavailable` / `agents_unavailable` and 500 `voice_internal_error`.
+The full list is `Sendly::Call::ERROR_CODES`; the hangup vocabulary is
+`Sendly::Call::HANGUP_CLASSES`.
+
+`call.started`, `call.completed` and `call.recording.ready` webhooks carry
+the same object in snake_case (`handled_by`, `hangup_class`, `billing`,
+`metadata`, ...); `Sendly::Call.new(event.raw_object)` reads it.
+
 ## Error Handling
 
 ```ruby

data/lib/sendly/calls_resource.rb

@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+module Sendly
+  # One line of what was said on an agent-handled call. +speaker+ is
+  # "caller" or "agent"; +at_ms+ is the offset from the start of the call.
+  class CallTranscriptLine
+    SPEAKERS = %w[caller agent].freeze
+
+    attr_reader :speaker, :text, :at_ms
+
+    def initialize(data)
+      data ||= {}
+      @speaker = data["speaker"]
+      @text = data["text"]
+      @at_ms = data["atMs"] || data["at_ms"]
+    end
+
+    def to_h
+      { speaker: speaker, text: text, at_ms: at_ms }.compact
+    end
+  end
+
+  # A phone call placed or received by one of your workspace's numbers.
+  #
+  # +kind+ is "pstn" for a phone call and "internal" for a browser-to-browser
+  # call between teammates. +status+ is "ringing" or "active" while the call
+  # is live and one of the terminal values ("completed", "no_answer", "busy",
+  # "cancelled", "declined", "failed") once it has ended; "suspended" can
+  # appear on an internal call whose media dropped and may recover.
+  # +handled_by+ says whether an AI agent ("agent") or the team in the
+  # dashboard ("dashboard") took the call. +billing+ is "metered" while a
+  # phone call is charged per started minute, "settled" once it has ended,
+  # and "unbilled" for calls that are never charged. +hangup_class+ says why
+  # the call ended (see {HANGUP_CLASSES}); anything unrecognised arrives as
+  # "ended". +metadata+ is the string map attached on create (+{}+ when
+  # none). +transcript+ is only present on {CallsResource#get} for
+  # agent-handled calls and is +nil+ otherwise.
+  class Call
+    STATUSES = %w[ringing active completed no_answer busy cancelled declined failed suspended].freeze
+    LIVE_STATUSES = %w[ringing active].freeze
+    DIRECTIONS = %w[inbound outbound].freeze
+    KINDS = %w[pstn internal].freeze
+    HANDLED_BY = %w[agent dashboard].freeze
+    BILLING_STATES = %w[metered settled unbilled].freeze
+    RECORDING_STATUSES = %w[recording ready failed].freeze
+    HANGUP_CLASSES = %w[
+      normal caller_hung_up callee_hung_up caller_left peer_left agent_ended
+      agent_agent_hangup agent_caller_left
+      ring_timeout callee_declined callee_busy caller_cancelled room_closed_unanswered
+      agent_left_unanswered agent_caller_never_joined invalid_number destination_rejected
+      max_duration credits_exhausted media_aborted peer_connection_lost room_closed agent_left
+      setup_failed agent_dispatch_failed agent_api_unreachable agent_already_ended
+      ended
+    ].freeze
+    ERROR_CODES = %w[
+      voice_unavailable agents_unavailable voice_not_enabled outbound_calls_not_enabled
+      agent_required agent_not_found agent_disabled invalid_metadata from_number_required
+      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
+    ].freeze
+
+    attr_reader :id, :object, :kind, :direction, :status, :handled_by, :agent_id,
+                :from, :to, :caller_name, :callee_name, :started_at, :answered_at,
+                :ended_at, :duration_secs, :credits_charged, :billing, :hangup_class,
+                :recording_status, :metadata, :transcript
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
+
+    def initialize(data)
+      data ||= {}
+      @raw = data
+      @id = data["id"]
+      @object = data["object"] || "call"
+      @kind = data["kind"]
+      @direction = data["direction"]
+      @status = data["status"]
+      @handled_by = data["handledBy"] || data["handled_by"]
+      @agent_id = data["agentId"] || data["agent_id"]
+      @from = data["from"]
+      @to = data["to"]
+      @caller_name = data["callerName"] || data["caller_name"]
+      @callee_name = data["calleeName"] || data["callee_name"]
+      @started_at = data["startedAt"] || data["started_at"]
+      @answered_at = data["answeredAt"] || data["answered_at"]
+      @ended_at = data["endedAt"] || data["ended_at"]
+      @duration_secs = data["durationSecs"] || data["duration_secs"] || 0
+      @credits_charged = data["creditsCharged"] || data["credits_charged"] || 0
+      @billing = data["billing"]
+      @hangup_class = data["hangupClass"] || data["hangup_class"]
+      @recording_status = data["recordingStatus"] || data["recording_status"]
+      @metadata = data["metadata"] || {}
+      lines = data["transcript"]
+      @transcript = lines.is_a?(Array) ? lines.map { |l| CallTranscriptLine.new(l) } : nil
+    end
+
+    # @return [Boolean] Whether the call is still ringing or in progress
+    def live?
+      LIVE_STATUSES.include?(status)
+    end
+
+    # @return [Boolean] Whether the call has reached a terminal status
+    def ended?
+      !status.nil? && !live? && status != "suspended"
+    end
+
+    def answered?
+      !answered_at.nil?
+    end
+
+    def agent_handled?
+      handled_by == "agent"
+    end
+
+    def inbound?
+      direction == "inbound"
+    end
+
+    def outbound?
+      direction == "outbound"
+    end
+
+    def to_h
+      {
+        id: id, object: object, kind: kind, direction: direction, status: status,
+        handled_by: handled_by, agent_id: agent_id, from: from, to: to,
+        caller_name: caller_name, callee_name: callee_name, started_at: started_at,
+        answered_at: answered_at, ended_at: ended_at, duration_secs: duration_secs,
+        credits_charged: credits_charged, billing: billing, hangup_class: hangup_class,
+        recording_status: recording_status, metadata: metadata,
+        transcript: transcript&.map(&:to_h)
+      }.compact
+    end
+  end
+
+  # A page of calls, newest first, with the pagination the API returned.
+  class CallList
+    include Enumerable
+
+    attr_reader :data, :total, :limit, :offset, :has_more
+
+    def initialize(response)
+      @data = (response["data"] || []).map { |c| Call.new(c) }
+      pagination = response["pagination"] || {}
+      @total = pagination["total"] || @data.length
+      @limit = pagination["limit"] || 50
+      @offset = pagination["offset"] || 0
+      @has_more = pagination["hasMore"] || pagination["has_more"] || false
+    end
+
+    def has_more?
+      has_more == true
+    end
+
+    def each(&block)
+      data.each(&block)
+    end
+
+    def count
+      data.length
+    end
+
+    alias size count
+    alias length count
+
+    def empty?
+      data.empty?
+    end
+
+    def first
+      data.first
+    end
+
+    def last
+      data.last
+    end
+  end
+
+  # The recording of a call. +status+ is "none" when there is no recording
+  # (recording off, or the call was never answered), "recording" while the
+  # 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.
+  class CallRecording
+    STATUSES = %w[none recording ready failed].freeze
+
+    attr_reader :call_id, :status, :url, :expires_at, :content_type
+
+    def initialize(data)
+      data ||= {}
+      @call_id = data["callId"] || data["call_id"]
+      @status = data["status"]
+      @url = data["url"]
+      @expires_at = data["expiresAt"] || data["expires_at"]
+      @content_type = data["contentType"] || data["content_type"]
+    end
+
+    def ready?
+      status == "ready"
+    end
+
+    def to_h
+      {
+        call_id: call_id, status: status, url: url, expires_at: expires_at,
+        content_type: content_type
+      }.compact
+    end
+  end
+
+  # 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
+  # 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
+  # +calls:write+ and a live API key (+sk_live_v1_xxx+).
+  #
+  # 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+, +outbound_calls_not_enabled+, +agent_not_found+,
+  # +number_not_found+ and +call_not_found+; {Sendly::ValidationError} for
+  # +invalid_number+, +destination_not_supported+, +agent_required+,
+  # +invalid_metadata+ and +from_number_required+;
+  # {Sendly::InsufficientCreditsError} for +insufficient_credits+;
+  # {Sendly::RateLimitError} for +daily_call_limit+ and
+  # +rate_limit_exceeded+; {Sendly::APIError} with the HTTP status for
+  # +e911_required+ (428), +agent_disabled+ / +no_voice_number+ /
+  # +lines_busy+ (409) and +live_key_required+ / +forbidden+ (403); and
+  # {Sendly::ServerError} (not an +APIError+) for +voice_unavailable+ /
+  # +agents_unavailable+ (503) and +voice_internal_error+ (500). The full
+  # list is {Call::ERROR_CODES}.
+  #
+  # @example Place a call and wait for it to end
+  #   call = client.calls.create(
+  #     to: "+15555550123",
+  #     agent_id: "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
+  #     context: "Confirm the 3pm appointment on Tuesday."
+  #   )
+  #   call = client.calls.get(call.id) while call.live? && sleep(2)
+  #   puts call.hangup_class
+  #   call.transcript.each { |line| puts "#{line.speaker}: #{line.text}" }
+  class CallsResource
+    def initialize(client)
+      @client = client
+    end
+
+    # Place a phone call that one of your AI agents handles. Returns at once
+    # with the call +ringing+; poll {#get} or subscribe to the +call.started+
+    # and +call.completed+ webhooks to follow it. Requires the +calls:write+
+    # scope and a live key.
+    #
+    # @param to [String] The number to call, in E.164 format (US or Canada)
+    # @param agent_id [String] The AI agent that talks on the call
+    # @param from [String, nil] A voice-enabled number in your workspace.
+    #   Optional when the workspace has exactly one; required (the API
+    #   responds 400 +from_number_required+) when it has more.
+    # @param context [String, nil] Up to 2000 characters appended to the
+    #   agent's instructions for this call only. Not echoed back.
+    # @param metadata [Hash{String => String}, nil] Up to 20 string pairs
+    #   (keys 1-40 characters of +A-Z a-z 0-9 _ . : -+, values up to 500
+    #   characters). Stored, echoed on every read and in every +call.*+
+    #   webhook.
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [Sendly::Call] The new call (+status+ "ringing", +handled_by+ "agent")
+    # @raise [Sendly::ValidationError] If +to+ or +agent_id+ is missing, or
+    #   HTTP 400 (+invalid_number+, +destination_not_supported+,
+    #   +agent_required+, +invalid_metadata+, +from_number_required+)
+    # @raise [Sendly::NotFoundError] HTTP 404 (+voice_not_enabled+,
+    #   +outbound_calls_not_enabled+, +agent_not_found+, +number_not_found+)
+    # @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+ /
+    #   +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+ /
+    #   +agents_unavailable+ (calling is not switched on for this deployment),
+    #   HTTP 500 +voice_internal_error+
+    #
+    # @example
+    #   call = client.calls.create(
+    #     to: "+15555550123",
+    #     agent_id: "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
+    #     from: "+15555550188",
+    #     metadata: { "crmId" => "lead_8812" }
+    #   )
+    #   puts call.id
+    def create(to:, agent_id:, from: nil, context: nil, metadata: nil, idempotency_key: nil)
+      raise ValidationError, "to is required" if to.nil? || to.to_s.empty?
+      raise ValidationError, "agent_id is required" if agent_id.nil? || agent_id.to_s.empty?
+
+      body = { to: to, agentId: agent_id }
+      body[:from] = from unless from.nil?
+      body[:context] = context unless context.nil?
+      body[:metadata] = metadata unless metadata.nil?
+
+      response = @client.post("/calls", body, idempotency_key: idempotency_key)
+      Call.new(response)
+    end
+
+    # List your workspace's calls, newest first. Live rows are reconciled
+    # before they are returned, so a ring past its deadline reads as
+    # +no_answer+. Requires the +calls:read+ scope.
+    #
+    # @param limit [Integer, nil] Calls per page (1-100, default 50)
+    # @param offset [Integer, nil] Calls to skip (default 0)
+    # @param status [String, nil] One of {Call::STATUSES}
+    # @param direction [String, nil] "inbound" or "outbound"
+    # @param kind [String, nil] "pstn" or "internal"
+    # @param agent_id [String, nil] Only calls handled by this agent
+    # @param to [String, nil] Exact E.164 match on the called number
+    # @param from [String, nil] Exact E.164 match on the calling number
+    # @return [Sendly::CallList] The page and its pagination
+    # @raise [Sendly::ValidationError] HTTP 400 +invalid_request+ for a value
+    #   outside the vocabularies above
+    #
+    # @example
+    #   page = client.calls.list(status: "completed", direction: "outbound", limit: 20)
+    #   page.each { |c| puts "#{c.to} #{c.duration_secs}s #{c.credits_charged} credits" }
+    #   puts page.has_more?
+    def list(limit: nil, offset: nil, status: nil, direction: nil, kind: nil,
+             agent_id: nil, to: nil, from: nil)
+      params = {}
+      params[:limit] = limit unless limit.nil?
+      params[:offset] = offset unless offset.nil?
+      params[:status] = status unless status.nil?
+      params[:direction] = direction unless direction.nil?
+      params[:kind] = kind unless kind.nil?
+      params[:agentId] = agent_id unless agent_id.nil?
+      params[:to] = to unless to.nil?
+      params[:from] = from unless from.nil?
+
+      response = @client.get("/calls", params)
+      CallList.new(response)
+    end
+
+    # Fetch one call. Agent-handled calls include their +transcript+; a live
+    # call is reconciled first. Requires the +calls:read+ scope.
+    #
+    # @param id [String] Call identifier
+    # @return [Sendly::Call]
+    # @raise [Sendly::NotFoundError] HTTP 404 +call_not_found+ when the call
+    #   is not in your workspace
+    #
+    # @example
+    #   call = client.calls.get("6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f")
+    #   call.transcript&.each { |line| puts "#{line.speaker}: #{line.text}" }
+    def get(id)
+      encoded_id = encode_id!(id)
+      response = @client.get("/calls/#{encoded_id}")
+      Call.new(response)
+    end
+
+    # End a call. A ringing call becomes +cancelled+ (+hangup_class+
+    # "caller_cancelled") and the callee stops ringing; an active call
+    # becomes +completed+ ("normal"). Hanging up a call that has already
+    # ended returns it unchanged. Requires the +calls:write+ scope and a
+    # live key.
+    #
+    # @param id [String] Call identifier
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [Sendly::Call] The call after the hangup
+    # @raise [Sendly::NotFoundError] HTTP 404 +call_not_found+
+    #
+    # @example
+    #   call = client.calls.hangup(call.id)
+    #   puts call.status # "cancelled" or "completed"
+    def hangup(id, idempotency_key: nil)
+      encoded_id = encode_id!(id)
+      response = @client.post("/calls/#{encoded_id}/hangup", {}, idempotency_key: idempotency_key)
+      Call.new(response)
+    end
+
+    # Fetch the recording of a call. +url+ is a signed link valid for five
+    # minutes and is only set once the recording is +ready?+; fetch again
+    # for a fresh link. Requires the +calls:read+ scope.
+    #
+    # @param id [String] Call identifier
+    # @return [Sendly::CallRecording]
+    # @raise [Sendly::NotFoundError] HTTP 404 +call_not_found+
+    #
+    # @example
+    #   rec = client.calls.recording(call.id)
+    #   if rec.ready?
+    #     File.binwrite("#{call.id}.ogg", Net::HTTP.get(URI(rec.url)))
+    #   end
+    def recording(id)
+      encoded_id = encode_id!(id)
+      response = @client.get("/calls/#{encoded_id}/recording")
+      CallRecording.new(response)
+    end
+
+    private
+
+    def encode_id!(id)
+      raise ValidationError, "Call ID is required" if id.nil? || id.to_s.empty?
+
+      URI.encode_www_form_component(id)
+    end
+  end
+end

data/lib/sendly/client.rb

@@ -192,6 +192,13 @@ module Sendly
       @rcs ||= RcsResource.new(self)
     end
 
+    # Access the Calls resource (phone calls handled by your AI agents)
+    #
+    # @return [Sendly::CallsResource]
+    def calls
+      @calls ||= CallsResource.new(self)
+    end
+
     # Make a GET request
     #
     # @param path [String] API path

data/lib/sendly/numbers_resource.rb

@@ -53,9 +53,21 @@ module Sendly
                 # true when the number is scheduled for release at period end.
                 :pending_cancellation,
                 # ISO-8601 timestamp string, or nil when no release is scheduled.
-                :scheduled_release_at
+                :scheduled_release_at,
+                # true when the number can place and receive phone calls
+                # (switched on 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.
+                :voice_mode
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
+
+    VOICE_MODES = %w[none ring_dashboard agent].freeze
 
     def initialize(data)
+      @raw = data
       @id = data["id"]
       @phone_number = data["phoneNumber"] || data["phone_number"]
       @status = data["status"]
@@ -67,6 +79,13 @@ module Sendly
       @requirements_submitted_at = data["requirementsSubmittedAt"] || data["requirements_submitted_at"]
       @pending_cancellation = data.key?("pendingCancellation") ? data["pendingCancellation"] : data["pending_cancellation"]
       @scheduled_release_at = data["scheduledReleaseAt"] || data["scheduled_release_at"]
+      @voice_enabled = data.key?("voiceEnabled") ? data["voiceEnabled"] : data["voice_enabled"]
+      @voice_mode = data["voiceMode"] || data["voice_mode"]
+    end
+
+    # @return [Boolean] Whether the number can be used as the +from+ of a call
+    def voice_enabled?
+      voice_enabled == true
     end
 
     def to_h
@@ -76,7 +95,8 @@ module Sendly
         monthly_cost_cents: monthly_cost_cents, is_default: is_default,
         requirements_submitted_at: requirements_submitted_at,
         pending_cancellation: pending_cancellation,
-        scheduled_release_at: scheduled_release_at
+        scheduled_release_at: scheduled_release_at,
+        voice_enabled: voice_enabled, voice_mode: voice_mode
       }.compact
     end
   end

data/lib/sendly/version.rb

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

data/lib/sendly/webhooks.rb

@@ -99,6 +99,10 @@ module Sendly
     EVENT_CALL_STARTED                  = "call.started"
     EVENT_CALL_COMPLETED                = "call.completed"
     EVENT_CALL_RECORDING_READY          = "call.recording.ready"
+    EVENT_SHORT_CODE_ACTION_REQUIRED     = "short_code.action_required"
+    EVENT_SHORT_CODE_REJECTED            = "short_code.rejected"
+    EVENT_SHORT_CODE_FILED               = "short_code.filed"
+    EVENT_SHORT_CODE_LIVE                = "short_code.live"
 
     # Source of a list-health event. Frozen enum — new values will be
     # added in minor SDK versions, never removed.

data/lib/sendly.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendly
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Sendly
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -126,6 +126,7 @@ files:
 - lib/sendly.rb
 - lib/sendly/account_resource.rb
 - lib/sendly/business_upgrade_resource.rb
+- lib/sendly/calls_resource.rb
 - lib/sendly/campaigns_resource.rb
 - lib/sendly/client.rb
 - lib/sendly/contacts_resource.rb