wldx-admin-cli 1.2.0 → 1.3.0

package/specs/voicebots.openapi.json

@@ -0,0 +1 @@
+{"openapi":"3.0.2","info":{"title":"voicebots","sources":["https://docs.wildix.com/codegen/api/wim-voicebots-client.openapi.json"]},"servers":[{"url":"https://wim.wildix.com","description":"Production"},{"url":"https://wim-stable.wildix.com","description":"Stable"},{"url":"https://wim-stage.wildix.com","description":"Stage"}],"paths":{"/v2/voicebots/bots":{"get":{"operationId":"ListVoiceBots","summary":"","description":"Retrieves a list of all voice bots for the specified company.\n\n### Allowed Auth Scopes\n\n- voicebots:ListVoiceBots\n- voicebots:read","parameters":[{"name":"company","in":"query","required":false,"schema":{"type":"string"}}]},"post":{"operationId":"CreateVoiceBot","summary":"","description":"Creates a new voice bot with the specified configuration for the company.\n\n### Allowed Auth Scopes\n\n- voicebots:CreateVoiceBot","parameters":[{"name":"company","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"minLength":3},"category":{"type":"string","maxLength":128,"minLength":1,"description":"Category of the bot"},"message":{"type":"string","description":"The initial message that will be played at the start of the session."},"pipeline":{"type":"object","properties":{"interuptionsEnabled":{"type":"boolean","description":"If enabled the user can interrupt the the bot playback."},"maximumDuration":{"type":"number","description":"The maximum number of seconds a call will last."},"maximumDurationAction":{"oneOf":[{"type":"object","title":"hangup","properties":{"hangup":{"type":"object"}},"required":["hangup"]},{"type":"object","title":"transfer","properties":{"transfer":{"type":"object","properties":{"context":{"type":"string"},"extension":{"type":"string"}},"required":["context","extension"]}},"required":["transfer"]}]},"silenceTimeout":{"type":"number","description":"How long to wait before a call is automatically ended due to inactivity."},"silenceTimeoutAction":{"oneOf":[{"type":"object","title":"hangup","properties":{"hangup":{"type":"object"}},"required":["hangup"]},{"type":"object","title":"transfer","properties":{"transfer":{"type":"object","properties":{"context":{"type":"string"},"extension":{"type":"string"}},"required":["context","extension"]}},"required":["transfer"]}]},"endCallEnabled":{"type":"boolean","description":"If enabled the bot can hangup the call."},"endCallPhases":{"type":"string","description":"A list of phases separated by comma, which will end the call matched."}}},"speech":{"type":"object","description":"Speech configuration. When present it wins over the dialplan's `voice` and `initialMessage` connect parameters; `language` is the exception.","properties":{"languages":{"type":"array","items":{"type":"object","description":"One configured language: its voice, its initial phrase and its pronunciation rules.","properties":{"code":{"type":"string","maxLength":8,"minLength":2,"pattern":"^[a-z]{2,3}(-[A-Z]{2})?$","description":"BCP-47 code with locale, e.g. 'en-US'."},"voice":{"type":"string","maxLength":1024,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*://[a-zA-Z0-9._~/-]+(\\?[a-zA-Z0-9._~%&=+:/-]*)?$","description":"Voice this language speaks with, as a URI — provider, voice id, synthesis parameters and,\n    where the company uses its own provider account, its `apiKey` query parameter. See\n    VoiceBotVoiceUri.\n\n    PER LANGUAGE, and that is the whole reason the member is here rather than on the settings\n    above: provider quality is not uniform across languages, a voice id belongs to exactly one\n    provider, and a bot-wide provider made changing it invalidate every configured voice at once."},"greeting":{"type":"string","description":"Initial phrase for this language. Absent or empty means the agent says nothing and\n    waits — it does NOT fall back to the agent-level message, which would speak one\n    language's text in another language's voice."},"isDefault":{"type":"boolean","description":"Marks the language a caller hears when their own matches nothing configured.\n\n    THE FULL RESOLUTION ORDER, since a client author reading only this contract cannot\n    otherwise find it: an exact match on the call's language, then a match on its primary\n    subtag (`fr` finds `fr-FR`), then the language marked here, then a language whose\n    primary subtag is `en`, then the first entry in the list.\n\n    Marked is consulted BEFORE the English step, so a record with none marked resolves\n    exactly as it did before this member existed. English is deliberate rather than\n    arbitrary — it is the language a caller the agent was not built for is likeliest to\n    understand — and the last step exists only to keep the rule total, which is why list\n    order should not be treated as configuration.\n\n    At most one language may carry it. A record with two — reachable through the API or\n    the CLI, where no form prevents it — resolves to the first marked one in list order,\n    because refusing a call over configuration drift is worse than serving it and saying\n    so in the trace."},"pronunciations":{"type":"array","items":{"type":"object","description":"A pronunciation rule for one phrase, belonging to one language.","properties":{"phrase":{"type":"string","maxLength":200,"description":"The written form to replace. Bounded because every rule is compiled into ONE regular expression — see the list below."},"as":{"type":"string","maxLength":200,"description":"Respelling (ALIAS) or phonetic transcription (IPA)."},"encoding":{"type":"string","enum":["alias","ipa"]}},"required":["as","phrase"]},"maxItems":200,"description":"Pronunciation rules for one language.\n\n    BOUNDED, and the bound is not decoration. `applyPronunciations` compiles every rule of a\n    language into a SINGLE alternating regular expression, so the cost is the pattern's total\n    size: measured against the real escaping and matching logic, 1,000 rules cost ~0.9 s of CPU\n    per synthesized sentence, 5,000 cost ~4.9 s, and around 10,000 `new RegExp` throws V8's\n    pattern-size error outright — from a call site outside the surrounding `try`, so a 500 rather\n    than a degraded reply. Stored on a bot, that made every utterance of the agent fail.\n\n    200 is far above any real use — a product glossary is a handful of names — and far below\n    where either cost begins. Found by a security review.\n    NO LOWER BOUND on `phrase` or `as`, deliberately. Both consoles add an EMPTY rule row the\n    moment someone clicks 'Add pronunciation', so a `min: 1` would make saving an agent with a\n    half-typed row fail entirely — and the runtime already ignores a rule with no phrase. Dropping\n    blank rows belongs in the consoles' save filters, not in a refusal here."}},"required":["code","voice"]},"maxItems":10,"minItems":1,"description":"Configured languages. The @length bound is a storage ceiling; the real cap is the recogniser's own candidate limit, enforced in the service."},"greetEveryLanguage":{"type":"boolean","description":"Speak the first message of every configured language in turn when the call is answered, each in its own language's voice, provider account and pronunciation rules. Languages with an empty first message, 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."},"transcription":{"type":"object","description":"Speech-to-text configuration: which recogniser listens to the caller, and whether it identifies the language while it does.","properties":{"engine":{"type":"string","maxLength":1024,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*://[a-zA-Z0-9._~/-]+(\\?[a-zA-Z0-9._~%&=+:/-]*)?$","description":"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."},"autoDetect":{"type":"boolean","description":"Identify the caller's language per utterance and switch voice and reply language mid-call.\n\n    HERE RATHER THAN ON `VoiceBotSpeechSettings`, because identifying a language is something the\n    RECOGNISER does: it becomes identify-multiple-languages plus language-options on the\n    recognition stream, and nothing about synthesis reads it.\n\n    Requires at least two configured languages and a recogniser that can identify them; the server\n    clamps it to false otherwise, because forwarding true with a single candidate makes Amazon\n    reject the stream outright."}}}},"required":["languages"]},"backgroundSound":{"type":"object","description":"Ambient background audio played under the call.\n\n  A SETTINGS OBJECT rather than a loose name on the bot, matching `wildix.wilma.agents`: it is one\n  switchable call behaviour, and the volume and fade controls the console will want next have\n  somewhere to go.\n\n  ABSENT MEANS OFF — a bot that never touches it behaves exactly as every call did before this\n  setting existed, and the PBX needs no new case.","properties":{"enabled":{"type":"boolean","description":"Whether ambient background audio plays under the call."},"sound":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[^\\r\\n]+$","description":"Music-on-hold class the PBX plays. Absent with `enabled` true leaves the choice of class to the PBX."}},"required":["enabled"]},"endpoint":{"oneOf":[{"type":"object","title":"llm","properties":{"llm":{"type":"object","properties":{"prompt":{"type":"string","maxLength":40000},"model":{"type":"string","default":"default","pattern":"^(default|([a-z0-9][a-z0-9-]*://[a-zA-Z0-9._/-]+(\\?[a-zA-Z0-9._&=%-]*)?))$","description":"The AI model to use for generating responses. If not specified, uses the default model."},"guidelines":{"type":"array","items":{"type":"string","maxLength":12,"minLength":12}},"metadata":{"type":"object","properties":{"userName":{"type":"object","properties":{"enabled":{"type":"boolean","default":true,"description":"Whether this metadata field is enabled"}},"required":["enabled"]},"userPhoneNumber":{"type":"object","properties":{"enabled":{"type":"boolean","default":true,"description":"Whether this metadata field is enabled"}},"required":["enabled"]},"userEmail":{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether this metadata field is enabled"}},"required":["enabled"]},"userCompany":{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether this metadata field is enabled"}},"required":["enabled"]},"time":{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether this metadata field is enabled"},"timeZone":{"type":"string","default":"UTC","description":"Timezone for time formatting (e.g., 'Europe/Rome', 'UTC')"}},"required":["enabled","timeZone"]}}},"embeddedTools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["HANGUP","TRANSFER","DELEGATE","WAIT"]},"name":{"type":"string"},"parameters":{"description":"The parameters the functions accepts."},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}},"required":["name","type"]},"description":"Embedded functions to use within voice session."},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["function"]},"function":{"type":"object","properties":{"name":{"type":"string","description":"The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64."},"description":{"type":"string","description":"A description of what the function does, used by the model to choose when and how to call the function."},"parameters":{"description":"The parameters the functions accepts, described as a JSON Schema object."},"integration":{"oneOf":[{"type":"object","title":"webhook","properties":{"webhook":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["get","post","put","delete","patch"]},"async":{"type":"boolean"},"authorization":{"oneOf":[{"type":"object","title":"bearer","properties":{"bearer":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}},"required":["bearer"]},{"type":"object","title":"basic","properties":{"basic":{"type":"object","properties":{"username":{"type":"string"},"password":{"type":"string"}},"required":["password","username"]}},"required":["basic"]},{"type":"object","title":"oauth","properties":{"oauth":{"type":"object","properties":{"clientId":{"type":"string"},"clientSecret":{"type":"string"},"endpointUrl":{"type":"string"},"scope":{"type":"string"}},"required":["clientId","clientSecret","endpointUrl"]}},"required":["oauth"]}]},"headers":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]}},"timeout":{"type":"number","maximum":120000,"minimum":5000,"description":"Timeout in milliseconds for the webhook request."},"startMessage":{"type":"string","description":"Message spoken when the function call starts."},"parameters":{}},"required":["url"]}},"required":["webhook"]}]}},"required":["name"]},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}},"required":["type"]},"description":"Custom tools to be used within voice session."},"capabilities":{"type":"array","items":{"oneOf":[{"type":"object","title":"tool","properties":{"tool":{"type":"object","properties":{"id":{"type":"string","maxLength":12,"minLength":12,"pattern":"^[0-9A-Za-z]{12}$","description":"Unique identifier of the tool using nanoid format"},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-zA-Z0-9_]+$","description":"Name of the tool variable, e.g.: 'myvar'"},"handler":{"oneOf":[{"type":"object","title":"auto","properties":{"auto":{"type":"object"}},"required":["auto"]},{"type":"object","title":"guided","properties":{"guided":{"type":"object","properties":{"description":{"type":"string","maxLength":1024,"minLength":1}},"required":["description"]}},"required":["guided"]},{"type":"object","title":"predefined","properties":{"predefined":{"type":"object","properties":{"description":{"type":"string"}},"required":["description"]}},"required":["predefined"]}]}},"required":["name"]}},"startMessage":{"type":"string","description":"Message spoken when the tool call starts. Spoken in every language of the call while `startMessages` is absent or empty; not consulted once `startMessages` carries any entry."},"startMessages":{"type":"array","items":{"type":"object","description":"One phrase in one language, for a tool that speaks a fixed line when its call starts. Which\n  entry is spoken is decided by the call's current language — the one resolved at connect, or the\n  one automatic detection switched to — matched on `language` CASE-INSENSITIVELY, because older\n  records on this stack hold lower-cased codes; `AgentSpokenPhrase` matches the same way, so the\n  two stacks cannot disagree about which entry a code reaches. Blank `text` means the agent says\n  nothing in that language; it does NOT fall back to `startMessage`, which would speak one\n  language's text in another language's voice.","properties":{"language":{"type":"string","maxLength":8,"minLength":2,"pattern":"^[a-z]{2,3}(-[A-Z]{2})?$","description":"BCP-47 language tag, optionally with a region subtag: 'en', 'en-US', 'pt-BR'. Deliberately a\n    constrained string rather than an enum: the offerable set is a property of the selected\n    recogniser and changes with it, so an enumeration here would cap the set at whatever was known\n    when the model was released."},"text":{"type":"string"}},"required":["language","text"]},"description":"Per-language start messages. When present and non-empty, the entry for the call's current\n    language is spoken and `startMessage` is not consulted; a language with no entry is silent.\n    When absent or empty, `startMessage` is spoken as before. On a call with no effective speech\n    configuration — no configured languages, or a PBX below protocol 2 — `startMessage` is spoken\n    regardless, because there is no current language to choose by."},"pipeline":{"type":"object","properties":{"type":{"type":"string","enum":["blocking_request","blocking_request_guided","async_request","async_request_guided"]},"instructions":{"type":"string","description":"Instructions for generating a reply when using guided pipeline types. Use {{response}} to reference the tool response."}}},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}},"required":["id"]}},"required":["tool"]},{"type":"object","title":"kb","properties":{"kb":{"type":"object","properties":{"knowledgeBaseId":{"type":"string"},"instructions":{"type":"string","description":"Additional instructions for when the bot should use this knowledge base."},"searchStrategy":{"type":"string","enum":["bm25","vector","hybrid"]},"searchThreshold":{"type":"string","enum":["low","medium","high"]},"searchLimit":{"type":"number","maximum":50,"minimum":1,"description":"Maximum number of search results returned by this knowledge base capability."},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}}}},"required":["kb"]}]}},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-zA-Z0-9_]+$"}},"required":["name"]},"description":"Variables such as dialplan variables that can be used in the bot."}},"required":["prompt"]}},"required":["llm"]},{"type":"object","title":"dialogflowCx","properties":{"dialogflowCx":{"type":"object","properties":{"credentials":{"description":"Dialogflow Service Account Credentials"},"agent":{"type":"string","description":"Dialogflow Agent Id (example - 88ff4635-0852-4f97-ae44-b19ae9fa6ea1"},"location":{"type":"string","description":"Dialogflow Agent Region (example: europe-west3)"},"language":{"type":"string","description":"Language"}},"required":["agent","credentials","language","location"]}},"required":["dialogflowCx"]},{"type":"object","title":"openAiAssistant","properties":{"openAiAssistant":{"type":"object","properties":{"key":{"type":"string"},"assistantId":{"type":"string"}},"required":["assistantId","key"]}},"required":["openAiAssistant"]},{"type":"object","title":"webhook","properties":{"webhook":{"type":"object","properties":{"url":{"type":"string"},"secret":{"type":"string"}},"required":["secret","url"]}},"required":["webhook"]},{"type":"object","title":"sqs","properties":{"sqs":{"type":"object","properties":{"url":{"type":"string"},"key":{"type":"string"},"secret":{"type":"string"}},"required":["key","secret","url"]}},"required":["sqs"]}]},"capabilities":{"type":"array","items":{"oneOf":[{"type":"object","title":"tool","properties":{"tool":{"type":"object","properties":{"id":{"type":"string","maxLength":12,"minLength":12,"pattern":"^[0-9A-Za-z]{12}$","description":"Unique identifier of the tool using nanoid format"},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-zA-Z0-9_]+$","description":"Name of the tool variable, e.g.: 'myvar'"},"handler":{"oneOf":[{"type":"object","title":"auto","properties":{"auto":{"type":"object"}},"required":["auto"]},{"type":"object","title":"guided","properties":{"guided":{"type":"object","properties":{"description":{"type":"string","maxLength":1024,"minLength":1}},"required":["description"]}},"required":["guided"]},{"type":"object","title":"predefined","properties":{"predefined":{"type":"object","properties":{"description":{"type":"string"}},"required":["description"]}},"required":["predefined"]}]}},"required":["name"]}},"startMessage":{"type":"string","description":"Message spoken when the tool call starts. Spoken in every language of the call while `startMessages` is absent or empty; not consulted once `startMessages` carries any entry."},"startMessages":{"type":"array","items":{"type":"object","description":"One phrase in one language, for a tool that speaks a fixed line when its call starts. Which\n  entry is spoken is decided by the call's current language — the one resolved at connect, or the\n  one automatic detection switched to — matched on `language` CASE-INSENSITIVELY, because older\n  records on this stack hold lower-cased codes; `AgentSpokenPhrase` matches the same way, so the\n  two stacks cannot disagree about which entry a code reaches. Blank `text` means the agent says\n  nothing in that language; it does NOT fall back to `startMessage`, which would speak one\n  language's text in another language's voice.","properties":{"language":{"type":"string","maxLength":8,"minLength":2,"pattern":"^[a-z]{2,3}(-[A-Z]{2})?$","description":"BCP-47 language tag, optionally with a region subtag: 'en', 'en-US', 'pt-BR'. Deliberately a\n    constrained string rather than an enum: the offerable set is a property of the selected\n    recogniser and changes with it, so an enumeration here would cap the set at whatever was known\n    when the model was released."},"text":{"type":"string"}},"required":["language","text"]},"description":"Per-language start messages. When present and non-empty, the entry for the call's current\n    language is spoken and `startMessage` is not consulted; a language with no entry is silent.\n    When absent or empty, `startMessage` is spoken as before. On a call with no effective speech\n    configuration — no configured languages, or a PBX below protocol 2 — `startMessage` is spoken\n    regardless, because there is no current language to choose by."},"pipeline":{"type":"object","properties":{"type":{"type":"string","enum":["blocking_request","blocking_request_guided","async_request","async_request_guided"]},"instructions":{"type":"string","description":"Instructions for generating a reply when using guided pipeline types. Use {{response}} to reference the tool response."}}},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}},"required":["id"]}},"required":["tool"]},{"type":"object","title":"kb","properties":{"kb":{"type":"object","properties":{"knowledgeBaseId":{"type":"string"},"instructions":{"type":"string","description":"Additional instructions for when the bot should use this knowledge base."},"searchStrategy":{"type":"string","enum":["bm25","vector","hybrid"]},"searchThreshold":{"type":"string","enum":["low","medium","high"]},"searchLimit":{"type":"number","maximum":50,"minimum":1,"description":"Maximum number of search results returned by this knowledge base capability."},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}}}},"required":["kb"]}]}},"groupId":{"type":"string","description":"PBX group ID for ACL-based visibility in Sales Intelligence."}},"required":["endpoint","name"]}}}},"/v2/voicebots/bots/{botId}":{"get":{"operationId":"GetVoiceBot","summary":"","description":"Retrieves details of a specific voice bot by its unique identifier.\n\n### Allowed Auth Scopes\n\n- voicebots:GetVoiceBot\n- voicebots:read","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","maxLength":12,"minLength":12}},{"name":"company","in":"query","required":false,"schema":{"type":"string"}}]},"put":{"operationId":"UpdateVoiceBot","summary":"","description":"Updates the configuration of an existing voice bot with new settings.\n\n### Allowed Auth Scopes\n\n- voicebots:UpdateVoiceBot","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","maxLength":12,"minLength":12}},{"name":"company","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"minLength":3},"category":{"type":"string","maxLength":128,"minLength":1,"description":"Category of the bot"},"message":{"type":"string","description":"The initial message that will be played at the start of the session."},"pipeline":{"type":"object","properties":{"interuptionsEnabled":{"type":"boolean","description":"If enabled the user can interrupt the the bot playback."},"maximumDuration":{"type":"number","description":"The maximum number of seconds a call will last."},"maximumDurationAction":{"oneOf":[{"type":"object","title":"hangup","properties":{"hangup":{"type":"object"}},"required":["hangup"]},{"type":"object","title":"transfer","properties":{"transfer":{"type":"object","properties":{"context":{"type":"string"},"extension":{"type":"string"}},"required":["context","extension"]}},"required":["transfer"]}]},"silenceTimeout":{"type":"number","description":"How long to wait before a call is automatically ended due to inactivity."},"silenceTimeoutAction":{"oneOf":[{"type":"object","title":"hangup","properties":{"hangup":{"type":"object"}},"required":["hangup"]},{"type":"object","title":"transfer","properties":{"transfer":{"type":"object","properties":{"context":{"type":"string"},"extension":{"type":"string"}},"required":["context","extension"]}},"required":["transfer"]}]},"endCallEnabled":{"type":"boolean","description":"If enabled the bot can hangup the call."},"endCallPhases":{"type":"string","description":"A list of phases separated by comma, which will end the call matched."}}},"speech":{"type":"object","description":"Speech configuration. When present it wins over the dialplan's `voice` and `initialMessage` connect parameters; `language` is the exception.","properties":{"languages":{"type":"array","items":{"type":"object","description":"One configured language: its voice, its initial phrase and its pronunciation rules.","properties":{"code":{"type":"string","maxLength":8,"minLength":2,"pattern":"^[a-z]{2,3}(-[A-Z]{2})?$","description":"BCP-47 code with locale, e.g. 'en-US'."},"voice":{"type":"string","maxLength":1024,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*://[a-zA-Z0-9._~/-]+(\\?[a-zA-Z0-9._~%&=+:/-]*)?$","description":"Voice this language speaks with, as a URI — provider, voice id, synthesis parameters and,\n    where the company uses its own provider account, its `apiKey` query parameter. See\n    VoiceBotVoiceUri.\n\n    PER LANGUAGE, and that is the whole reason the member is here rather than on the settings\n    above: provider quality is not uniform across languages, a voice id belongs to exactly one\n    provider, and a bot-wide provider made changing it invalidate every configured voice at once."},"greeting":{"type":"string","description":"Initial phrase for this language. Absent or empty means the agent says nothing and\n    waits — it does NOT fall back to the agent-level message, which would speak one\n    language's text in another language's voice."},"isDefault":{"type":"boolean","description":"Marks the language a caller hears when their own matches nothing configured.\n\n    THE FULL RESOLUTION ORDER, since a client author reading only this contract cannot\n    otherwise find it: an exact match on the call's language, then a match on its primary\n    subtag (`fr` finds `fr-FR`), then the language marked here, then a language whose\n    primary subtag is `en`, then the first entry in the list.\n\n    Marked is consulted BEFORE the English step, so a record with none marked resolves\n    exactly as it did before this member existed. English is deliberate rather than\n    arbitrary — it is the language a caller the agent was not built for is likeliest to\n    understand — and the last step exists only to keep the rule total, which is why list\n    order should not be treated as configuration.\n\n    At most one language may carry it. A record with two — reachable through the API or\n    the CLI, where no form prevents it — resolves to the first marked one in list order,\n    because refusing a call over configuration drift is worse than serving it and saying\n    so in the trace."},"pronunciations":{"type":"array","items":{"type":"object","description":"A pronunciation rule for one phrase, belonging to one language.","properties":{"phrase":{"type":"string","maxLength":200,"description":"The written form to replace. Bounded because every rule is compiled into ONE regular expression — see the list below."},"as":{"type":"string","maxLength":200,"description":"Respelling (ALIAS) or phonetic transcription (IPA)."},"encoding":{"type":"string","enum":["alias","ipa"]}},"required":["as","phrase"]},"maxItems":200,"description":"Pronunciation rules for one language.\n\n    BOUNDED, and the bound is not decoration. `applyPronunciations` compiles every rule of a\n    language into a SINGLE alternating regular expression, so the cost is the pattern's total\n    size: measured against the real escaping and matching logic, 1,000 rules cost ~0.9 s of CPU\n    per synthesized sentence, 5,000 cost ~4.9 s, and around 10,000 `new RegExp` throws V8's\n    pattern-size error outright — from a call site outside the surrounding `try`, so a 500 rather\n    than a degraded reply. Stored on a bot, that made every utterance of the agent fail.\n\n    200 is far above any real use — a product glossary is a handful of names — and far below\n    where either cost begins. Found by a security review.\n    NO LOWER BOUND on `phrase` or `as`, deliberately. Both consoles add an EMPTY rule row the\n    moment someone clicks 'Add pronunciation', so a `min: 1` would make saving an agent with a\n    half-typed row fail entirely — and the runtime already ignores a rule with no phrase. Dropping\n    blank rows belongs in the consoles' save filters, not in a refusal here."}},"required":["code","voice"]},"maxItems":10,"minItems":1,"description":"Configured languages. The @length bound is a storage ceiling; the real cap is the recogniser's own candidate limit, enforced in the service."},"greetEveryLanguage":{"type":"boolean","description":"Speak the first message of every configured language in turn when the call is answered, each in its own language's voice, provider account and pronunciation rules. Languages with an empty first message, 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."},"transcription":{"type":"object","description":"Speech-to-text configuration: which recogniser listens to the caller, and whether it identifies the language while it does.","properties":{"engine":{"type":"string","maxLength":1024,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*://[a-zA-Z0-9._~/-]+(\\?[a-zA-Z0-9._~%&=+:/-]*)?$","description":"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."},"autoDetect":{"type":"boolean","description":"Identify the caller's language per utterance and switch voice and reply language mid-call.\n\n    HERE RATHER THAN ON `VoiceBotSpeechSettings`, because identifying a language is something the\n    RECOGNISER does: it becomes identify-multiple-languages plus language-options on the\n    recognition stream, and nothing about synthesis reads it.\n\n    Requires at least two configured languages and a recogniser that can identify them; the server\n    clamps it to false otherwise, because forwarding true with a single candidate makes Amazon\n    reject the stream outright."}}}},"required":["languages"]},"backgroundSound":{"type":"object","description":"Ambient background audio played under the call.\n\n  A SETTINGS OBJECT rather than a loose name on the bot, matching `wildix.wilma.agents`: it is one\n  switchable call behaviour, and the volume and fade controls the console will want next have\n  somewhere to go.\n\n  ABSENT MEANS OFF — a bot that never touches it behaves exactly as every call did before this\n  setting existed, and the PBX needs no new case.","properties":{"enabled":{"type":"boolean","description":"Whether ambient background audio plays under the call."},"sound":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[^\\r\\n]+$","description":"Music-on-hold class the PBX plays. Absent with `enabled` true leaves the choice of class to the PBX."}},"required":["enabled"]},"endpoint":{"oneOf":[{"type":"object","title":"llm","properties":{"llm":{"type":"object","properties":{"prompt":{"type":"string","maxLength":40000},"model":{"type":"string","default":"default","pattern":"^(default|([a-z0-9][a-z0-9-]*://[a-zA-Z0-9._/-]+(\\?[a-zA-Z0-9._&=%-]*)?))$","description":"The AI model to use for generating responses. If not specified, uses the default model."},"guidelines":{"type":"array","items":{"type":"string","maxLength":12,"minLength":12}},"metadata":{"type":"object","properties":{"userName":{"type":"object","properties":{"enabled":{"type":"boolean","default":true,"description":"Whether this metadata field is enabled"}},"required":["enabled"]},"userPhoneNumber":{"type":"object","properties":{"enabled":{"type":"boolean","default":true,"description":"Whether this metadata field is enabled"}},"required":["enabled"]},"userEmail":{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether this metadata field is enabled"}},"required":["enabled"]},"userCompany":{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether this metadata field is enabled"}},"required":["enabled"]},"time":{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether this metadata field is enabled"},"timeZone":{"type":"string","default":"UTC","description":"Timezone for time formatting (e.g., 'Europe/Rome', 'UTC')"}},"required":["enabled","timeZone"]}}},"embeddedTools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["HANGUP","TRANSFER","DELEGATE","WAIT"]},"name":{"type":"string"},"parameters":{"description":"The parameters the functions accepts."},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}},"required":["name","type"]},"description":"Embedded functions to use within voice session."},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["function"]},"function":{"type":"object","properties":{"name":{"type":"string","description":"The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64."},"description":{"type":"string","description":"A description of what the function does, used by the model to choose when and how to call the function."},"parameters":{"description":"The parameters the functions accepts, described as a JSON Schema object."},"integration":{"oneOf":[{"type":"object","title":"webhook","properties":{"webhook":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["get","post","put","delete","patch"]},"async":{"type":"boolean"},"authorization":{"oneOf":[{"type":"object","title":"bearer","properties":{"bearer":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}},"required":["bearer"]},{"type":"object","title":"basic","properties":{"basic":{"type":"object","properties":{"username":{"type":"string"},"password":{"type":"string"}},"required":["password","username"]}},"required":["basic"]},{"type":"object","title":"oauth","properties":{"oauth":{"type":"object","properties":{"clientId":{"type":"string"},"clientSecret":{"type":"string"},"endpointUrl":{"type":"string"},"scope":{"type":"string"}},"required":["clientId","clientSecret","endpointUrl"]}},"required":["oauth"]}]},"headers":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]}},"timeout":{"type":"number","maximum":120000,"minimum":5000,"description":"Timeout in milliseconds for the webhook request."},"startMessage":{"type":"string","description":"Message spoken when the function call starts."},"parameters":{}},"required":["url"]}},"required":["webhook"]}]}},"required":["name"]},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}},"required":["type"]},"description":"Custom tools to be used within voice session."},"capabilities":{"type":"array","items":{"oneOf":[{"type":"object","title":"tool","properties":{"tool":{"type":"object","properties":{"id":{"type":"string","maxLength":12,"minLength":12,"pattern":"^[0-9A-Za-z]{12}$","description":"Unique identifier of the tool using nanoid format"},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-zA-Z0-9_]+$","description":"Name of the tool variable, e.g.: 'myvar'"},"handler":{"oneOf":[{"type":"object","title":"auto","properties":{"auto":{"type":"object"}},"required":["auto"]},{"type":"object","title":"guided","properties":{"guided":{"type":"object","properties":{"description":{"type":"string","maxLength":1024,"minLength":1}},"required":["description"]}},"required":["guided"]},{"type":"object","title":"predefined","properties":{"predefined":{"type":"object","properties":{"description":{"type":"string"}},"required":["description"]}},"required":["predefined"]}]}},"required":["name"]}},"startMessage":{"type":"string","description":"Message spoken when the tool call starts. Spoken in every language of the call while `startMessages` is absent or empty; not consulted once `startMessages` carries any entry."},"startMessages":{"type":"array","items":{"type":"object","description":"One phrase in one language, for a tool that speaks a fixed line when its call starts. Which\n  entry is spoken is decided by the call's current language — the one resolved at connect, or the\n  one automatic detection switched to — matched on `language` CASE-INSENSITIVELY, because older\n  records on this stack hold lower-cased codes; `AgentSpokenPhrase` matches the same way, so the\n  two stacks cannot disagree about which entry a code reaches. Blank `text` means the agent says\n  nothing in that language; it does NOT fall back to `startMessage`, which would speak one\n  language's text in another language's voice.","properties":{"language":{"type":"string","maxLength":8,"minLength":2,"pattern":"^[a-z]{2,3}(-[A-Z]{2})?$","description":"BCP-47 language tag, optionally with a region subtag: 'en', 'en-US', 'pt-BR'. Deliberately a\n    constrained string rather than an enum: the offerable set is a property of the selected\n    recogniser and changes with it, so an enumeration here would cap the set at whatever was known\n    when the model was released."},"text":{"type":"string"}},"required":["language","text"]},"description":"Per-language start messages. When present and non-empty, the entry for the call's current\n    language is spoken and `startMessage` is not consulted; a language with no entry is silent.\n    When absent or empty, `startMessage` is spoken as before. On a call with no effective speech\n    configuration — no configured languages, or a PBX below protocol 2 — `startMessage` is spoken\n    regardless, because there is no current language to choose by."},"pipeline":{"type":"object","properties":{"type":{"type":"string","enum":["blocking_request","blocking_request_guided","async_request","async_request_guided"]},"instructions":{"type":"string","description":"Instructions for generating a reply when using guided pipeline types. Use {{response}} to reference the tool response."}}},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}},"required":["id"]}},"required":["tool"]},{"type":"object","title":"kb","properties":{"kb":{"type":"object","properties":{"knowledgeBaseId":{"type":"string"},"instructions":{"type":"string","description":"Additional instructions for when the bot should use this knowledge base."},"searchStrategy":{"type":"string","enum":["bm25","vector","hybrid"]},"searchThreshold":{"type":"string","enum":["low","medium","high"]},"searchLimit":{"type":"number","maximum":50,"minimum":1,"description":"Maximum number of search results returned by this knowledge base capability."},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}}}},"required":["kb"]}]}},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-zA-Z0-9_]+$"}},"required":["name"]},"description":"Variables such as dialplan variables that can be used in the bot."}},"required":["prompt"]}},"required":["llm"]},{"type":"object","title":"dialogflowCx","properties":{"dialogflowCx":{"type":"object","properties":{"credentials":{"description":"Dialogflow Service Account Credentials"},"agent":{"type":"string","description":"Dialogflow Agent Id (example - 88ff4635-0852-4f97-ae44-b19ae9fa6ea1"},"location":{"type":"string","description":"Dialogflow Agent Region (example: europe-west3)"},"language":{"type":"string","description":"Language"}},"required":["agent","credentials","language","location"]}},"required":["dialogflowCx"]},{"type":"object","title":"openAiAssistant","properties":{"openAiAssistant":{"type":"object","properties":{"key":{"type":"string"},"assistantId":{"type":"string"}},"required":["assistantId","key"]}},"required":["openAiAssistant"]},{"type":"object","title":"webhook","properties":{"webhook":{"type":"object","properties":{"url":{"type":"string"},"secret":{"type":"string"}},"required":["secret","url"]}},"required":["webhook"]},{"type":"object","title":"sqs","properties":{"sqs":{"type":"object","properties":{"url":{"type":"string"},"key":{"type":"string"},"secret":{"type":"string"}},"required":["key","secret","url"]}},"required":["sqs"]}]},"capabilities":{"type":"array","items":{"oneOf":[{"type":"object","title":"tool","properties":{"tool":{"type":"object","properties":{"id":{"type":"string","maxLength":12,"minLength":12,"pattern":"^[0-9A-Za-z]{12}$","description":"Unique identifier of the tool using nanoid format"},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-zA-Z0-9_]+$","description":"Name of the tool variable, e.g.: 'myvar'"},"handler":{"oneOf":[{"type":"object","title":"auto","properties":{"auto":{"type":"object"}},"required":["auto"]},{"type":"object","title":"guided","properties":{"guided":{"type":"object","properties":{"description":{"type":"string","maxLength":1024,"minLength":1}},"required":["description"]}},"required":["guided"]},{"type":"object","title":"predefined","properties":{"predefined":{"type":"object","properties":{"description":{"type":"string"}},"required":["description"]}},"required":["predefined"]}]}},"required":["name"]}},"startMessage":{"type":"string","description":"Message spoken when the tool call starts. Spoken in every language of the call while `startMessages` is absent or empty; not consulted once `startMessages` carries any entry."},"startMessages":{"type":"array","items":{"type":"object","description":"One phrase in one language, for a tool that speaks a fixed line when its call starts. Which\n  entry is spoken is decided by the call's current language — the one resolved at connect, or the\n  one automatic detection switched to — matched on `language` CASE-INSENSITIVELY, because older\n  records on this stack hold lower-cased codes; `AgentSpokenPhrase` matches the same way, so the\n  two stacks cannot disagree about which entry a code reaches. Blank `text` means the agent says\n  nothing in that language; it does NOT fall back to `startMessage`, which would speak one\n  language's text in another language's voice.","properties":{"language":{"type":"string","maxLength":8,"minLength":2,"pattern":"^[a-z]{2,3}(-[A-Z]{2})?$","description":"BCP-47 language tag, optionally with a region subtag: 'en', 'en-US', 'pt-BR'. Deliberately a\n    constrained string rather than an enum: the offerable set is a property of the selected\n    recogniser and changes with it, so an enumeration here would cap the set at whatever was known\n    when the model was released."},"text":{"type":"string"}},"required":["language","text"]},"description":"Per-language start messages. When present and non-empty, the entry for the call's current\n    language is spoken and `startMessage` is not consulted; a language with no entry is silent.\n    When absent or empty, `startMessage` is spoken as before. On a call with no effective speech\n    configuration — no configured languages, or a PBX below protocol 2 — `startMessage` is spoken\n    regardless, because there is no current language to choose by."},"pipeline":{"type":"object","properties":{"type":{"type":"string","enum":["blocking_request","blocking_request_guided","async_request","async_request_guided"]},"instructions":{"type":"string","description":"Instructions for generating a reply when using guided pipeline types. Use {{response}} to reference the tool response."}}},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}},"required":["id"]}},"required":["tool"]},{"type":"object","title":"kb","properties":{"kb":{"type":"object","properties":{"knowledgeBaseId":{"type":"string"},"instructions":{"type":"string","description":"Additional instructions for when the bot should use this knowledge base."},"searchStrategy":{"type":"string","enum":["bm25","vector","hybrid"]},"searchThreshold":{"type":"string","enum":["low","medium","high"]},"searchLimit":{"type":"number","maximum":50,"minimum":1,"description":"Maximum number of search results returned by this knowledge base capability."},"annotations":{"type":"array","items":{"description":"Configuration for annotations emitted after a tool completes. Tag and comment annotations can provide a handlebars value, while variables and result annotations opt into logging runtime data.","oneOf":[{"type":"object","title":"tag","properties":{"tag":{"type":"object","description":"Tag annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["tag"]},{"type":"object","title":"comment","properties":{"comment":{"type":"object","description":"Comment annotation emitted after a voice bot tool completes.","properties":{"value":{"type":"string","description":"Static handlebars expression resolved against bot variables and helpers."},"applyOnSuccess":{"type":"boolean","description":"Apply when the tool succeeds."},"applyOnFailure":{"type":"boolean","description":"Apply when the tool fails."}}}},"required":["comment"]},{"type":"object","title":"variables","properties":{"variables":{"type":"object","description":"Variables annotation emitted after a voice bot tool completes."}},"required":["variables"]},{"type":"object","title":"result","properties":{"result":{"type":"object","description":"Result annotation emitted after a voice bot tool completes."}},"required":["result"]}]}}}}},"required":["kb"]}]}},"groupId":{"type":"string","description":"PBX group ID for ACL-based visibility in Sales Intelligence."}},"required":["endpoint","name"]}}},"delete":{"operationId":"DeleteVoiceBot","summary":"","description":"Deletes an existing voice bot and all its associated data.\n\n### Allowed Auth Scopes\n\n- voicebots:DeleteVoiceBot","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","maxLength":12,"minLength":12}},{"name":"company","in":"query","required":false,"schema":{"type":"string"}}]}},"/v2/voicebots/describe":{"post":{"operationId":"DescribeEvent","summary":"","description":"Utility method to describe available events for websocket and webhook events.\n\n### Allowed Auth Scopes\n\n- voicebots:DescribeEvent","parameters":[]}},"/v2/voicebots/names":{"get":{"operationId":"ListVoiceBotsNames","summary":"","description":"Retrieves a list of voice bot names and basic information for the specified company.\n\n### Allowed Auth Scopes\n\n- voicebots:ListVoiceBotsNames\n- voicebots:read","parameters":[{"name":"company","in":"query","required":false,"schema":{"type":"string"}}]}},"/v2/voicebots/sessions/{sessionId}/hangup":{"post":{"operationId":"SendHangup","summary":"","description":"Terminates the voice session and the call.\n\n### Allowed Auth Scopes\n\n- voicebots:SendHangup","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"/v2/voicebots/sessions/{sessionId}/play":{"post":{"operationId":"SendPlay","summary":"","description":"Plays the specified audio chunk through the audio stream of the voice session.\n\n### Allowed Auth Scopes\n\n- voicebots:SendPlay","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"schema":{"type":"object","properties":{"replyId":{"type":"string"},"streamId":{"type":"string"},"data":{"type":"string","description":"The audio chunk is encoded in base64 and should be played in the stream. The chunk must use the sample rate specified in the \"say\" command and be PCM encoded."}},"required":["data","replyId","streamId"]}}}},"/v2/voicebots/sessions/{sessionId}/say":{"post":{"operationId":"SendSay","summary":"","description":"Generates and plays the specified text through the audio stream of the voice session.\n\n### Allowed Auth Scopes\n\n- voicebots:SendSay","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"schema":{"type":"object","properties":{"text":{"type":"string"},"replyId":{"type":"string"},"interruptible":{"type":"boolean"},"voice":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9]+$","description":"Bare Amazon Polly voice id, e.g. 'Joanna' — NOT a URI. The PBX consumes this verbatim as the\n    AMI `Voice=` action parameter, so it takes exactly what Polly names the voice, with the\n    `amazon_polly://` scheme and any query parameters already stripped by whoever builds this\n    command out of the bot's stored `VoiceBotVoiceUri`.\n\n    Set only for a provider whose synthesis runs ON THE PBX (Amazon Polly); ElevenLabs and Google\n    are synthesized in the cloud and streamed as PCM through `play` instead, and leave this\n    absent."},"audio":{"type":"object","properties":{"streamId":{"type":"string"},"sampleRate":{"type":"number"}},"required":["sampleRate","streamId"]}},"required":["replyId","text"]}}}},"/v2/voicebots/sessions/{sessionId}/stop":{"post":{"operationId":"SendStop","summary":"","description":"Stop playing and ongoing audio from the voice bot.\n\n### Allowed Auth Scopes\n\n- voicebots:SendStop","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}]}},"/v2/voicebots/sessions/{sessionId}/transfer":{"post":{"operationId":"SendTransfer","summary":"","description":"Transfers the call to the specified context and extension, and terminates the voice bot session.\n\n### Allowed Auth Scopes\n\n- voicebots:SendTransfer","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"schema":{"type":"object","properties":{"context":{"type":"string"},"extension":{"type":"string"}},"required":["context","extension"]}}}},"/v2/voicebots/text-to-speech":{"post":{"operationId":"TextToSpeech","summary":"","description":"Synthesizes one phrase and returns MP3.\n\n    NOT NAMED FOR THE PREVIEW IT SERVES. Auditioning an unsaved voice in the console is the first\n    caller, but nothing about the operation is preview-specific — it is the platform's\n    text-to-speech, reachable by anything holding the scope, and a name naming one caller's screen\n    would have to be worked around by the second one.\n\n    The operation reads no stored bot for the audition itself: the exact voice URI, including any\n    custom account key, travels in the request so the audition and runtime cannot diverge. `botId`\n    is the one exception, for a language whose key is masked (`apiKey=stored`) in that URI: it\n    lets the server resolve the bot's stored key server-side instead of the caller round-tripping\n    a key it was never given back. It only substitutes which key authenticates the synthesis call\n    — the response never carries the key either way.\n\n### Allowed Auth Scopes\n\n- voicebots:TextToSpeech\n- voicebots:UpdateVoiceBot","parameters":[],"requestBody":{"required":true,"schema":{"type":"object","properties":{"voice":{"type":"string","maxLength":1024,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*://[a-zA-Z0-9._~/-]+(\\?[a-zA-Z0-9._~%&=+:/-]*)?$","description":"Voice to speak with, as the URI a call would use — provider, voice id, synthesis parameters and, for a custom account, `apiKey`. Passing the call's own value is what keeps an audition from diverging from the call it is auditioning."},"language":{"type":"string","maxLength":8,"minLength":2,"pattern":"^[a-z]{2,3}(-[A-Z]{2})?$","description":"Language the phrase is in."},"text":{"type":"string","maxLength":2000,"minLength":1,"description":"Text to speak, before pronunciation rules are applied."},"pronunciations":{"type":"array","items":{"type":"object","description":"A pronunciation rule for one phrase, belonging to one language.","properties":{"phrase":{"type":"string","maxLength":200,"description":"The written form to replace. Bounded because every rule is compiled into ONE regular expression — see the list below."},"as":{"type":"string","maxLength":200,"description":"Respelling (ALIAS) or phonetic transcription (IPA)."},"encoding":{"type":"string","enum":["alias","ipa"]}},"required":["as","phrase"]},"maxItems":200,"description":"Pronunciation rules for this language, applied SERVER-SIDE by the same helper the call path uses — never pre-applied by the caller, or the form reimplements a rule the server owns and can silently diverge from the call."},"botId":{"type":"string","maxLength":12,"minLength":12,"description":"The bot whose language this audition speaks for. Resolves the language's STORED private\n      key server-side when that language's key is masked (`apiKey=stored`) rather than the caller\n      round-tripping a key it was never given back. The key itself is never returned — it is used\n      only to authenticate against the provider."}},"required":["language","text","voice"]}}}},"/v2/voicebots/traces":{"get":{"operationId":"ListTraces","summary":"","description":"Retrieves a list of voice bot trace sessions for the specified company.\n\n### Allowed Auth Scopes\n\n- voicebots:ListTraces\n- voicebots:read","parameters":[{"name":"company","in":"query","required":false,"schema":{"type":"string"}},{"name":"search","in":"query","required":false,"schema":{"type":"string","description":"Optional search query to filter traces by caller name, bot name, or session ID."},"description":"Optional search query to filter traces by caller name, bot name, or session ID."}]}},"/v2/voicebots/traces/{sessionId}":{"get":{"operationId":"GetTrace","summary":"","description":"Retrieves detailed trace information for a specific voice bot session.\n\n### Allowed Auth Scopes\n\n- voicebots:GetTrace\n- voicebots:read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"company","in":"query","required":false,"schema":{"type":"string"}}]}},"/v2/voicebots/voices":{"get":{"operationId":"ListVoices","summary":"","description":"Lists the voices a synthesis provider offers, read from the provider's own API. Answers a URI\n    per voice, so a picker stores what it selected rather than composing one.\n\n    A catalog is a property of the provider and the account, not a stored bot: a form needs the\n    speaker list before the bot it is configuring exists, and for that pre-bot case the caller\n    supplies its key on `credential`, then appends it to the voice URI it stores. `botId` is the\n    one exception, for an already-saved bot whose language key is masked (`apiKey=stored`): it\n    lets the server resolve that stored key instead of the caller round-tripping a key it was\n    never given back. It only substitutes which key authenticates the request — the response\n    never carries the key either way.\n\n### Allowed Auth Scopes\n\n- voicebots:ListVoices\n- voicebots:read","parameters":[{"name":"provider","in":"query","required":true,"schema":{"type":"string","maxLength":32,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"Provider whose catalog to read: 'elevenlabs', 'google', 'amazon_polly'. This is the scheme of the URIs answered on `voices`."},"description":"Provider whose catalog to read: 'elevenlabs', 'google', 'amazon_polly'. This is the scheme of the URIs answered on `voices`."},{"name":"language","in":"query","required":false,"schema":{"type":"string","maxLength":8,"minLength":2,"pattern":"^[a-z]{2,3}(-[A-Z]{2})?$","description":"Server-side filter for language-bound providers: only voices whose language SET CONTAINS this code. Ignored for ElevenLabs, whose voices are not language bound."},"description":"Server-side filter for language-bound providers: only voices whose language SET CONTAINS this code. Ignored for ElevenLabs, whose voices are not language bound."},{"name":"botId","in":"query","required":false,"schema":{"type":"string","maxLength":12,"minLength":12,"description":"The bot whose language this catalog request previews. Resolves the language's STORED\n      private key server-side when that language's key is masked (`apiKey=stored`) rather than\n      the caller round-tripping a key it was never given back. The key itself is never returned —\n      it is used only to authenticate against the provider. When both `credential` and `botId`\n      are sent, `credential` wins."},"description":"The bot whose language this catalog request previews. Resolves the language's STORED\n      private key server-side when that language's key is masked (`apiKey=stored`) rather than\n      the caller round-tripping a key it was never given back. The key itself is never returned —\n      it is used only to authenticate against the provider. When both `credential` and `botId`\n      are sent, `credential` wins."},{"name":"x-wildix-provider-credential","in":"header","required":false,"schema":{"type":"string","maxLength":16384,"minLength":1,"description":"The company's own provider key, used to list that account's voices including cloned ones.\n      Absent means the platform account.\n\n      A header avoids putting the key in this GET request's URL, browser history and ordinary access\n      logs. It remains a secret at this boundary: never include it in a cache identity, response or\n      trace attribute. The stored voice URI deliberately makes a different legacy trade-off; see\n      VoiceBotVoiceUri.","format":"password"},"description":"The company's own provider key, used to list that account's voices including cloned ones.\n      Absent means the platform account.\n\n      A header avoids putting the key in this GET request's URL, browser history and ordinary access\n      logs. It remains a secret at this boundary: never include it in a cache identity, response or\n      trace attribute. The stored voice URI deliberately makes a different legacy trade-off; see\n      VoiceBotVoiceUri."}]}}}}