sentdm 0.38.1 → 0.40.0

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

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Resources
+    class Voice
+      class Calls
+        # 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 Participants
+          # Some parameter documentations has been truncated, see
+          # {Sentdm::Models::Voice::Calls::ParticipantUpdateParams} for more details.
+          #
+          # Mutes or unmutes one participant of the conference room a live call is in, named
+          # by the participant's own call id from the participants list: send muted true to
+          # silence them, muted false to let them be heard again. Muting a participant who
+          # is already muted succeeds, as does unmuting one who is not. A participant who is
+          # not in this call's room answers 404. A call that has ended answers 409, as does
+          # a call that is not in a conference.
+          #
+          # @overload update(participant_id, id:, muted: nil, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+          #
+          # @param participant_id [String] Path param: The participant's own call id from the route, as listed by the parti
+          #
+          # @param id [String] Path param: The call id from the route, as carried by call webhooks and the call
+          #
+          # @param muted [Boolean] Body param: true to mute the participant, false to unmute them
+          #
+          # @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 [nil]
+          #
+          # @see Sentdm::Models::Voice::Calls::ParticipantUpdateParams
+          def update(participant_id, params)
+            parsed, options = Sentdm::Voice::Calls::ParticipantUpdateParams.dump_request(params)
+            id =
+              parsed.delete(:id) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+            @client.request(
+              method: :patch,
+              path: ["v3/voice/calls/%1$s/participants/%2$s", id, participant_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::Calls::ParticipantListParams} for more details.
+          #
+          # Lists who is in the conference room one of your live calls is in: each
+          # participant's own call id, who they are, whether the room mutes them, and how
+          # long they have been connected. The call itself is one of the participants. Use a
+          # participant's id to mute or remove them; it is also a call id, so GET
+          # /v3/voice/calls/{id} accepts it. A call that has ended answers 409, as does a
+          # call that is not in a conference.
+          #
+          # @overload list(id, x_profile_id: nil, request_options: {})
+          #
+          # @param id [String] The call id from the route, as carried by call webhooks and the calls list, for
+          #
+          # @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::Calls::APIResponseOfListOfCallParticipant]
+          #
+          # @see Sentdm::Models::Voice::Calls::ParticipantListParams
+          def list(id, params = {})
+            parsed, options = Sentdm::Voice::Calls::ParticipantListParams.dump_request(params)
+            @client.request(
+              method: :get,
+              path: ["v3/voice/calls/%1$s/participants", id],
+              headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
+              model: Sentdm::Voice::Calls::APIResponseOfListOfCallParticipant,
+              options: options
+            )
+          end
+
+          # Some parameter documentations has been truncated, see
+          # {Sentdm::Models::Voice::Calls::ParticipantAddParams} for more details.
+          #
+          # Dials one of your app users or a phone number into a call that is in a
+          # conference room, and answers with the participant's own call record. The
+          # participant is a call of their own: it has its own id, can be looked up and hung
+          # up, and is billed and reported through call.completed and call.failed like any
+          # other call. Every participant needs a positive balance. A phone participant is
+          # called from caller_id, which must be one of your numbers, or from the call's
+          # owning number when omitted, and needs a destination you may call. Only a call
+          # your answer connected to a conference can take participants: a call connected to
+          # a user or a number answers 409.
+          #
+          # @overload add(id, caller_id: nil, sandbox: nil, to: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+          #
+          # @param id [String] Path param: The call id from the route, as carried by call webhooks and the call
+          #
+          # @param caller_id [String, nil] Body param: The number shown to a phone participant as the caller, in E.164 form
+          #
+          # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+          #
+          # @param to [Sentdm::Models::Voice::Calls::CallParticipantTarget] Body param: A participant to add to a call
+          #
+          # @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::APIResponseOfCall]
+          #
+          # @see Sentdm::Models::Voice::Calls::ParticipantAddParams
+          def add(id, params = {})
+            parsed, options = Sentdm::Voice::Calls::ParticipantAddParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+            @client.request(
+              method: :post,
+              path: ["v3/voice/calls/%1$s/participants", id],
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
+              model: Sentdm::Voice::APIResponseOfCall,
+              options: options
+            )
+          end
+
+          # Some parameter documentations has been truncated, see
+          # {Sentdm::Models::Voice::Calls::ParticipantRemoveParams} for more details.
+          #
+          # Removes one participant from the conference room a live call is in, named by the
+          # participant's own call id from the participants list. Their leg ends and is
+          # reported through call.completed like any other call; everyone else stays
+          # connected. A participant who is not in this call's room answers 404. A call that
+          # has ended answers 409, as does a call that is not in a conference.
+          #
+          # @overload remove(participant_id, id:, sandbox: nil, x_profile_id: nil, request_options: {})
+          #
+          # @param participant_id [String] Path param: The participant's own call id from the route, as listed by the parti
+          #
+          # @param id [String] Path param: The call id from the route, as carried by call webhooks and the call
+          #
+          # @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::Calls::ParticipantRemoveParams
+          def remove(participant_id, params)
+            parsed, options = Sentdm::Voice::Calls::ParticipantRemoveParams.dump_request(params)
+            id =
+              parsed.delete(:id) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            header_params = {x_profile_id: "x-profile-id"}
+            @client.request(
+              method: :delete,
+              path: ["v3/voice/calls/%1$s/participants/%2$s", id, participant_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::Calls::ParticipantRemoveAllParams} for more details.
+          #
+          # Removes every participant from the conference room a live call is in, the call
+          # itself included. Every leg ends and is reported through call.completed like any
+          # other call. A room that is already empty answers 204 as well. A call that has
+          # ended answers 409, as does a call that is not in a conference.
+          #
+          # @overload remove_all(id, sandbox: nil, x_profile_id: nil, request_options: {})
+          #
+          # @param id [String] Path param: The call id from the route, as carried by call webhooks and the call
+          #
+          # @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::Calls::ParticipantRemoveAllParams
+          def remove_all(id, params = {})
+            parsed, options = Sentdm::Voice::Calls::ParticipantRemoveAllParams.dump_request(params)
+            header_params = {x_profile_id: "x-profile-id"}
+            @client.request(
+              method: :delete,
+              path: ["v3/voice/calls/%1$s/participants", id],
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
+              model: NilClass,
+              options: options
+            )
+          end
+
+          # @api private
+          #
+          # @param client [Sentdm::Client]
+          def initialize(client:)
+            @client = client
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,269 @@
+# 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 Calls
+        # 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`.
+        # @return [Sentdm::Resources::Voice::Calls::Participants]
+        attr_reader :participants
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::CallRetrieveParams} for more details.
+        #
+        # Retrieves one of your calls by id: the parties, the owning number, the phone
+        # number the call was connected to and the caller id it showed, the current status
+        # with its failure reason, duration, price with the billed legs and what each
+        # cost, recording availability, and a timeline of when the call entered each
+        # status.
+        #
+        # @overload retrieve(id, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] The call id from the route, as carried by call webhooks and the calls list, for
+        #
+        # @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::APIResponseOfCall]
+        #
+        # @see Sentdm::Models::Voice::CallRetrieveParams
+        def retrieve(id, params = {})
+          parsed, options = Sentdm::Voice::CallRetrieveParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: ["v3/voice/calls/%1$s", id],
+            headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
+            model: Sentdm::Voice::APIResponseOfCall,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::CallListParams} for more details.
+        #
+        # Retrieves a paginated list of your calls, most recent first. Filter by
+        # direction, status, the owning number, the mode (inapp, or agent for calls your
+        # voice agents answered), the agent that answered, and the time the call started
+        # (from and to are inclusive). Each call carries the phone number it was connected
+        # to, the caller id it showed, and the billed legs with what each cost. Use the
+        # call webhooks for real-time updates; this list is for looking calls up
+        # afterwards.
+        #
+        # @overload list(agent_id: nil, direction: nil, from: nil, mode: nil, number: nil, page: nil, page_size: nil, status: nil, to: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param agent_id [String, nil] Query param: Optional filter on the voice agent that answered the call, such as
+        #
+        # @param direction [String, nil] Query param: Optional direction filter: outbound for calls placed from your app,
+        #
+        # @param from [Time, nil] Query param: Only calls started at or after this time (ISO 8601)
+        #
+        # @param mode [String, nil] Query param: Optional mode filter: inapp for calls routed by your number's callb
+        #
+        # @param number [String, nil] Query param: Optional filter on the number that owns the call, one of your voice
+        #
+        # @param page [Integer] Query param: Page number (1-indexed)
+        #
+        # @param page_size [Integer] Query param: Number of items per page
+        #
+        # @param status [String, nil] Query param: Optional status filter: initiated, ringing, answered, completed, fa
+        #
+        # @param to [Time, nil] Query param: Only calls started at or before this time (ISO 8601)
+        #
+        # @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::CallsPage<Sentdm::Models::Voice::Call>]
+        #
+        # @see Sentdm::Models::Voice::CallListParams
+        def list(params = {})
+          query_params = [:agent_id, :direction, :from, :mode, :number, :page, :page_size, :status, :to]
+          parsed, options = Sentdm::Voice::CallListParams.dump_request(params)
+          query = Sentdm::Internal::Util.encode_query_params(parsed.slice(*query_params))
+          @client.request(
+            method: :get,
+            path: "v3/voice/calls",
+            query: query,
+            headers: parsed.except(*query_params).transform_keys(x_profile_id: "x-profile-id"),
+            page: Sentdm::Internal::CallsPage,
+            model: Sentdm::Voice::Call,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::CallHangupParams} for more details.
+        #
+        # Ends one of your live calls. The call then ends the way any other call does once
+        # the disconnect is reported: an answered call as COMPLETED with call.completed, a
+        # call still ringing as NO_ANSWER, REJECTED or FAILED with call.failed. A call
+        # that has already ended answers 409, as do a call with no phone leg, such as one
+        # between two app users, and a call one of your voice agents answers.
+        #
+        # @overload hangup(id, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] Path param: The call id from the route, as carried by call webhooks and the call
+        #
+        # @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 [nil]
+        #
+        # @see Sentdm::Models::Voice::CallHangupParams
+        def hangup(id, params = {})
+          parsed, options = Sentdm::Voice::CallHangupParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :post,
+            path: ["v3/voice/calls/%1$s/hangup", 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::CallListRecordingsParams} for more details.
+        #
+        # Returns pre-signed links to the recordings of one of your calls, each valid
+        # until its url_expires_at. A recording appears once the call was recorded, by a
+        # connect answer with record set, a startRecording instruction or the recordings
+        # command, and the call.recording_ready webhook has been sent; until then, and for
+        # a call that was never recorded, the list is empty. A call recorded more than
+        # once lists every recording, oldest first, each under the recording_id its
+        # call.recording_ready webhook carried.
+        #
+        # @overload list_recordings(id, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] The call id from the route, as carried by call webhooks and the calls list, for
+        #
+        # @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::APIResponseOfCallRecordings]
+        #
+        # @see Sentdm::Models::Voice::CallListRecordingsParams
+        def list_recordings(id, params = {})
+          parsed, options = Sentdm::Voice::CallListRecordingsParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: ["v3/voice/calls/%1$s/recordings", id],
+            headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
+            model: Sentdm::Voice::APIResponseOfCallRecordings,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::CallRecordParams} for more details.
+        #
+        # Starts or stops recording one of your live calls. Use start to begin recording
+        # mid-call, or stop to end a recording, whether it was started here or by a
+        # connect answer with record set. A call that has already ended answers 409, as do
+        # a call with no phone leg, such as one between two app users, and a call one of
+        # your voice agents answers, neither of which can be recorded this way.
+        #
+        # @overload record(id, action: nil, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] Path param: The call id from the route, as carried by call webhooks and the call
+        #
+        # @param action [String] Body param: start to begin recording, stop to end it
+        #
+        # @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 [nil]
+        #
+        # @see Sentdm::Models::Voice::CallRecordParams
+        def record(id, params = {})
+          parsed, options = Sentdm::Voice::CallRecordParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :post,
+            path: ["v3/voice/calls/%1$s/recordings", id],
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Sentdm::Client]
+        def initialize(client:)
+          @client = client
+          @participants = Sentdm::Resources::Voice::Calls::Participants.new(client: client)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# 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 Catalogue
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::CatalogueListParams} for more details.
+        #
+        # The names a voice agent's `speech.voice` and `speech.language` accept, with the
+        # default marked. The list grows as voices are added; a name is never removed
+        # without notice.
+        #
+        # @overload list(x_profile_id: nil, request_options: {})
+        #
+        # @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::APIResponseOfVoiceCatalogue]
+        #
+        # @see Sentdm::Models::Voice::CatalogueListParams
+        def list(params = {})
+          parsed, options = Sentdm::Voice::CatalogueListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: "v3/voice/voices",
+            headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
+            model: Sentdm::Voice::APIResponseOfVoiceCatalogue,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Sentdm::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# 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 Tokens
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Voice::TokenCreateParams} for more details.
+        #
+        # Mints a short-lived token for one of your app users. Call this from your backend
+        # and return the token to your app, which passes it to the voice client SDK to
+        # register. The identity is bound to the given number, or to your default app-call
+        # number when omitted, and calls placed by that identity are routed through the
+        # bound number. Minting again re-binds the identity, so an identity can move
+        # between numbers.
+        #
+        # @overload create(identity: nil, number: nil, sandbox: nil, ttl: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param identity [String] Body param: Your identifier for the app user, such as an agent or account id. Le
+        #
+        # @param number [String, nil] Body param: One of your voice-enabled phone numbers in E.164 format. Calls place
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param ttl [Integer, nil] Body param: Token lifetime in seconds. Defaults to 600 and cannot exceed 3600.
+        #
+        # @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::APIResponseOfVoiceToken]
+        #
+        # @see Sentdm::Models::Voice::TokenCreateParams
+        def create(params = {})
+          parsed, options = Sentdm::Voice::TokenCreateParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :post,
+            path: "v3/voice/tokens",
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: Sentdm::Voice::APIResponseOfVoiceToken,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Sentdm::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end