telnyx 5.171.0 → 5.173.0

data/lib/telnyx/resources/ai/avatars.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    class AI
+      # Create and manage real-time AI avatars
+      class Avatars
+        # Uploads an image, validates its file type, size, safe decoding, and resolution,
+        # stores it in Telnyx-managed private storage, and creates an avatar owned by the
+        # authenticated organization. Creating an avatar does not update an AI Assistant;
+        # use the returned ID separately wherever the avatar is consumed. The avatar image
+        # is stored independently from the rendering model and background, which are
+        # selected where the avatar is consumed. Supported image types are JPEG, PNG, and
+        # WebP. Images may be up to 10 MiB, must be between 256 and 8192 pixels on each
+        # side, and may contain at most 40 megapixels. A per-organization custom-avatar
+        # quota applies; the create request returns an error when the quota is reached.
+        # For best results, use a 16:9 landscape image, preferably 1920 by 1080 pixels and
+        # at least 1280 by 720 pixels. Show one centered, front-facing person from the
+        # shoulders up, keep the full head and hair visible with space around it, and use
+        # a sharp, evenly lit image with unobstructed eyes and mouth. Use a transparent
+        # PNG or WebP when the avatar will be combined with a selectable background. These
+        # composition recommendations are not enforced in the first release; the first
+        # release does not validate the number of faces, pose, or image content.
+        #
+        # @overload create(image_file:, name:, request_options: {})
+        #
+        # @param image_file [Pathname, StringIO, IO, String, Telnyx::FilePart] JPEG, PNG, or WebP image file. The maximum file size is 10 MiB.
+        #
+        # @param name [String] Customer-facing name of the custom avatar.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::AI::AvatarResponse]
+        #
+        # @see Telnyx::Models::AI::AvatarCreateParams
+        def create(params)
+          parsed, options = Telnyx::AI::AvatarCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "ai/avatars",
+            headers: {"content-type" => "multipart/form-data"},
+            body: parsed,
+            model: Telnyx::AI::AvatarResponse,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::AI::AvatarRetrieveParams} for more details.
+        #
+        # Returns a Telnyx stock avatar or a custom avatar owned by the authenticated
+        # organization. A custom avatar belonging to another organization is returned as
+        # not found.
+        #
+        # @overload retrieve(avatar_id, request_options: {})
+        #
+        # @param avatar_id [String] Stable identifier returned by the Avatars API. Discover available stock IDs with
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::AI::AvatarResponse]
+        #
+        # @see Telnyx::Models::AI::AvatarRetrieveParams
+        def retrieve(avatar_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["ai/avatars/%1$s", avatar_id],
+            model: Telnyx::AI::AvatarResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::AI::AvatarUpdateParams} for more details.
+        #
+        # Updates the customer-facing name of a custom avatar owned by the authenticated
+        # organization. Stock avatars cannot be modified. To replace the image, create a
+        # new custom avatar so existing references keep their original content.
+        #
+        # @overload update(avatar_id, name:, request_options: {})
+        #
+        # @param avatar_id [String] Stable identifier returned by the Avatars API. Discover available stock IDs with
+        #
+        # @param name [String] New customer-facing name of the custom avatar.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::AI::AvatarResponse]
+        #
+        # @see Telnyx::Models::AI::AvatarUpdateParams
+        def update(avatar_id, params)
+          parsed, options = Telnyx::AI::AvatarUpdateParams.dump_request(params)
+          @client.request(
+            method: :patch,
+            path: ["ai/avatars/%1$s", avatar_id],
+            body: parsed,
+            model: Telnyx::AI::AvatarResponse,
+            options: options
+          )
+        end
+
+        # Returns a paginated list of the Telnyx stock avatars and custom avatars
+        # available to the authenticated organization. Custom avatars owned by other
+        # organizations are never returned. The `image_url` value is suitable for
+        # displaying a thumbnail and may be refreshed by listing or retrieving the avatar
+        # again. `suggested_voice_id` recommends a compatible Telnyx voice for stock
+        # avatars and is an empty string for custom avatars; it does not change an AI
+        # Assistant's voice automatically.
+        #
+        # @overload list(filter_avatar_type: nil, filter_id: nil, filter_name: nil, page_number: nil, page_size: nil, request_options: {})
+        #
+        # @param filter_avatar_type [Symbol, Telnyx::Models::AI::AvatarType] Return only stock or custom avatars.
+        #
+        # @param filter_id [String] Return the avatar with this exact ID.
+        #
+        # @param filter_name [String] Return avatars whose names contain this value, using case-insensitive matching.
+        #
+        # @param page_number [Integer] Page number to retrieve, starting at 1.
+        #
+        # @param page_size [Integer] Number of avatars to return per page.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Internal::DefaultFlatPagination<Telnyx::Models::AI::Avatar>]
+        #
+        # @see Telnyx::Models::AI::AvatarListParams
+        def list(params = {})
+          parsed, options = Telnyx::AI::AvatarListParams.dump_request(params)
+          query = Telnyx::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: "ai/avatars",
+            query: query.transform_keys(
+              filter_avatar_type: "filter[avatar_type]",
+              filter_id: "filter[id]",
+              filter_name: "filter[name]",
+              page_number: "page[number]",
+              page_size: "page[size]"
+            ),
+            page: Telnyx::Internal::DefaultFlatPagination,
+            model: Telnyx::AI::Avatar,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Telnyx::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/resources/ai/tests/schedules/v1/cron_jobs.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    class AI
+      class Tests
+        class Schedules
+          class V1
+            # Test agents, evaluator scenarios, metrics, and run results for the AI test
+            # framework.
+            class CronJobs
+              # Returns the specified scheduled test job.
+              #
+              # @overload retrieve(id, request_options: {})
+              #
+              # @param id [Integer] Numeric ID of the scheduled test job.
+              #
+              # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Telnyx::Models::AI::Tests::Schedules::V1::ScheduledTestJob]
+              #
+              # @see Telnyx::Models::AI::Tests::Schedules::V1::CronJobRetrieveParams
+              def retrieve(id, params = {})
+                @client.request(
+                  method: :get,
+                  path: ["ai/tests/schedules/v1/cron-jobs/%1$s", id],
+                  model: Telnyx::AI::Tests::Schedules::V1::ScheduledTestJob,
+                  options: params[:request_options]
+                )
+              end
+
+              # Updates the specified scheduled test job.
+              #
+              # @overload update(id, agent: nil, crontab_expression: nil, execution_mode: nil, frequency: nil, is_active: nil, name: nil, notify_on: nil, personalities: nil, run_as_text: nil, scenarios: nil, tags: nil, timezone: nil, request_options: {})
+              #
+              # @param id [Integer] Numeric ID of the scheduled test job.
+              #
+              # @param agent [Integer, nil]
+              #
+              # @param crontab_expression [String] Cron expression controlling when the job runs.
+              #
+              # @param execution_mode [String] Execution mode for the test runs, such as voice, text, or sip.
+              #
+              # @param frequency [Integer]
+              #
+              # @param is_active [Boolean]
+              #
+              # @param name [String]
+              #
+              # @param notify_on [Symbol, Telnyx::Models::AI::Tests::Schedules::V1::CronJobUpdateParams::NotifyOn]
+              #
+              # @param personalities [Array<Integer>]
+              #
+              # @param run_as_text [Boolean]
+              #
+              # @param scenarios [Array<Integer>]
+              #
+              # @param tags [Array<String>]
+              #
+              # @param timezone [String]
+              #
+              # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Telnyx::Models::AI::Tests::Schedules::V1::ScheduledTestJob]
+              #
+              # @see Telnyx::Models::AI::Tests::Schedules::V1::CronJobUpdateParams
+              def update(id, params = {})
+                parsed, options = Telnyx::AI::Tests::Schedules::V1::CronJobUpdateParams.dump_request(params)
+                @client.request(
+                  method: :patch,
+                  path: ["ai/tests/schedules/v1/cron-jobs/%1$s", id],
+                  body: parsed,
+                  model: Telnyx::AI::Tests::Schedules::V1::ScheduledTestJob,
+                  options: options
+                )
+              end
+
+              # Deletes the specified scheduled test job.
+              #
+              # @overload delete(id, request_options: {})
+              #
+              # @param id [Integer] Numeric ID of the scheduled test job.
+              #
+              # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Object]
+              #
+              # @see Telnyx::Models::AI::Tests::Schedules::V1::CronJobDeleteParams
+              def delete(id, params = {})
+                @client.request(
+                  method: :delete,
+                  path: ["ai/tests/schedules/v1/cron-jobs/%1$s", id],
+                  model: Telnyx::Internal::Type::Unknown,
+                  options: params[:request_options]
+                )
+              end
+
+              # Creates a scheduled test job that runs the selected scenarios on a cron
+              # expression.
+              #
+              # @overload cron_jobs(crontab_expression:, agent: nil, execution_mode: nil, frequency: nil, is_active: nil, name: nil, notify_on: nil, personalities: nil, run_as_text: nil, scenarios: nil, tags: nil, timezone: nil, request_options: {})
+              #
+              # @param crontab_expression [String] Cron expression controlling when the job runs.
+              #
+              # @param agent [Integer]
+              #
+              # @param execution_mode [String] Execution mode for the test runs, such as voice, text, or sip.
+              #
+              # @param frequency [Integer]
+              #
+              # @param is_active [Boolean]
+              #
+              # @param name [String]
+              #
+              # @param notify_on [Symbol, Telnyx::Models::AI::Tests::Schedules::V1::CronJobCronJobsParams::NotifyOn]
+              #
+              # @param personalities [Array<Integer>]
+              #
+              # @param run_as_text [Boolean]
+              #
+              # @param scenarios [Array<Integer>]
+              #
+              # @param tags [Array<String>]
+              #
+              # @param timezone [String]
+              #
+              # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Telnyx::Models::AI::Tests::Schedules::V1::ScheduledTestJob]
+              #
+              # @see Telnyx::Models::AI::Tests::Schedules::V1::CronJobCronJobsParams
+              def cron_jobs(params)
+                parsed, options = Telnyx::AI::Tests::Schedules::V1::CronJobCronJobsParams.dump_request(params)
+                @client.request(
+                  method: :post,
+                  path: "ai/tests/schedules/v1/cron-jobs",
+                  body: parsed,
+                  model: Telnyx::AI::Tests::Schedules::V1::ScheduledTestJob,
+                  options: options
+                )
+              end
+
+              # Returns the scheduled test jobs in your organization, optionally filtered by
+              # test agent. A scheduled job runs selected scenarios on a cron expression.
+              #
+              # @overload retrieve_cron_jobs(agent_id: nil, request_options: {})
+              #
+              # @param agent_id [Integer] Filter jobs belonging to the specified test agent.
+              #
+              # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Array<Telnyx::Models::AI::Tests::Schedules::V1::ScheduledTestJob>]
+              #
+              # @see Telnyx::Models::AI::Tests::Schedules::V1::CronJobRetrieveCronJobsParams
+              def retrieve_cron_jobs(params = {})
+                parsed, options = Telnyx::AI::Tests::Schedules::V1::CronJobRetrieveCronJobsParams.dump_request(params)
+                query = Telnyx::Internal::Util.encode_query_params(parsed)
+                @client.request(
+                  method: :get,
+                  path: "ai/tests/schedules/v1/cron-jobs",
+                  query: query,
+                  model: Telnyx::Internal::Type::ArrayOf[Telnyx::AI::Tests::Schedules::V1::ScheduledTestJob],
+                  options: options
+                )
+              end
+
+              # @api private
+              #
+              # @param client [Telnyx::Client]
+              def initialize(client:)
+                @client = client
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/resources/ai/tests/schedules/v1.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    class AI
+      class Tests
+        class Schedules
+          class V1
+            # Test agents, evaluator scenarios, metrics, and run results for the AI test
+            # framework.
+            # @return [Telnyx::Resources::AI::Tests::Schedules::V1::CronJobs]
+            attr_reader :cron_jobs
+
+            # @api private
+            #
+            # @param client [Telnyx::Client]
+            def initialize(client:)
+              @client = client
+              @cron_jobs = Telnyx::Resources::AI::Tests::Schedules::V1::CronJobs.new(client: client)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/resources/ai/tests/schedules.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    class AI
+      class Tests
+        class Schedules
+          # @return [Telnyx::Resources::AI::Tests::Schedules::V1]
+          attr_reader :v1
+
+          # @api private
+          #
+          # @param client [Telnyx::Client]
+          def initialize(client:)
+            @client = client
+            @v1 = Telnyx::Resources::AI::Tests::Schedules::V1.new(client: client)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/resources/ai/tests/test_framework/v1/aiagents.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    class AI
+      class Tests
+        class TestFramework
+          class V1
+            # Test agents, evaluator scenarios, metrics, and run results for the AI test
+            # framework.
+            class Aiagents
+              # Creates a test agent in your organization. The agent wraps a Telnyx AI assistant
+              # so simulated callers can be sent against it.
+              #
+              # @overload create(agent_name:, assistant_id:, auto_fetch_calls_enabled: nil, auto_sync_prompt_enabled: nil, auto_update_dropoff_nodes: nil, auto_update_topic_nodes: nil, contact_number: nil, description: nil, inbound: nil, language: nil, llm_max_tokens: nil, llm_model: nil, llm_system_prompt: nil, llm_temperature: nil, outbound_auto_call: nil, sip_endpoint: nil, request_options: {})
+              #
+              # @param agent_name [String] Name of the test agent.
+              #
+              # @param assistant_id [String] ID of the Telnyx AI assistant under test.
+              #
+              # @param auto_fetch_calls_enabled [Boolean]
+              #
+              # @param auto_sync_prompt_enabled [Boolean]
+              #
+              # @param auto_update_dropoff_nodes [Boolean]
+              #
+              # @param auto_update_topic_nodes [Boolean]
+              #
+              # @param contact_number [String]
+              #
+              # @param description [String]
+              #
+              # @param inbound [Boolean]
+              #
+              # @param language [String] ISO language code the test agent converses in.
+              #
+              # @param llm_max_tokens [Integer]
+              #
+              # @param llm_model [String]
+              #
+              # @param llm_system_prompt [String]
+              #
+              # @param llm_temperature [Float]
+              #
+              # @param outbound_auto_call [Boolean]
+              #
+              # @param sip_endpoint [String]
+              #
+              # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Telnyx::Models::AI::Tests::TestFramework::V1::TestAgent]
+              #
+              # @see Telnyx::Models::AI::Tests::TestFramework::V1::AiagentCreateParams
+              def create(params)
+                parsed, options = Telnyx::AI::Tests::TestFramework::V1::AiagentCreateParams.dump_request(params)
+                @client.request(
+                  method: :post,
+                  path: "ai/tests/test_framework/v1/aiagents",
+                  body: parsed,
+                  model: Telnyx::AI::Tests::TestFramework::V1::TestAgent,
+                  options: options
+                )
+              end
+
+              # Returns the specified test agent.
+              #
+              # @overload retrieve(id, request_options: {})
+              #
+              # @param id [Integer] Numeric ID of the test agent.
+              #
+              # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Telnyx::Models::AI::Tests::TestFramework::V1::TestAgent]
+              #
+              # @see Telnyx::Models::AI::Tests::TestFramework::V1::AiagentRetrieveParams
+              def retrieve(id, params = {})
+                @client.request(
+                  method: :get,
+                  path: ["ai/tests/test_framework/v1/aiagents/%1$s", id],
+                  model: Telnyx::AI::Tests::TestFramework::V1::TestAgent,
+                  options: params[:request_options]
+                )
+              end
+
+              # Updates the specified test agent.
+              #
+              # @overload update(id, agent_name: nil, assistant_id: nil, auto_fetch_calls_enabled: nil, auto_sync_prompt_enabled: nil, auto_update_dropoff_nodes: nil, auto_update_topic_nodes: nil, contact_number: nil, description: nil, inbound: nil, language: nil, llm_max_tokens: nil, llm_model: nil, llm_system_prompt: nil, llm_temperature: nil, outbound_auto_call: nil, sip_endpoint: nil, request_options: {})
+              #
+              # @param id [Integer] Numeric ID of the test agent.
+              #
+              # @param agent_name [String] Name of the test agent.
+              #
+              # @param assistant_id [String] ID of the Telnyx AI assistant under test.
+              #
+              # @param auto_fetch_calls_enabled [Boolean]
+              #
+              # @param auto_sync_prompt_enabled [Boolean]
+              #
+              # @param auto_update_dropoff_nodes [Boolean]
+              #
+              # @param auto_update_topic_nodes [Boolean]
+              #
+              # @param contact_number [String]
+              #
+              # @param description [String]
+              #
+              # @param inbound [Boolean]
+              #
+              # @param language [String] ISO language code the test agent converses in.
+              #
+              # @param llm_max_tokens [Integer]
+              #
+              # @param llm_model [String]
+              #
+              # @param llm_system_prompt [String]
+              #
+              # @param llm_temperature [Float]
+              #
+              # @param outbound_auto_call [Boolean]
+              #
+              # @param sip_endpoint [String]
+              #
+              # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Telnyx::Models::AI::Tests::TestFramework::V1::TestAgent]
+              #
+              # @see Telnyx::Models::AI::Tests::TestFramework::V1::AiagentUpdateParams
+              def update(id, params = {})
+                parsed, options = Telnyx::AI::Tests::TestFramework::V1::AiagentUpdateParams.dump_request(params)
+                @client.request(
+                  method: :put,
+                  path: ["ai/tests/test_framework/v1/aiagents/%1$s", id],
+                  body: parsed,
+                  model: Telnyx::AI::Tests::TestFramework::V1::TestAgent,
+                  options: options
+                )
+              end
+
+              # Returns a paginated list of test agents in your organization. A test agent wraps
+              # the Telnyx AI assistant under test and drives simulated callers against it.
+              #
+              # @overload list(page: nil, page_size: nil, request_options: {})
+              #
+              # @param page [Integer] Page number (1-based).
+              #
+              # @param page_size [Integer] Number of results per page.
+              #
+              # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Telnyx::Models::AI::Tests::TestFramework::V1::AiagentListResponse]
+              #
+              # @see Telnyx::Models::AI::Tests::TestFramework::V1::AiagentListParams
+              def list(params = {})
+                parsed, options = Telnyx::AI::Tests::TestFramework::V1::AiagentListParams.dump_request(params)
+                query = Telnyx::Internal::Util.encode_query_params(parsed)
+                @client.request(
+                  method: :get,
+                  path: "ai/tests/test_framework/v1/aiagents",
+                  query: query,
+                  model: Telnyx::Models::AI::Tests::TestFramework::V1::AiagentListResponse,
+                  options: options
+                )
+              end
+
+              # Deletes the specified test agent.
+              #
+              # @overload delete(id, request_options: {})
+              #
+              # @param id [Integer] Numeric ID of the test agent.
+              #
+              # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Object]
+              #
+              # @see Telnyx::Models::AI::Tests::TestFramework::V1::AiagentDeleteParams
+              def delete(id, params = {})
+                @client.request(
+                  method: :delete,
+                  path: ["ai/tests/test_framework/v1/aiagents/%1$s", id],
+                  model: Telnyx::Internal::Type::Unknown,
+                  options: params[:request_options]
+                )
+              end
+
+              # @api private
+              #
+              # @param client [Telnyx::Client]
+              def initialize(client:)
+                @client = client
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end