sentdm 0.39.0 → 0.40.0

data/lib/sentdm/models/webhook_response.rb

@@ -10,6 +10,8 @@ module Sentdm
       optional :id, String
 
       # @!attribute consecutive_failures
+      #   Failed attempts since the last success. Version 1 only: always 0 on a version 2
+      #   webhook, whose deliveries are in its events (GET /v3/webhooks/{id}/events).
       #
       #   @return [Integer, nil]
       optional :consecutive_failures, Integer
@@ -53,12 +55,24 @@ module Sentdm
       #   @return [Boolean, nil]
       optional :is_active, Sentdm::Internal::Type::Boolean
 
+      # @!attribute is_inheritable
+      #   Whether the webhook also receives its organization's sender profiles' events,
+      #   and each profile sees it and reads the events about itself. Always false on a
+      #   version 1 webhook.
+      #
+      #   @return [Boolean, nil]
+      optional :is_inheritable, Sentdm::Internal::Type::Boolean
+
       # @!attribute last_delivery_attempt_at
+      #   When the webhook was last attempted. Version 1 only: always null on a version 2
+      #   webhook.
       #
       #   @return [Time, nil]
       optional :last_delivery_attempt_at, Time, nil?: true
 
       # @!attribute last_successful_delivery_at
+      #   When the webhook last received an event. Version 1 only: always null on a
+      #   version 2 webhook.
       #
       #   @return [Time, nil]
       optional :last_successful_delivery_at, Time, nil?: true
@@ -68,6 +82,16 @@ module Sentdm
       #   @return [Integer, nil]
       optional :retry_count, Integer
 
+      # @!attribute sender_profile
+      #   The events a version 1 webhook's sender profile clones receive, as a response
+      #   reports them.
+      #
+      #   Its own type, field for field the same as the request's sender_profile. A
+      #   response is not a request, whatever it carries.
+      #
+      #   @return [Sentdm::Models::WebhookResponse::SenderProfile, nil]
+      optional :sender_profile, -> { Sentdm::WebhookResponse::SenderProfile }, nil?: true
+
       # @!attribute signing_secret
       #
       #   @return [String, nil]
@@ -83,13 +107,20 @@ module Sentdm
       #   @return [Time, nil]
       optional :updated_at, Time, nil?: true
 
-      # @!method initialize(id: nil, consecutive_failures: nil, created_at: nil, customer_id: nil, display_name: nil, endpoint_url: nil, event_filters: nil, event_types: nil, is_active: nil, last_delivery_attempt_at: nil, last_successful_delivery_at: nil, retry_count: nil, signing_secret: nil, timeout_seconds: nil, updated_at: nil)
+      # @!attribute webhook_version
+      #   Who delivers the webhook: 1 the older delivery, which will be retired, or 2
+      #   Svix. A webhook is created as version 2 unless the request asks for 1.
+      #
+      #   @return [Integer, nil]
+      optional :webhook_version, Integer
+
+      # @!method initialize(id: nil, consecutive_failures: nil, created_at: nil, customer_id: nil, display_name: nil, endpoint_url: nil, event_filters: nil, event_types: nil, is_active: nil, is_inheritable: nil, last_delivery_attempt_at: nil, last_successful_delivery_at: nil, retry_count: nil, sender_profile: nil, signing_secret: nil, timeout_seconds: nil, updated_at: nil, webhook_version: nil)
       #   Some parameter documentations has been truncated, see
       #   {Sentdm::Models::WebhookResponse} for more details.
       #
       #   @param id [String]
       #
-      #   @param consecutive_failures [Integer]
+      #   @param consecutive_failures [Integer] Failed attempts since the last success. Version 1 only: always 0 on a version 2
       #
       #   @param created_at [Time]
       #
@@ -105,17 +136,48 @@ module Sentdm
       #
       #   @param is_active [Boolean]
       #
-      #   @param last_delivery_attempt_at [Time, nil]
+      #   @param is_inheritable [Boolean] Whether the webhook also receives its organization's sender profiles' events, an
       #
-      #   @param last_successful_delivery_at [Time, nil]
+      #   @param last_delivery_attempt_at [Time, nil] When the webhook was last attempted. Version 1 only: always null on a version 2
+      #
+      #   @param last_successful_delivery_at [Time, nil] When the webhook last received an event. Version 1 only: always null on a versio
       #
       #   @param retry_count [Integer]
       #
