@wildix/wilma-agents-client 1.0.34 → 1.0.37

package/dist-types/models/models_0.d.ts

@@ -1,5 +1,5 @@
 import type { DocumentType as __DocumentType } from "@smithy/types";
-import type { ActorType, AgentGuardrailErrorMode, AgentGuardrailMode, AgentGuardrailPreset, AgentGuardrailSensitivity, AgentGuardrailWindow, AgentHandoverPipelineType, AgentHandoverVariant, AgentHangupPipelineType, AgentStatus, AgentToolPipelineType, AgentTransferPipelineType, AgentTransferVariant, AgentVariableType, AgentVisibility, AgentWorkflowEntryBehavior, AgentWorkflowFailureKind, AgentWorkflowLayout, AgentWorkflowMessageButtonVariant, ChannelType, SandboxNetworkAccess, SandboxSize, WebSearchContextSize } from "./enums";
+import type { ActorType, AgentGuardrailErrorMode, AgentGuardrailMode, AgentGuardrailPreset, AgentGuardrailSensitivity, AgentGuardrailWindow, AgentHandoverPipelineType, AgentHandoverVariant, AgentHangupPipelineType, AgentStatus, AgentToolPipelineType, AgentTransferPipelineType, AgentTransferVariant, AgentVariableType, AgentVisibility, AgentWorkflowEntryBehavior, AgentWorkflowFailureKind, AgentWorkflowLayout, AgentWorkflowMessageButtonVariant, ChannelType, SandboxNetworkAccess, SandboxSize, VoicePronunciationEncoding, WebSearchContextSize } from "./enums";
 /**
  * A user or group that access is granted to.
  * @public
@@ -140,6 +140,29 @@ export interface ChatChannelSettings {
      */
     discoverable?: boolean | undefined;
 }
+/**
+ * Ambient background audio played under the call.
+ *
+ *     A SETTINGS OBJECT like `interruptions` and `endCall`, rather than a loose name on the channel:
+ *     it is one switchable call behaviour, it reads the same way as its siblings, and the volume and
+ *     fade controls the console will want next have somewhere to go.
+ *
+ *     ABSENT MEANS OFF — a bot that never touches it behaves exactly as every call did before this
+ *     setting existed, and the PBX needs no new case.
+ * @public
+ */
+export interface VoiceBackgroundSoundSettings {
+    /**
+     * Whether ambient background audio plays under the call.
+     * @public
+     */
+    enabled: boolean;
+    /**
+     * Music-on-hold class the PBX plays. Absent with `enabled` true leaves the choice of class to the PBX.
+     * @public
+     */
+    sound?: string | undefined;
+}
 /**
  * Caller context injected into the model prompt.
  * @public
@@ -282,6 +305,150 @@ export interface VoiceSilenceTimeoutSettings {
     seconds: number;
     action: VoiceTerminateAction;
 }
+/**
+ * A pronunciation rule for one phrase. Belongs to a LANGUAGE, not to the agent: 'Wildix' is
+ *     respelled differently for an Italian and a German voice, so one list shared ACROSS languages
+ *     would fight itself. That is why the rules hang off the language and nowhere else — there is no
+ *     company-wide dictionary above them to inherit from, or to disagree with.
+ * @public
+ */
+export interface VoicePronunciation {
+    /**
+     * The phrase as it appears in the text, e.g. 'Wildix'. Bounded because every rule is compiled into ONE regular expression — see the list below.
+     * @public
+     */
+    phrase: string;
+    /**
+     * Respelling (ALIAS) or phonetic transcription (IPA), e.g. 'Wil-dix'.
+     * @public
+     */
+    as: string;
+    /**
+     * Defaults to ALIAS.
+     * @public
+     */
+    encoding?: VoicePronunciationEncoding | undefined;
+}
+/**
+ * One configured language: its voice, its initial phrase and its pronunciation rules.
+ * @public
+ */
+export interface VoiceLanguage {
+    /**
+     * BCP-47 code with locale, e.g. 'en-US', 'it-IT'.
+     * @public
+     */
+    code: string;
+    /**
+     * Voice this language speaks with, as a URI — provider, voice id, synthesis parameters and,
+     *         where the company uses its own provider account, an `apiKey=secrets:\{secretId\}` reference.
+     *         See VoiceUri.
+     *
+     *         PER LANGUAGE, and that is the whole reason the member is here rather than on the settings
+     *         above: provider quality is not uniform across languages, a voice id belongs to exactly one
+     *         provider, and a bot-wide provider made changing it invalidate every configured voice at
+     *         once.
+     * @public
+     */
+    voice: string;
+    /**
+     * Initial phrase spoken when the call starts in this language. Absent or empty means
+     *         the agent says nothing and waits — it does NOT fall back to VoiceChannelSettings.greeting,
+     *         which would speak one language's text in another language's voice.
+     * @public
+     */
+    greeting?: string | undefined;
+    /**
+     * Marks the language a caller hears when their own matches nothing configured.
+     *
+     *         THE FULL RESOLUTION ORDER, since a client author reading only this contract cannot
+     *         otherwise find it: an exact match on the call's language, then a match on its primary
+     *         subtag (`fr` finds `fr-FR`), then the language marked here, then a language whose
+     *         primary subtag is `en`, then the first entry in the list.
+     *
+     *         Marked is consulted BEFORE the English step, so a record with none marked resolves
+     *         exactly as it did before this member existed. English is deliberate rather than
+     *         arbitrary — it is the language a caller the agent was not built for is likeliest to
+     *         understand — and the last step exists only to keep the rule total, which is why list
+     *         order should not be treated as configuration.
+     *
+     *         At most one language may carry it. A record with two — reachable through the API or
+     *         the CLI, where no form prevents it — resolves to the first marked one in list order,
+     *         because refusing a call over configuration drift is worse than serving it and saying
+     *         so in the trace.
+     * @public
+     */
+    isDefault?: boolean | undefined;
+    /**
+     * The rules this language is spoken with. THE WHOLE SET rather than an override layer: an
+     *         agent's respellings are stored here and read from here, so what this list says is what the
+     *         caller hears.
+     *
+     *         THERE IS NOTHING ABOVE IT. An earlier draft of this contract carried a company-wide
+     *         dictionary per language that every agent speaking it inherited, with a merge order over this
+     *         member and an identity rule ('Wildix' -> 'Wildix') for declining an inherited respelling.
+     *         It bought correcting a handful of names in one place, and cost a second store, a merge on
+     *         every synthesis path, a screen of its own, and a reader who could not tell from an agent
+     *         what that agent would actually say. Per language per agent is where the divergence that
+     *         matters already lives.
+     * @public
+     */
+    pronunciations?: VoicePronunciation[] | undefined;
+}
+/**
+ * Speech-to-text configuration: which recogniser listens to the caller, and whether it identifies the language while it does.
+ * @public
+ */
+export interface VoiceTranscriptionSettings {
+    /**
+     * Recogniser to transcribe the caller with. Absent resolves to the platform default ('aws://transcribe' today), resolved by the server so exactly one component decides it.
+     * @public
+     */
+    engine?: string | undefined;
+    /**
+     * Identify the caller's language per utterance and switch voice and reply language mid-call.
+     *
+     *         HERE RATHER THAN ON `VoiceSpeechSettings`, because identifying a language is something the
+     *         RECOGNISER does: it becomes identify-multiple-languages plus language-options on the
+     *         recognition stream, and nothing about synthesis reads it.
+     *
+     *         Requires at least two configured languages and a recogniser that can identify them; the
+     *         server clamps it to false otherwise, because forwarding true with a single candidate makes
+     *         Amazon reject the stream outright.
+     * @public
+     */
+    autoDetect?: boolean | undefined;
+}
+/**
+ * Speech configuration for the voice channel. When present it WINS over the dialplan's `voice` and
+ *     `initialMessage` connect parameters; `language` is the single exception, because it is the
+ *     channel's own input signal and the feature has no starting point without it.
+ * @public
+ */
+export interface VoiceSpeechSettings {
+    /**
+     * Configured languages. The @length bound is a STORAGE ceiling, not the product rule: the real
+     *         cap is the recogniser's own candidate limit (five for Amazon Transcribe), enforced in the
+     *         service so a recogniser with a different limit needs no model change.
+     * @public
+     */
+    languages: VoiceLanguage[];
+    /**
+     * Speak the first message of every configured language in turn when the call is answered, each
+     *         in the voice, provider account and pronunciation rules of its own language, instead of only the
+     *         language the call resolved to. Languages whose first message is empty, and languages the PBX
+     *         synthesizes itself, are skipped. Absent means off. Requires at least two languages carrying a
+     *         first message; below that the runtime speaks only the resolved language's phrase, and the
+     *         console clamps the member on save.
+     * @public
+     */
+    greetEveryLanguage?: boolean | undefined;
+    /**
+     * Which recogniser listens to the caller, and whether it identifies the language. Absent takes the platform default recogniser with no language identification.
+     * @public
+     */
+    transcription?: VoiceTranscriptionSettings | undefined;
+}
 /**
  * Voice channel settings. Note: a voice agent's AgentAccess.grants are ignored — inbound calls are routed by the PBX dialplan and data ACL is the agent-level `settings.pbxGroupId`, not per-user grants.
  * @public
@@ -292,6 +459,21 @@ export interface VoiceChannelSettings {
      * @public
      */
     greeting?: string | undefined;