+      #   @param sender_profile [Sentdm::Models::WebhookResponse::SenderProfile, nil] The events a version 1 webhook's sender profile clones receive, as a response re
+      #
       #   @param signing_secret [String, nil]
       #
       #   @param timeout_seconds [Integer]
       #
       #   @param updated_at [Time, nil]
+      #
+      #   @param webhook_version [Integer] Who delivers the webhook: 1 the older delivery, which will be retired, or 2 Svix
+
+      # @see Sentdm::Models::WebhookResponse#sender_profile
+      class SenderProfile < Sentdm::Internal::Type::BaseModel
+        # @!attribute event_filters
+        #
+        #   @return [Hash{Symbol=>Array<String>}, nil]
+        optional :event_filters,
+                 Sentdm::Internal::Type::HashOf[Sentdm::Internal::Type::ArrayOf[String]],
+                 nil?: true
+
+        # @!attribute event_types
+        #
+        #   @return [Array<String>, nil]
+        optional :event_types, Sentdm::Internal::Type::ArrayOf[String]
+
+        # @!method initialize(event_filters: nil, event_types: nil)
+        #   The events a version 1 webhook's sender profile clones receive, as a response
+        #   reports them.
+        #
+        #   Its own type, field for field the same as the request's sender_profile. A
+        #   response is not a request, whatever it carries.
+        #
+        #   @param event_filters [Hash{Symbol=>Array<String>}, nil]
+        #   @param event_types [Array<String>]
+      end
     end
   end
 end

data/lib/sentdm/models/webhook_update_params.rb

@@ -34,6 +34,14 @@ module Sentdm
       #   @return [Array<String>, nil]
       optional :event_types, Sentdm::Internal::Type::ArrayOf[String]
 
+      # @!attribute is_inheritable
+      #   Makes this webhook inheritable by the organization's sender profiles (see
+      #   create), or stops it being inheritable. Omit or pass null to keep it as it is.
+      #   Only a version 2 webhook can be inheritable.
+      #
+      #   @return [Boolean, nil]
+      optional :is_inheritable, Sentdm::Internal::Type::Boolean, nil?: true
+
       # @!attribute retry_count
       #
       #   @return [Integer, nil]
@@ -48,7 +56,8 @@ module Sentdm
 
       # @!attribute sender_profile
       #   Request-only: the events an organization webhook's sender profile clones
-      #   receive, one clone per existing and future profile. Responses never return it.
+      #   receive, one clone per existing and future profile. A version 1 webhook's
+      #   responses report it as WebhookSenderProfileV3Response.
       #
       #   @return [Sentdm::Models::WebhookUpdateParams::SenderProfile, nil]
       optional :sender_profile, -> { Sentdm::WebhookUpdateParams::SenderProfile }, nil?: true
@@ -68,7 +77,7 @@ module Sentdm
       #   @return [String, nil]
       optional :x_profile_id, String
 
-      # @!method initialize(id:, display_name: nil, endpoint_url: nil, event_filters: nil, event_types: nil, retry_count: nil, sandbox: nil, sender_profile: nil, timeout_seconds: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+      # @!method initialize(id:, display_name: nil, endpoint_url: nil, event_filters: nil, event_types: nil, is_inheritable: nil, retry_count: nil, sandbox: nil, sender_profile: nil, timeout_seconds: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {Sentdm::Models::WebhookUpdateParams} for more details.
       #
@@ -82,6 +91,8 @@ module Sentdm
       #
       #   @param event_types [Array<String>]
       #
+      #   @param is_inheritable [Boolean, nil] Makes this webhook inheritable by the organization's sender profiles (see create
+      #
       #   @param retry_count [Integer]
       #
       #   @param sandbox [Boolean] Sandbox flag - when true, the operation is simulated without side effects
@@ -111,7 +122,8 @@ module Sentdm
 
         # @!method initialize(event_filters: nil, event_types: nil)
         #   Request-only: the events an organization webhook's sender profile clones