+    /**
+     * Ambient background audio played under the call.
+     *
+     *         It belongs to the CHANNEL rather than to `speech`, even though the console shows the control
+     *         under the automatic-language switch. `speech` is the recognition and synthesis
+     *         configuration and is sent only when languages are configured — background audio has nothing
+     *         to do with either, and a bot with no languages must still be able to have it.
+     * @public
+     */
+    backgroundSound?: VoiceBackgroundSoundSettings | undefined;
+    /**
+     * Languages, voices, initial phrases, recogniser and pronunciation. Absent means the legacy behavior: voice URI from the dialplan connect parameter, one voice, language as prompt context only.
+     * @public
+     */
+    speech?: VoiceSpeechSettings | undefined;
     interruptions?: VoiceInterruptionSettings | undefined;
     silenceTimeout?: VoiceSilenceTimeoutSettings | undefined;
     maxDuration?: VoiceMaxDurationSettings | undefined;
@@ -303,7 +485,7 @@ export interface VoiceChannelSettings {
     callerMetadata?: VoiceCallerMetadataSettings | undefined;
 }
 /**
- * The channels an agent serves and their channel-specific settings. Presence of a member enables that channel; at least one must be set. Enabled channels are mirrored as ChannelType values on AgentInfo.
+ * The channels an agent serves and their channel-specific settings. Presence of a member enables that channel. Empty means the agent serves no channel: it is not reachable on its own and runs only as an automation's task or when another agent calls it. Enabled channels are mirrored as ChannelType values on AgentInfo.
  * @public
  */
 export interface AgentChannels {
@@ -1724,6 +1906,11 @@ export interface AgentGuardrailInput {
      * @public
      */
     model?: string | undefined;
+    /**
+     * Action for checks that declare none. Defaults to a block.
+     * @public
+     */
+    action?: AgentGuardrailAction | undefined;
     /**
      * Runs the checker before the agent's model (BLOCKING) or alongside it (PARALLEL). Blocking costs the checker's latency on every turn but guarantees that a refused turn spent no tokens and fired no tool; parallel adds no latency and is the right trade on voice, where the delay is audible, at the risk that part of a reply reaches the caller and that a tool has already run before the cancellation lands. Defaults to BLOCKING.
      * @public
@@ -3013,7 +3200,7 @@ export interface Agent {
      */
     picture?: string | undefined;
     /**
-     * The channels this agent serves and their channel-specific settings. A channel is enabled when its member is present; at least one must be set. An agent may serve multiple channels (e.g. chat + assistant) over the shared engine.
+     * The channels this agent serves and their channel-specific settings. A channel is enabled when its member is present. An agent may serve multiple channels (e.g. chat + assistant) over the shared engine, or none at all — an empty structure is an agent that is only run as an automation's task or called by another agent, and is not reachable on any delivery surface.
      * @public
      */
     channels: AgentChannels;
@@ -3129,7 +3316,7 @@ export interface AgentDefinitionSnapshot {
      */
     picture?: string | undefined;
     /**
-     * The channels this agent serves and their channel-specific settings. A channel is enabled when its member is present; at least one must be set. An agent may serve multiple channels (e.g. chat + assistant) over the shared engine.
+     * The channels this agent serves and their channel-specific settings. A channel is enabled when its member is present. An agent may serve multiple channels (e.g. chat + assistant) over the shared engine, or none at all — an empty structure is an agent that is only run as an automation's task or called by another agent, and is not reachable on any delivery surface.
      * @public
      */
     channels: AgentChannels;
@@ -3170,10 +3357,15 @@ export interface AgentInfo {
     category?: string | undefined;
     status: AgentStatus;
     /**
-     * The channels this agent serves (voice / chat / assistant).
+     * The channels this agent serves (voice / chat / assistant). Empty for an agent that serves none — one only an automation runs or another agent calls.
      * @public
      */
     channels: ChannelType[];
+    /**
+     * Whether the voice channel has at least one configured speech language. A dialplan form partitions its application lists on this, so the answer has to travel with the list rather than cost one lookup per entry — it is the reason this member exists and the reason removing it broke that form. Absent is read as false.
+     * @public
+     */
+    speechConfigured?: boolean | undefined;
     /**
      * Ids of the skills attached to this agent. Always active in this agent's sessions; user skill preferences cannot disable them.
      * @public
@@ -3335,7 +3527,7 @@ export interface CreateAgentInput {
      */
     picture?: string | undefined;
     /**
-     * The channels this agent serves and their channel-specific settings. A channel is enabled when its member is present; at least one must be set. An agent may serve multiple channels (e.g. chat + assistant) over the shared engine.
+     * The channels this agent serves and their channel-specific settings. A channel is enabled when its member is present. An agent may serve multiple channels (e.g. chat + assistant) over the shared engine, or none at all — an empty structure is an agent that is only run as an automation's task or called by another agent, and is not reachable on any delivery surface.
      * @public
      */
     channels: AgentChannels;
@@ -3490,7 +3682,7 @@ export interface ListAgentApiKeysOutput {
 export interface ListAgentsInput {
     company?: string | undefined;
     /**
-     * Only agents that have this channel enabled (voice / chat / assistant).
+     * Only agents that have this channel enabled (voice / chat / assistant). An agent serving no channel matches no value of this filter, so a caller listing agents to run as a task — rather than to reach on a surface — must leave it unset.
      * @public
      */
     channel?: ChannelType | undefined;
@@ -3671,7 +3863,7 @@ export interface UpdateAgentInput {
      */
     picture?: string | undefined;
     /**
-     * The channels this agent serves and their channel-specific settings. A channel is enabled when its member is present; at least one must be set. An agent may serve multiple channels (e.g. chat + assistant) over the shared engine.
+     * The channels this agent serves and their channel-specific settings. A channel is enabled when its member is present. An agent may serve multiple channels (e.g. chat + assistant) over the shared engine, or none at all — an empty structure is an agent that is only run as an automation's task or called by another agent, and is not reachable on any delivery surface.
      * @public
      */
     channels: AgentChannels;

package/dist-types/schemas/schemas_0.d.ts

@@ -134,13 +134,18 @@ export declare var RestoreAgentVersionToDraftInput$: StaticStructureSchema;
 export declare var RestoreAgentVersionToDraftOutput$: StaticStructureSchema;
 export declare var UpdateAgentInput$: StaticStructureSchema;
 export declare var UpdateAgentOutput$: StaticStructureSchema;
+export declare var VoiceBackgroundSoundSettings$: StaticStructureSchema;
 export declare var VoiceCallerMetadataSettings$: StaticStructureSchema;
 export declare var VoiceChannelSettings$: StaticStructureSchema;
 export declare var VoiceEndCallSettings$: StaticStructureSchema;
 export declare var VoiceInterruptionSettings$: StaticStructureSchema;
+export declare var VoiceLanguage$: StaticStructureSchema;
 export declare var VoiceMaxDurationSettings$: StaticStructureSchema;
+export declare var VoicePronunciation$: StaticStructureSchema;
 export declare var VoiceSilenceTimeoutSettings$: StaticStructureSchema;
+export declare var VoiceSpeechSettings$: StaticStructureSchema;
 export declare var VoiceTerminateHangupAction$: StaticStructureSchema;
+export declare var VoiceTranscriptionSettings$: StaticStructureSchema;
 export declare var VoiceTransferTarget$: StaticStructureSchema;
 export declare var WebSearchUserLocation$: StaticStructureSchema;
 export declare var Actor$: StaticStructureSchema;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@wildix/wilma-agents-client",
     "description": "@wildix/wilma-agents-client client",
-    "version": "1.0.34",
+    "version": "1.0.37",
     "scripts": {
         "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types'",
         "build:cjs": "tsc -p tsconfig.cjs.json",