-        #   receive, one clone per existing and future profile. Responses never return it.
+        #   receive, one clone per existing and future profile. A version 1 webhook's
+        #   responses report it as WebhookSenderProfileV3Response.
         #
         #   @param event_filters [Hash{Symbol=>Array<String>}, nil]
         #   @param event_types [Array<String>]

data/lib/sentdm/resources/channels/voice.rb

@@ -47,6 +47,16 @@ module Sentdm
         # question the way you verify a webhook. `POST /v3/channels/voice/{number}/test`
         # sends a test question and reports the verdict.
         #
+        # Send `agent_id` instead of `callback_url`, or with it, to have one of your voice
+        # agents (`GET /v3/voice/agents`) answer calls to the number. The agent wins over
+        # the callback URL for calls to the number; calls your app places from it still
+        # follow your app. `routes_to` in the response says which answers, and reads
+        # `agent_pending` while the number is still being moved to the agent. Calls follow
+        # the move within about an hour, as the provider applies it on its own clock.
+        # While numbers cannot be bound to agents, a request with `agent_id` is refused
+        # with `502` before any number is obtained or anything is written; send
+        # `callback_url` instead.
+        #
         # Your first voice number becomes the line app-originated calls are placed from
         # when a voice token names no number; send `default_for_app_calls: true` to give
         # that role to another number. A number you turned off earlier is turned back on,
@@ -59,12 +69,14 @@ module Sentdm
         # With `sandbox: true` the request is validated and a simulated number reported
         # with `202`; nothing is written and no number is bought.
         #
-        # @overload create(callback_url:, area_code: nil, default_for_app_calls: nil, number: nil, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        # @overload create(agent_id: nil, area_code: nil, callback_url: nil, default_for_app_calls: nil, number: nil, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
         #
-        # @param callback_url [String] Body param: Where Sent asks what to do with each call on this number: an absolut
+        # @param agent_id [String, nil] Body param: One of your voice agents (GET /v3/voice/agents), such as
         #
         # @param area_code [String, nil] Body param: The US area code a new number should be in, as 212. Only for a reque
         #
+        # @param callback_url [String, nil] Body param: Where Sent asks what to do with each call on this number: an absolut
+        #
         # @param default_for_app_calls [Boolean, nil] Body param: Make this the line app-originated calls are placed from when a voice
         #
         # @param number [String, nil] Body param: One of your phone numbers, in E.164 format. Leave the field out enti
@@ -80,7 +92,7 @@ module Sentdm
         # @return [Sentdm::Models::Channels::APIResponseOfVoiceNumberCreated]
         #
         # @see Sentdm::Models::Channels::VoiceCreateParams
-        def create(params)
+        def create(params = {})
           parsed, options = Sentdm::Channels::VoiceCreateParams.dump_request(params)
           header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
           @client.request(
@@ -136,18 +148,23 @@ module Sentdm
         #
         # ## What it changes
         #
-        # | Body                                          | Effect                                                                                                       |
-        # | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-        # | `"status": "ACTIVE"`                          | turns calls on again for a number you turned off; the callback URL and the secret it had are kept            |
-        # | `"status": "INACTIVE"`                        | turns calls off; the callback URL and the secret stay on the number                                          |
-        # | `"default_for_app_calls": true`               | makes this the line app-originated calls are placed from when a voice token names no number                  |
-        # | `"callback_url": "https://example.com/voice"` | replaces where Sent asks what to do with each call on the number; the signing secret and the status are kept |
-        # | key omitted                                   | left exactly as it is                                                                                        |
+        # | Body                                          | Effect                                                                                                                                                                                                                                                                                                                                                                                                     |
+        # | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+        # | `"status": "ACTIVE"`                          | turns calls on again for a number you turned off; the callback URL and the secret it had are kept                                                                                                                                                                                                                                                                                                          |
+        # | `"status": "INACTIVE"`                        | turns calls off; the callback URL and the secret stay on the number                                                                                                                                                                                                                                                                                                                                        |
+        # | `"default_for_app_calls": true`               | makes this the line app-originated calls are placed from when a voice token names no number                                                                                                                                                                                                                                                                                                                |
+        # | `"callback_url": "https://example.com/voice"` | replaces where Sent asks what to do with each call on the number; the signing secret and the status are kept                                                                                                                                                                                                                                                                                               |
+        # | `"agent_id": "agent_…"`                       | one of your voice agents answers calls to the number, within about an hour of the change (the provider applies the move on its own clock, and `routes_to` reads `agent` as soon as it has recorded it); it wins over `callback_url` for calls to the number, and calls your app places from it still follow your app. `routes_to` reads `agent_pending` while the number is still being moved to the agent |
+        # | `"agent_id": null`                            | unbinds the agent, so `callback_url` answers calls to the number again                                                                                                                                                                                                                                                                                                                                     |
+        # | key omitted                                   | left exactly as it is                                                                                                                                                                                                                                                                                                                                                                                      |
         #
         # `status` is matched ignoring case. Any combination is accepted:
         # `status: "ACTIVE"` with `default_for_app_calls: true` turns a number on as the
-        # new default, and a `callback_url` sent with either status is written too. A body
-        # that names none of the three is refused.
+        # new default, and a `callback_url` sent with either status is written too.
+        # `agent_id` is applied first, so a refusal to move the number to or from the
+        # agent leaves everything as it was, and the `409` and `400` refusals below are
+        # decided before anything is written, so they leave everything as it was too. A
+        # body that names none of them is refused.
         #
         # A number can be on without a callback URL: calls placed from your app then
         # connect straight to the number or user they dial, and calls to the number are
@@ -166,8 +183,12 @@ module Sentdm
         # **Making an inactive number the default is `400`.** Send `status: "ACTIVE"` in
         # the same call.
         #
-        # **A number you never turned voice on for is `404`.** Add it with
-        # `POST /v3/channels/voice`.
+        # **A number you never turned voice on for is `404`**, and so is an `agent_id`
+        # that is not one of your agents. Add the number with `POST /v3/channels/voice`.
+        #
+        # **`502` means the number could not be moved to or from the agent**, or an
+        # `agent_id` was sent while numbers cannot be bound to agents; nothing was
+        # written.
         #
         # The number is the E.164 value in the path with the plus sign URL-encoded
         # (`%2B`).
@@ -176,10 +197,12 @@ module Sentdm
         # stored number and the number is reported with `200` as it would read after the
         # change.
         #
-        # @overload update(number, callback_url: nil, default_for_app_calls: nil, sandbox: nil, status: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        # @overload update(number, agent_id: nil, callback_url: nil, default_for_app_calls: nil, sandbox: nil, status: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
         #
         # @param number [String] Path param: The number in E.164 format with the plus sign URL-encoded, e.g. %2B1
         #
+        # @param agent_id [String, nil] Body param: One of your voice agents, such as agent_9f2ab000-0000-4000-8000-0000
+        #
         # @param callback_url [String, nil] Body param: A new callback URL for the number, active or not: an absolute HTTP o
         #
         # @param default_for_app_calls [Boolean, nil] Body param: true makes this the line app-originated calls are placed from when a

data/lib/sentdm/resources/profiles/campaigns.rb

@@ -66,8 +66,9 @@ module Sentdm
         # which models a profile's markets, compliance, brand, campaigns and billing
         # explicitly.
         #
-        # Updates an existing campaign under the brand of the specified profile. Cannot
-        # update campaigns that have already been submitted to TCR.
+        # Updates an existing campaign under the brand of the specified profile. Once the
+        # campaign has been submitted to TCR its volume can no longer move between low
+        # volume (under 2,000 messages a day) and high volume.
         #
         # @overload update(campaign_id, profile_id:, campaign:, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
         #

data/lib/sentdm/resources/voice/agents.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Resources
+    class Voice
+      # Phone calls from the numbers you hold, driven by your own callback URL.
+      #
+      # `POST /v3/channels/voice` enables a number for calls, with the callback URL Sent
+      # asks what to do with each call on it, and `POST /v3/voice/tokens` mints a
+      # short-lived token that lets a user of your app place and receive calls as that
+      # number. When a call arrives or a caller presses a key, a signed question is
+      # POSTed to the callback URL and the answer decides the call;
+      # `POST /v3/channels/voice/{number}/test` checks the URL answers the way we need
+      # before a real call reaches it, and
+      # `POST /v3/channels/voice/{number}/rotate-secret` replaces the signing secret.
+      # The call events themselves (`call.completed` and the rest) arrive through your
+      # webhooks.
+      #
+      # Every call is a record under `/v3/voice/calls`: read it, list its recordings
+      # once one is ready, hang it up, start or stop recording, and add, mute or remove
+      # conference participants while it is live. A leg to a phone number runs for at
+      # most what your balance affords at the destination's rate.
+      #
+      # **Voice agents.** `POST /v3/voice/agents` creates an agent that answers calls
+      # through the Sent Voice Gateway: `session_type` says whether Sent carries the
+      # call as text (speech recognised and spoken for the agent) or as audio,
+      # `websocket_url` is where the gateway dials the agent for each call (leave it out
+      # and the agent dials in with your API key), and `tools`, `transfer_targets`,
+      # `fallback` and `limits` say what it may do on a call. The agent's
+      # `signing_secret` is shown on create and on
+      # `POST /v3/voice/agents/{id}/rotate-secret` only. Voices and languages for text
+      # sessions come from `GET /v3/voice/voices`. A number takes calls to an agent once
+      # it is bound to it on `/v3/channels/voice`.
+      class Agents
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::AgentCreateParams} for more details.
+        #
+        # Creates an agent that answers phone calls through the Sent Voice Gateway.
+        # `session_type` says whether Sent carries the call as text (the caller's speech
+        # recognised for the agent, the agent's text spoken) or as audio. With
+        # `websocket_url` the gateway dials your agent for each call and signs the
+        # handshake with the `signing_secret` this response returns; without it, your
+        # agent dials in with your API key and this agent's `id`.
+        #
+        # `tools`, `transfer_targets`, `fallback` and `limits` say what the agent may do
+        # on a call. Voices and languages for text sessions come from
+        # `GET /v3/voice/voices`. Calls reach the agent once a number is bound to it on
+        # `/v3/channels/voice`.
+        #
+        # `signing_secret` is shown here and on `POST /v3/voice/agents/{id}/rotate-secret`
+        # only; store it now. With `sandbox: true` the request is validated and the agent
+        # reported with `202`; nothing is written.
+        #
+        # @overload create(audio: nil, fallback: nil, greeting: nil, limits: nil, name: nil, sandbox: nil, session_type: nil, speech: nil, tools: nil, transcripts: nil, transfer_targets: nil, websocket_url: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param audio [Sentdm::Models::Voice::VoiceAgentAudioSpec, nil] Body param: Audio sessions only: the sound format.
+        #
+        # @param fallback [Sentdm::Models::Voice::VoiceAgentPartySpec, nil] Body param: Who takes the call when the agent cannot: a phone number (kind: numb
+        #
+        # @param greeting [String, nil] Body param: Text sessions only: what the caller hears as soon as the call is ans
+        #
+        # @param limits [Sentdm::Models::Voice::VoiceAgentLimitsSpec, nil] Body param
+        #
+        # @param name [String, nil] Body param: A name for your own reference, 1 to 100 characters.
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param session_type [String, nil] Body param: text: Sent turns the caller's speech into text and the agent's text
+        #
+        # @param speech [Sentdm::Models::Voice::VoiceAgentSpeechSpec, nil] Body param: Text sessions only: how the caller is spoken to and listened to.
+        #
+        # @param tools [Array<String>, nil] Body param: What the agent may do to the call: any of transfer, hangup, send_dtm
+        #
+        # @param transcripts [Sentdm::Models::Voice::VoiceAgentTranscriptsSpec, nil] Body param
+        #
+        # @param transfer_targets [Array<Sentdm::Models::Voice::VoiceAgentPartySpec>, nil] Body param: Where the agent may transfer a call to, up to 20 parties: a phone nu
+        #
+        # @param websocket_url [String, nil] Body param: Where the gateway connects to the agent for each call: an absolute w
+        #
+        # @param idempotency_key [String] Header param: Unique key to ensure idempotent request processing. Must be 1-255
+        #
+        # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Sentdm::Models::Voice::APIResponseOfVoiceAgent]
+        #
+        # @see Sentdm::Models::Voice::AgentCreateParams
+        def create(params = {})
+          parsed, options = Sentdm::Voice::AgentCreateParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :post,
+            path: "v3/voice/agents",
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: Sentdm::Voice::APIResponseOfVoiceAgent,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::AgentRetrieveParams} for more details.
+        #
+        # The agent as stored, without its signing secret.
+        #
+        # @overload retrieve(id, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] The agent id, such as agent_9f2ab000-0000-4000-8000-000000000001
+        #
+        # @param x_profile_id [String] Profile UUID to scope the request to a child profile. Only organization API keys
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Sentdm::Models::Voice::APIResponseOfVoiceAgent]
+        #
+        # @see Sentdm::Models::Voice::AgentRetrieveParams
+        def retrieve(id, params = {})
+          parsed, options = Sentdm::Voice::AgentRetrieveParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: ["v3/voice/agents/%1$s", id],
+            headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
+            model: Sentdm::Voice::APIResponseOfVoiceAgent,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::AgentUpdateParams} for more details.
+        #
+        # Changes the fields you name and answers with the agent as stored, the same shape
+        # `GET` returns.
+        #
+        # A key left out is left alone. A key sent as `null` clears an optional field
+        # (`websocket_url` makes the agent dial in, `greeting` and `fallback` go,
+        # `speech`, `audio`, `tools`, `limits` and `transcripts` return to their
+        # defaults). A key sent with a value replaces that field whole: send the whole
+        # `limits` object, not one of its keys. Changing `session_type` drops `speech`,
+        # `audio` and `greeting` unless the body sends them, since the other type cannot
+        # carry them. The result is checked like a new agent, and a body that changes
+        # nothing is `400`.
+        #
+        # With `sandbox: true` nothing is written: the request is validated against the
+        # stored agent and the agent is reported with `200` as it would read after the
+        # change.
+        #
+        # @overload update(id, audio: nil, fallback: nil, greeting: nil, limits: nil, name: nil, sandbox: nil, session_type: nil, speech: nil, tools: nil, transcripts: nil, transfer_targets: nil, websocket_url: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] Path param: The agent id, such as agent_9f2ab000-0000-4000-8000-000000000001
+        #
+        # @param audio [Sentdm::Models::Voice::VoiceAgentAudioSpec, nil] Body param: Audio sessions: { sample_rate }; null restores the default.
+        #
+        # @param fallback [Sentdm::Models::Voice::VoiceAgentPartySpec, nil] Body param: A new fallback party, or null for none.
+        #
+        # @param greeting [String, nil] Body param: A new greeting, or null for none.
+        #
+        # @param limits [Sentdm::Models::Voice::VoiceAgentLimitsSpec, nil] Body param: The whole limits object; null restores the defaults.
+        #
+        # @param name [String] Body param: A new name, 1 to 100 characters.
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param session_type [String] Body param: text or audio. Changing it drops the settings the other type cannot
+        #
+        # @param speech [Sentdm::Models::Voice::VoiceAgentSpeechSpec, nil] Body param: Text sessions: { setting, voice, language }, replaced whole; null re
+        #
+        # @param tools [Array<String>, nil] Body param: The whole list of tools; null restores the default.
+        #
+        # @param transcripts [Sentdm::Models::Voice::VoiceAgentTranscriptsSpec, nil] Body param: The whole transcripts object; null restores the defaults.
+        #
+        # @param transfer_targets [Array<Sentdm::Models::Voice::VoiceAgentPartySpec>, nil] Body param: The whole list of parties; null clears it.
+        #
+        # @param websocket_url [String, nil] Body param: A new wss:// URL, or null for an agent that dials in.
+        #
+        # @param idempotency_key [String] Header param: Unique key to ensure idempotent request processing. Must be 1-255
+        #
+        # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Sentdm::Models::Voice::APIResponseOfVoiceAgent]
+        #
+        # @see Sentdm::Models::Voice::AgentUpdateParams
+        def update(id, params = {})
+          parsed, options = Sentdm::Voice::AgentUpdateParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :patch,
+            path: ["v3/voice/agents/%1$s", id],
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: Sentdm::Voice::APIResponseOfVoiceAgent,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::AgentListParams} for more details.
+        #
+        # Your voice agents, newest first. `page` and `page_size` (1 to 100, default 20)
+        # page the list. Signing secrets are never listed.
+        #
+        # @overload list(page: nil, page_size: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param page [Integer] Query param: Page number, from 1
+        #
+        # @param page_size [Integer] Query param
+        #
+        # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Sentdm::Internal::VoiceAgentsPage<Sentdm::Models::Voice::VoiceAgent>]
+        #
+        # @see Sentdm::Models::Voice::AgentListParams
+        def list(params = {})
+          query_params = [:page, :page_size]
+          parsed, options = Sentdm::Voice::AgentListParams.dump_request(params)
+          query = Sentdm::Internal::Util.encode_query_params(parsed.slice(*query_params))
+          @client.request(
+            method: :get,
+            path: "v3/voice/agents",
+            query: query,
+            headers: parsed.except(*query_params).transform_keys(x_profile_id: "x-profile-id"),
+            page: Sentdm::Internal::VoiceAgentsPage,
+            model: Sentdm::Voice::VoiceAgent,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::AgentDeleteParams} for more details.
+        #
+        # Removes the agent. Calls it already took keep their `agent_id`.
+        #
+        # An agent that one of your voice numbers routes to, or that another of your
+        # agents lists in `transfer_targets`, is not deleted: the answer is `409` with a
+        # message naming those numbers and agents. Unbind the numbers
+        # (`PATCH /v3/channels/voice/{number}` with `"agent_id": null`), take the agent
+        # out of the others' `transfer_targets` or delete them, and try again.
+        #
+        # With `sandbox: true` nothing is written: the agent is looked up and the answer
+        # is the one a real delete would give.
+        #
+        # @overload delete(id, sandbox: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] Path param: The agent id, such as agent_9f2ab000-0000-4000-8000-000000000001
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see Sentdm::Models::Voice::AgentDeleteParams
+        def delete(id, params = {})
+          parsed, options = Sentdm::Voice::AgentDeleteParams.dump_request(params)
+          header_params = {x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :delete,
+            path: ["v3/voice/agents/%1$s", id],
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::AgentRotateSecretParams} for more details.
+        #
+        # Generates a new `signing_secret` for the agent and returns it. The previous
+        # secret stops signing immediately, so update your agent before the next call
+        # reaches it.
+        #
+        # With `sandbox: true` a secret is generated and returned with `202`, and nothing
+        # is written.
+        #
+        # @overload rotate_secret(id, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] Path param: The agent id, such as agent_9f2ab000-0000-4000-8000-000000000001
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param idempotency_key [String] Header param: Unique key to ensure idempotent request processing. Must be 1-255
+        #
+        # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Sentdm::Models::Voice::APIResponseOfVoiceAgentSecret]
+        #
+        # @see Sentdm::Models::Voice::AgentRotateSecretParams
+        def rotate_secret(id, params = {})
+          parsed, options = Sentdm::Voice::AgentRotateSecretParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :post,
+            path: ["v3/voice/agents/%1$s/rotate-secret", id],
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: Sentdm::Voice::APIResponseOfVoiceAgentSecret,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Sentdm::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/sentdm/resources/voice/calls/participants.rb

@@ -21,6 +21,17 @@ module Sentdm
         # once one is ready, hang it up, start or stop recording, and add, mute or remove
         # conference participants while it is live. A leg to a phone number runs for at
         # most what your balance affords at the destination's rate.
+        #
+        # **Voice agents.** `POST /v3/voice/agents` creates an agent that answers calls
+        # through the Sent Voice Gateway: `session_type` says whether Sent carries the
+        # call as text (speech recognised and spoken for the agent) or as audio,
+        # `websocket_url` is where the gateway dials the agent for each call (leave it out
+        # and the agent dials in with your API key), and `tools`, `transfer_targets`,
+        # `fallback` and `limits` say what it may do on a call. The agent's
+        # `signing_secret` is shown on create and on
+        # `POST /v3/voice/agents/{id}/rotate-secret` only. Voices and languages for text
+        # sessions come from `GET /v3/voice/voices`. A number takes calls to an agent once
+        # it is bound to it on `/v3/channels/voice`.
         class Participants
           # Some parameter documentations has been truncated, see
           # {Sentdm::Models::Voice::Calls::ParticipantUpdateParams} for more details.