From e9f156dce751689e35cb7c1c3375674c28d4429c Mon Sep 17 00:00:00 2001 From: Devon-White Date: Thu, 20 Aug 2026 12:24:22 -0400 Subject: [PATCH 1/8] refactor(api): decouple SWML schemas from REST operations --- fern/apis/signalwire-rest/openapi.yaml | 794 +++++------------- .../calling-api/calls/models/requests.tsp | 11 +- .../fabric-api/ai-agent/models/core.tsp | 87 +- .../fabric-api/call-flows/models/core.tsp | 4 +- .../fabric-api/call-flows/models/requests.tsp | 6 +- .../call-flows/models/responses.tsp | 4 +- .../call-flows/versions/models/responses.tsp | 6 +- .../fabric-api/swml-scripts/models/core.tsp | 7 +- .../swml-scripts/models/requests.tsp | 8 +- specs/signalwire-rest/main.tsp | 1 + specs/signalwire-rest/swml-document.tsp | 9 + .../signalwire-rest/webhooks/calling/main.tsp | 1 - .../webhooks/messaging/main.tsp | 1 - specs/swml/calling/Methods/ai/main.tsp | 90 +- 14 files changed, 372 insertions(+), 657 deletions(-) create mode 100644 specs/signalwire-rest/swml-document.tsp diff --git a/fern/apis/signalwire-rest/openapi.yaml b/fern/apis/signalwire-rest/openapi.yaml index 832a5330c1..a66fa71254 100644 --- a/fern/apis/signalwire-rest/openapi.yaml +++ b/fern/apis/signalwire-rest/openapi.yaml @@ -15284,13 +15284,15 @@ components: - name properties: global_data: - allOf: - - $ref: '#/components/schemas/SWML.Calling.GlobalData' + type: object + unevaluatedProperties: {} description: |- A key-value object for storing data that persists throughout the AI session. Can be set initially in the SWML script or modified during the conversation using the set_global_data action. The global_data object is accessible everywhere in the AI session: prompts, AI parameters, and SWML returned from SWAIG functions. Access properties using template strings (e.g. ${global_data.property_name}). + + See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai). examples: - company_name: Acme Corp support_hours: 9am-5pm EST @@ -15299,57 +15301,84 @@ components: items: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.Hint' - description: Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. + - type: object + unevaluatedProperties: {} + description: |- + Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. + + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai). examples: - - pizza - pepperoni languages: type: array items: - $ref: '#/components/schemas/SWML.Calling.Languages' + type: object + unevaluatedProperties: {} description: |- An array of JSON objects defining supported languages in the conversation. Mutually exclusive with `multilingual`: if both are set, `multilingual` is used and this array is ignored. + + See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). multilingual: - allOf: - - $ref: '#/components/schemas/SWML.Calling.Multilingual' + type: object + unevaluatedProperties: {} description: |- Configures a single agent to detect the caller's language and answer in it, switching as the caller switches. Use this instead of `languages` when one conversation may span several languages. Mutually exclusive with `languages`: if both are set, `multilingual` is used and `languages` is ignored. + + See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). params: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIParams' - description: A JSON object containing parameters as key-value pairs. + type: object + unevaluatedProperties: {} + description: |- + A JSON object containing parameters as key-value pairs. + + See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). post_prompt: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIPostPrompt' - description: The final set of instructions and configuration settings to send to the agent. + type: object + unevaluatedProperties: {} + description: |- + The final set of instructions and configuration settings to send to the agent. + + See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). post_prompt_url: type: string format: uri - description: The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. + description: |- + The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. + + See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#post_prompt_url-callback). examples: - username:password@https://example.com pronounce: type: array items: - $ref: '#/components/schemas/SWML.Calling.Pronounce' - description: An array of JSON objects to clarify the AI's pronunciation of words or expressions. + type: object + unevaluatedProperties: {} + description: |- + An array of JSON objects to clarify the AI's pronunciation of words or expressions. + + See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). prompt: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIPrompt' + type: object + unevaluatedProperties: {} description: |- Defines the AI agent's personality, goals, behaviors, and instructions for handling conversations. The prompt establishes how the agent should interact with callers, what information it should gather, and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. + + See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). SWAIG: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWAIG' - description: An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. + type: object + unevaluatedProperties: {} + description: |- + An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. + + See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). agent_id: allOf: - $ref: '#/components/schemas/uuid' @@ -15363,7 +15392,13 @@ components: - My AI Agent unevaluatedProperties: not: {} - description: An AI Agent configuration that extends the SWML AI object with additional API-specific properties. + description: |- + Creates an AI agent that conducts voice conversations using automatic speech recognition (ASR), + large language models (LLMs), and text-to-speech (TTS) synthesis. + The agent processes caller speech in real-time, generates contextually appropriate responses, + and can execute custom functions to interact with external systems through SignalWire AI Gateway (SWAIG). + + See the [SWML `ai` method reference](/docs/swml/reference/calling/ai) for the complete configuration contract. title: AI Agent AIAgentAddressListResponse: type: object @@ -15390,13 +15425,15 @@ components: - name properties: global_data: - allOf: - - $ref: '#/components/schemas/SWML.Calling.GlobalData' + type: object + unevaluatedProperties: {} description: |- A key-value object for storing data that persists throughout the AI session. Can be set initially in the SWML script or modified during the conversation using the set_global_data action. The global_data object is accessible everywhere in the AI session: prompts, AI parameters, and SWML returned from SWAIG functions. Access properties using template strings (e.g. ${global_data.property_name}). + + See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai). examples: - company_name: Acme Corp support_hours: 9am-5pm EST @@ -15405,57 +15442,84 @@ components: items: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.Hint' - description: Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. + - type: object + unevaluatedProperties: {} + description: |- + Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. + + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai). examples: - - pizza - pepperoni languages: type: array items: - $ref: '#/components/schemas/SWML.Calling.Languages' + type: object + unevaluatedProperties: {} description: |- An array of JSON objects defining supported languages in the conversation. Mutually exclusive with `multilingual`: if both are set, `multilingual` is used and this array is ignored. + + See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). multilingual: - allOf: - - $ref: '#/components/schemas/SWML.Calling.Multilingual' + type: object + unevaluatedProperties: {} description: |- Configures a single agent to detect the caller's language and answer in it, switching as the caller switches. Use this instead of `languages` when one conversation may span several languages. Mutually exclusive with `languages`: if both are set, `multilingual` is used and `languages` is ignored. + + See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). params: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIParams' - description: A JSON object containing parameters as key-value pairs. + type: object + unevaluatedProperties: {} + description: |- + A JSON object containing parameters as key-value pairs. + + See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). post_prompt: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIPostPrompt' - description: The final set of instructions and configuration settings to send to the agent. + type: object + unevaluatedProperties: {} + description: |- + The final set of instructions and configuration settings to send to the agent. + + See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). post_prompt_url: type: string format: uri - description: The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. + description: |- + The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. + + See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#post_prompt_url-callback). examples: - username:password@https://example.com pronounce: type: array items: - $ref: '#/components/schemas/SWML.Calling.Pronounce' - description: An array of JSON objects to clarify the AI's pronunciation of words or expressions. + type: object + unevaluatedProperties: {} + description: |- + An array of JSON objects to clarify the AI's pronunciation of words or expressions. + + See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). prompt: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIPrompt' + type: object + unevaluatedProperties: {} description: |- Defines the AI agent's personality, goals, behaviors, and instructions for handling conversations. The prompt establishes how the agent should interact with callers, what information it should gather, and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. + + See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). SWAIG: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWAIG' - description: An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. + type: object + unevaluatedProperties: {} + description: |- + An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. + + See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). agent_id: allOf: - $ref: '#/components/schemas/uuid' @@ -15596,13 +15660,15 @@ components: type: object properties: global_data: - allOf: - - $ref: '#/components/schemas/SWML.Calling.GlobalData' + type: object + unevaluatedProperties: {} description: |- A key-value object for storing data that persists throughout the AI session. Can be set initially in the SWML script or modified during the conversation using the set_global_data action. The global_data object is accessible everywhere in the AI session: prompts, AI parameters, and SWML returned from SWAIG functions. Access properties using template strings (e.g. ${global_data.property_name}). + + See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai). examples: - company_name: Acme Corp support_hours: 9am-5pm EST @@ -15611,57 +15677,84 @@ components: items: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.Hint' - description: Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. + - type: object + unevaluatedProperties: {} + description: |- + Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. + + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai). examples: - - pizza - pepperoni languages: type: array items: - $ref: '#/components/schemas/SWML.Calling.Languages' + type: object + unevaluatedProperties: {} description: |- An array of JSON objects defining supported languages in the conversation. Mutually exclusive with `multilingual`: if both are set, `multilingual` is used and this array is ignored. + + See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). multilingual: - allOf: - - $ref: '#/components/schemas/SWML.Calling.MultilingualUpdate' + type: object + unevaluatedProperties: {} description: |- Configures a single agent to detect the caller's language and answer in it, switching as the caller switches. Use this instead of `languages` when one conversation may span several languages. Mutually exclusive with `languages`: if both are set, `multilingual` is used and `languages` is ignored. + + See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). params: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIParams' - description: A JSON object containing parameters as key-value pairs. + type: object + unevaluatedProperties: {} + description: |- + A JSON object containing parameters as key-value pairs. + + See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). post_prompt: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIPostPromptUpdate' - description: The final set of instructions and configuration settings to send to the agent. + type: object + unevaluatedProperties: {} + description: |- + The final set of instructions and configuration settings to send to the agent. + + See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). post_prompt_url: type: string format: uri - description: The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. + description: |- + The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. + + See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#post_prompt_url-callback). examples: - username:password@https://example.com pronounce: type: array items: - $ref: '#/components/schemas/SWML.Calling.Pronounce' - description: An array of JSON objects to clarify the AI's pronunciation of words or expressions. + type: object + unevaluatedProperties: {} + description: |- + An array of JSON objects to clarify the AI's pronunciation of words or expressions. + + See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). prompt: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIPromptUpdate' + type: object + unevaluatedProperties: {} description: |- Defines the AI agent's personality, goals, behaviors, and instructions for handling conversations. The prompt establishes how the agent should interact with callers, what information it should gather, and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. + + See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). SWAIG: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWAIG' - description: An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. + type: object + unevaluatedProperties: {} + description: |- + An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. + + See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). agent_id: allOf: - $ref: '#/components/schemas/uuid' @@ -17072,8 +17165,8 @@ components: examples: - {} relayml: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + type: object + unevaluatedProperties: {} description: The calling SWML document this Call Flow executes. Uses [calling SWML methods](/docs/swml/reference/calling). examples: - version: 1.0.0 @@ -17155,8 +17248,8 @@ components: examples: - {} relayml: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + type: object + unevaluatedProperties: {} description: The calling SWML document this Call Flow should execute. Uses [calling SWML methods](/docs/swml/reference/calling). Optional but must be paired with `flow_data` — provide both fields together or omit both. When both are omitted, SignalWire creates a starter SWML document. examples: - version: 1.0.0 @@ -17282,8 +17375,8 @@ components: examples: - {} relayml: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + type: object + unevaluatedProperties: {} description: The calling SWML document this Call Flow should execute. Uses [calling SWML methods](/docs/swml/reference/calling). examples: - version: 1.0.0 @@ -17350,8 +17443,8 @@ components: examples: - {} relayml: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + type: object + unevaluatedProperties: {} description: The calling SWML document this version snapshots. Uses [calling SWML methods](/docs/swml/reference/calling). examples: - version: 1.0.0 @@ -17430,8 +17523,8 @@ components: examples: - {} relayml: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + type: object + unevaluatedProperties: {} description: The calling SWML document deployed by this version. Uses [calling SWML methods](/docs/swml/reference/calling). examples: - version: 1.0.0 @@ -18070,7 +18163,8 @@ components: to_script: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + - type: object + unevaluatedProperties: {} description: Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. examples: - https://example.com/destination.swml.json @@ -18201,7 +18295,8 @@ components: to_script: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + - type: object + unevaluatedProperties: {} description: Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. examples: - https://example.com/destination.swml.json @@ -18302,8 +18397,8 @@ components: - id: '12345' case_number: '54321' swml: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + type: object + unevaluatedProperties: {} description: Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call. unevaluatedProperties: not: {} @@ -18337,7 +18432,8 @@ components: to_script: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + - type: object + unevaluatedProperties: {} description: Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. examples: - https://example.com/destination.swml.json @@ -19950,7 +20046,8 @@ components: dest: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + - type: object + unevaluatedProperties: {} description: The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline SWML object. examples: - sip:destination@example.com @@ -20096,8 +20193,8 @@ components: examples: - https://example.com/status_callback swml: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + type: object + unevaluatedProperties: {} description: Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call. unevaluatedProperties: not: {} @@ -21463,8 +21560,8 @@ components: examples: - https://example.com/swml_script contents: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + type: object + unevaluatedProperties: {} description: The calling SWML document executed when this script runs. Uses [calling SWML methods](/docs/swml/reference/calling). examples: - version: 1.0.0 @@ -21509,8 +21606,8 @@ components: - calling default: calling contents: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + type: object + unevaluatedProperties: {} description: The calling SWML document. Uses [calling SWML methods](/docs/swml/reference/calling). examples: - version: 1.0.0 @@ -21545,8 +21642,8 @@ components: - calling default: calling contents: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + type: object + unevaluatedProperties: {} description: The calling SWML document. Uses [calling SWML methods](/docs/swml/reference/calling). examples: - version: 1.0.0 @@ -28616,8 +28713,8 @@ components: examples: - https://example.com/swml_script contents: - allOf: - - $ref: '#/components/schemas/SWML.Messaging.SWMLObject' + type: object + unevaluatedProperties: {} description: The messaging SWML document executed when this script runs. Uses [messaging SWML methods](/docs/swml/reference/messaging). examples: - version: 1.0.0 @@ -28647,8 +28744,8 @@ components: examples: - messaging contents: - allOf: - - $ref: '#/components/schemas/SWML.Messaging.SWMLObject' + type: object + unevaluatedProperties: {} description: The messaging SWML document. Uses [messaging SWML methods](/docs/swml/reference/messaging). examples: - version: 1.0.0 @@ -28675,8 +28772,8 @@ components: examples: - messaging contents: - allOf: - - $ref: '#/components/schemas/SWML.Messaging.SWMLObject' + type: object + unevaluatedProperties: {} description: The messaging SWML document. Uses [messaging SWML methods](/docs/swml/reference/messaging). examples: - version: 1.0.0 @@ -33187,8 +33284,10 @@ components: unevaluatedProperties: not: {} title: Post-Prompt with POM - SWML.Calling.AIPostPromptPomUpdate: + SWML.Calling.AIPostPromptText: type: object + required: + - text properties: max_tokens: type: integer @@ -33242,155 +33341,22 @@ components: examples: - 0 default: 0 - pom: - type: array - items: - $ref: '#/components/schemas/SWML.Calling.POM' - minItems: 1 + text: + type: string description: The instructions to send to the agent. + examples: + - Summarize the conversation and provide any follow-up action items. unevaluatedProperties: not: {} - title: Post-Prompt with POM - SWML.Calling.AIPostPromptText: + title: Post-Prompt with Text + SWML.Calling.AIPrompt: + anyOf: + - $ref: '#/components/schemas/SWML.Calling.AIPromptText' + - $ref: '#/components/schemas/SWML.Calling.AIPromptPom' + SWML.Calling.AIPromptPom: type: object required: - - text - properties: - max_tokens: - type: integer - format: int32 - minimum: 0 - maximum: 4096 - description: Limits the amount of tokens that the AI agent may generate when creating its response - examples: - - 256 - default: 256 - temperature: - type: number - minimum: 0 - maximum: 1.5 - description: Randomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random. **Default:** `1.0`. - examples: - - 0.7 - default: 1 - top_p: - type: number - minimum: 0 - maximum: 1 - description: Randomness setting. Alternative to `temperature`. Float value between 0.0 and 1.0. Closer to 0 will make the output less random. **Default:** `1.0`. - examples: - - 0.9 - default: 1 - confidence: - type: number - minimum: 0 - maximum: 1 - description: |- - Threshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. - Decreasing this value will reduce the pause after the user speaks, but may introduce false positives. - **Default:** `0.6`. - examples: - - 0.6 - default: 0.6 - presence_penalty: - type: number - minimum: -2 - maximum: 2 - description: Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model's likelihood to talk about new topics. **Default:** `0`. - examples: - - 0 - default: 0 - frequency_penalty: - type: number - minimum: -2 - maximum: 2 - description: Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model's likelihood to repeat the same line verbatim. **Default:** `0`. - examples: - - 0 - default: 0 - text: - type: string - description: The instructions to send to the agent. - examples: - - Summarize the conversation and provide any follow-up action items. - unevaluatedProperties: - not: {} - title: Post-Prompt with Text - SWML.Calling.AIPostPromptTextUpdate: - type: object - properties: - max_tokens: - type: integer - format: int32 - minimum: 0 - maximum: 4096 - description: Limits the amount of tokens that the AI agent may generate when creating its response - examples: - - 256 - default: 256 - temperature: - type: number - minimum: 0 - maximum: 1.5 - description: Randomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random. **Default:** `1.0`. - examples: - - 0.7 - default: 1 - top_p: - type: number - minimum: 0 - maximum: 1 - description: Randomness setting. Alternative to `temperature`. Float value between 0.0 and 1.0. Closer to 0 will make the output less random. **Default:** `1.0`. - examples: - - 0.9 - default: 1 - confidence: - type: number - minimum: 0 - maximum: 1 - description: |- - Threshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. - Decreasing this value will reduce the pause after the user speaks, but may introduce false positives. - **Default:** `0.6`. - examples: - - 0.6 - default: 0.6 - presence_penalty: - type: number - minimum: -2 - maximum: 2 - description: Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model's likelihood to talk about new topics. **Default:** `0`. - examples: - - 0 - default: 0 - frequency_penalty: - type: number - minimum: -2 - maximum: 2 - description: Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model's likelihood to repeat the same line verbatim. **Default:** `0`. - examples: - - 0 - default: 0 - text: - type: string - description: The instructions to send to the agent. - examples: - - Summarize the conversation and provide any follow-up action items. - unevaluatedProperties: - not: {} - title: Post-Prompt with Text - SWML.Calling.AIPostPromptUpdate: - anyOf: - - $ref: '#/components/schemas/SWML.Calling.AIPostPromptTextUpdate' - - $ref: '#/components/schemas/SWML.Calling.AIPostPromptPomUpdate' - SWML.Calling.AIPrompt: - anyOf: - - $ref: '#/components/schemas/SWML.Calling.AIPromptText' - - $ref: '#/components/schemas/SWML.Calling.AIPromptPom' - SWML.Calling.AIPromptPom: - type: object - required: - - pom + - pom properties: max_tokens: type: integer @@ -33464,81 +33430,6 @@ components: unevaluatedProperties: not: {} title: Prompt with POM - SWML.Calling.AIPromptPomUpdate: - type: object - properties: - max_tokens: - type: integer - format: int32 - minimum: 0 - maximum: 4096 - description: Limits the amount of tokens that the AI agent may generate when creating its response - examples: - - 256 - default: 256 - temperature: - type: number - minimum: 0 - maximum: 1.5 - description: Randomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random. **Default:** `1.0`. - examples: - - 0.7 - default: 1 - top_p: - type: number - minimum: 0 - maximum: 1 - description: Randomness setting. Alternative to `temperature`. Float value between 0.0 and 1.0. Closer to 0 will make the output less random. **Default:** `1.0`. - examples: - - 0.9 - default: 1 - confidence: - type: number - minimum: 0 - maximum: 1 - description: |- - Threshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. - Decreasing this value will reduce the pause after the user speaks, but may introduce false positives. - **Default:** `0.6`. - examples: - - 0.6 - default: 0.6 - presence_penalty: - type: number - minimum: -2 - maximum: 2 - description: Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model's likelihood to talk about new topics. **Default:** `0`. - examples: - - 0 - default: 0 - frequency_penalty: - type: number - minimum: -2 - maximum: 2 - description: Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model's likelihood to repeat the same line verbatim. **Default:** `0`. - examples: - - 0 - default: 0 - pom: - type: array - items: - $ref: '#/components/schemas/SWML.Calling.POM' - minItems: 1 - description: |- - Prompt Object Model (POM) is a structured data format for composing, organizing, and rendering prompt instructions for AI agents. - POM ensures that the prompt is structured in a way that is best for the AI agent to understand and execute. - The first item in the array MUST be FirstPOMSection (with optional title). - All subsequent items MUST be PomSection (with required title and body). - contexts: - allOf: - - $ref: '#/components/schemas/SWML.Calling.ContextsUpdate' - description: |- - An object that defines the context steps for the AI. The context steps are used to define the flow of the conversation. - Every context object requires a `default` key, which is the default context to use at the beginning of the conversation. - Additionally, more context steps can be defined as any other key in the object. - unevaluatedProperties: - not: {} - title: Prompt with POM SWML.Calling.AIPromptText: type: object required: @@ -33611,80 +33502,6 @@ components: unevaluatedProperties: not: {} title: Prompt with Text - SWML.Calling.AIPromptTextUpdate: - type: object - properties: - max_tokens: - type: integer - format: int32 - minimum: 0 - maximum: 4096 - description: Limits the amount of tokens that the AI agent may generate when creating its response - examples: - - 256 - default: 256 - temperature: - type: number - minimum: 0 - maximum: 1.5 - description: Randomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random. **Default:** `1.0`. - examples: - - 0.7 - default: 1 - top_p: - type: number - minimum: 0 - maximum: 1 - description: Randomness setting. Alternative to `temperature`. Float value between 0.0 and 1.0. Closer to 0 will make the output less random. **Default:** `1.0`. - examples: - - 0.9 - default: 1 - confidence: - type: number - minimum: 0 - maximum: 1 - description: |- - Threshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. - Decreasing this value will reduce the pause after the user speaks, but may introduce false positives. - **Default:** `0.6`. - examples: - - 0.6 - default: 0.6 - presence_penalty: - type: number - minimum: -2 - maximum: 2 - description: Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model's likelihood to talk about new topics. **Default:** `0`. - examples: - - 0 - default: 0 - frequency_penalty: - type: number - minimum: -2 - maximum: 2 - description: Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model's likelihood to repeat the same line verbatim. **Default:** `0`. - examples: - - 0 - default: 0 - text: - type: string - description: The instructions to send to the agent. - examples: - - Your name is Franklin and you are taking orders for Franklin's Pizza. Begin by greeting the caller, and ask if they'd like to place an order for pickup or delivery. - contexts: - allOf: - - $ref: '#/components/schemas/SWML.Calling.ContextsUpdate' - description: |- - An object that defines the context steps for the AI. The context steps are used to define the flow of the conversation. - Every context object requires a `default` key, which is the default context to use at the beginning of the conversation. - Additionally, more context steps can be defined as any other key in the object. - unevaluatedProperties: - not: {} - title: Prompt with Text - SWML.Calling.AIPromptUpdate: - anyOf: - - $ref: '#/components/schemas/SWML.Calling.AIPromptTextUpdate' - - $ref: '#/components/schemas/SWML.Calling.AIPromptPomUpdate' SWML.Calling.AISidecar: type: object required: @@ -36542,10 +36359,6 @@ components: anyOf: - $ref: '#/components/schemas/SWML.Calling.ContextsPOMObject' - $ref: '#/components/schemas/SWML.Calling.ContextsTextObject' - SWML.Calling.ContextsObjectUpdate: - anyOf: - - $ref: '#/components/schemas/SWML.Calling.ContextsPOMObjectUpdate' - - $ref: '#/components/schemas/SWML.Calling.ContextsTextObjectUpdate' SWML.Calling.ContextsPOMObject: type: object required: @@ -36580,38 +36393,6 @@ components: unevaluatedProperties: not: {} title: ContextsPOMObject - SWML.Calling.ContextsPOMObjectUpdate: - type: object - properties: - steps: - type: array - items: - $ref: '#/components/schemas/SWML.Calling.ContextSteps' - description: An array of step objects that define the conversation flow for this context. Steps execute sequentially unless otherwise specified. - title: steps - isolated: - type: boolean - description: When `true`, resets conversation history to only the system prompt when entering this context. Useful for focused tasks that shouldn't be influenced by previous conversation. **Default:** `false`. - examples: - - true - default: false - enter_fillers: - allOf: - - $ref: '#/components/schemas/SWML.Calling.FunctionFillers' - description: Filler phrases played when entering this context, keyed by language code. - exit_fillers: - allOf: - - $ref: '#/components/schemas/SWML.Calling.FunctionFillers' - description: Filler phrases played when leaving this context, keyed by language code. - pom: - type: array - items: - $ref: '#/components/schemas/SWML.Calling.POM' - minItems: 1 - description: An array of objects that define the POM for the context. POM is the Post-Prompt Object Model, which is used to define the flow of the conversation. - unevaluatedProperties: - not: {} - title: ContextsPOMObject SWML.Calling.ContextsTextObject: type: object required: @@ -36644,46 +36425,6 @@ components: - You are now helping the customer with their order. unevaluatedProperties: not: {} - SWML.Calling.ContextsTextObjectUpdate: - type: object - properties: - steps: - type: array - items: - $ref: '#/components/schemas/SWML.Calling.ContextSteps' - description: An array of step objects that define the conversation flow for this context. Steps execute sequentially unless otherwise specified. - title: steps - isolated: - type: boolean - description: When `true`, resets conversation history to only the system prompt when entering this context. Useful for focused tasks that shouldn't be influenced by previous conversation. **Default:** `false`. - examples: - - true - default: false - enter_fillers: - allOf: - - $ref: '#/components/schemas/SWML.Calling.FunctionFillers' - description: Filler phrases played when entering this context, keyed by language code. - exit_fillers: - allOf: - - $ref: '#/components/schemas/SWML.Calling.FunctionFillers' - description: Filler phrases played when leaving this context, keyed by language code. - text: - type: string - description: The text to send to the agent. - examples: - - You are now helping the customer with their order. - unevaluatedProperties: - not: {} - SWML.Calling.ContextsUpdate: - type: object - properties: - default: - allOf: - - $ref: '#/components/schemas/SWML.Calling.ContextsObjectUpdate' - description: The default context to use at the beginning of the conversation. Additional context steps can be defined as any other key in the object. - unevaluatedProperties: - $ref: '#/components/schemas/SWML.Calling.ContextsObjectUpdate' - title: contexts SWML.Calling.ConversationMessage: type: object required: @@ -38602,127 +38343,6 @@ components: unevaluatedProperties: not: {} title: MultilingualLanguage - SWML.Calling.MultilingualUpdate: - type: object - properties: - languages: - type: array - items: - $ref: '#/components/schemas/SWML.Calling.MultilingualLanguage' - description: |- - An array of voices, one per language the agent speaks. - At least one entry must supply a `voice`, either an entry with `language` set to - `default` or the first language listed. Without one, multilingual mode does not - start and the agent falls back to a single English voice. - allowed: - type: array - items: - type: string - description: |- - Restricts the agent to this set of language codes. The speech recognition engine still - transcribes whatever it hears, but the agent will not switch into a language outside the - list — it keeps the language it is already speaking. The list also tells the agent, in its - prompt, which languages are in play. Every code must be supported by the ASR engine and - model in use, or multilingual mode does not start. - Omit to let the agent follow the caller into any language the ASR engine detects. - examples: - - - en - - es - - fr - engine: - type: string - description: |- - The ASR (Automatic Speech Recognition) engine used to detect the spoken language. - This is separate from the TTS engine that speaks each voice. - If you leave it unset, `deepgram` is used. - Do not set this alongside `params.openai_asr_engine`, which overrides both this engine and - `model`. When both are present, the `params` value wins. - examples: - - deepgram - model: - type: string - description: The ASR model used to detect the spoken language. The model must support code-switching, or multilingual mode does not start. - examples: - - nova-3 - default: nova-3 - provider: - type: string - description: |- - The ASR provider used to detect the spoken language. - If you leave it unset, the provider already configured for the agent is used, falling back to - `deepgram` when the agent has none. Setting it here also applies it to the recognizer. - examples: - - deepgram - start_language: - type: string - description: |- - The language the agent opens the conversation in, before the caller has said - anything for the ASR engine to detect. - examples: - - en - default: en - min_switch_words: - type: integer - minimum: 1 - description: |- - How many words a caller must say before the agent will switch languages. - A single word is often the same in several languages — a name, `no`, `ok` — so a - one-word turn is an unreliable signal. Set to `1` to allow single-word switches. - A value below `1` is treated as the default of `2` rather than rejected. - examples: - - 2 - default: 2 - fillers: - anyOf: - - type: array - items: - type: string - - $ref: '#/components/schemas/SWML.Calling.FunctionFillers' - description: |- - Fillers used to break silence between turns. This is the speech filler map, so it is the - counterpart of `languages[].speech_fillers` rather than of `languages[].fillers`, which is - a deprecated spelling of `function_fillers`. - Supply an array to have the fillers translated into whichever language the caller - is speaking, or an object keyed by language code to set them per language verbatim. - An `auto` key inside the object is translated the same way an array is. - examples: - - - umm - - hmm - function_fillers: - anyOf: - - type: array - items: - type: string - - $ref: '#/components/schemas/SWML.Calling.FunctionFillers' - description: |- - Fillers used while a SWAIG function runs. - Supply an array to have the fillers translated into whichever language the caller - is speaking, or an object keyed by language code to set them per language verbatim. - An `auto` key inside the object is translated the same way an array is. - examples: - - - great - - ok - turn_fillers: - anyOf: - - type: array - items: - type: string - - $ref: '#/components/schemas/SWML.Calling.TurnFillers' - description: |- - Short backchannels played while the caller still has the floor and the agent is - deliberately waiting, as when they spell a name or read out a number, to signal it - is still listening. Which waits earn one is set by `params.turn_filler_sources`. - - Supply an object keyed by language code, optionally with a `default` key for - languages you have not listed. These fillers are never translated on the fly, so - the `auto` key does not apply here — resolving them has to be fast enough to play - immediately. An array is accepted and treated as the `default` set. - - An entry that is an absolute path or a `scheme://` URI is played as audio instead of - being spoken, which is a way to use a recorded backchannel. - unevaluatedProperties: - not: {} - title: multilingual SWML.Calling.NullProperty: type: object required: @@ -42806,6 +42426,10 @@ components: unevaluatedProperties: not: {} title: transfer Method + SWMLDocument: + anyOf: + - $ref: '#/components/schemas/SWML.Calling.SWMLObject' + - $ref: '#/components/schemas/SWML.Messaging.SWMLObject' SWMLScriptAddressListResponse: type: object required: diff --git a/specs/signalwire-rest/calling-api/calls/models/requests.tsp b/specs/signalwire-rest/calling-api/calls/models/requests.tsp index 9a810edcd0..ad58d3dfa0 100644 --- a/specs/signalwire-rest/calling-api/calls/models/requests.tsp +++ b/specs/signalwire-rest/calling-api/calls/models/requests.tsp @@ -1,7 +1,8 @@ import "@typespec/http"; import "@typespec/openapi3"; import "@typespec/json-schema"; -import "../../../../swml/calling"; +import "../../../../swml/calling/Methods/ai_sidecar"; +import "../../../../swml/calling/Methods/live_translate"; import "./core.tsp"; using TypeSpec.Http; @@ -427,7 +428,7 @@ model CallCreateParamsBase { @doc("Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted.") @example("https://example.com/destination.swml.json") - to_script?: string | SWMLObject; + to_script?: string | TypeSpec.Record; @doc("Caller ID displayed to the destination. E.164 for PSTN; short caller-id token or SIP URI for SIP/Verto.") @example("+1234567890") @@ -502,7 +503,7 @@ model CallCreateParamsURL is CallCreateParamsBase { @summary("dial (Inline SWML)") model CallCreateParamsSWML is CallCreateParamsBase { @doc("Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call.") - swml: SWMLObject; + swml: TypeSpec.Record; } @summary("update") @@ -530,7 +531,7 @@ model CallUpdateParamsBase { @summary("update (Inline SWML)") model CallUpdateParamsSWML is CallUpdateParamsBase { @doc("Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call.") - swml: SWMLObject; + swml: TypeSpec.Record; } @summary("update (URL)") @@ -1918,7 +1919,7 @@ model CallTransferRequest { params: { @doc("The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline SWML object.") @example("sip:destination@example.com") - dest: string | SWMLObject; + dest: string | TypeSpec.Record; }; } diff --git a/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp b/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp index 68a43c8dd3..877a003e63 100644 --- a/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp +++ b/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp @@ -1,15 +1,9 @@ import "./enums.tsp"; -import "./ai/main.tsp"; - import "../../../types"; - -// Import SWML AI types for reuse import "../../../../swml/calling/Methods/ai/main.tsp"; using TypeSpec.Http; -using SWML.Calling; - model AIAgentPathID { @doc("Unique ID of an AI Agent.") @example("3fa85f64-5717-4562-b3fc-2c963f66afa6") @@ -18,8 +12,85 @@ model AIAgentPathID { } @summary("AI Agent") -@doc("An AI Agent configuration that extends the SWML AI object with additional API-specific properties.") -model AIAgent is AIObject { +@doc(""" + ${SWML.Calling.aiDescription} + + See the [SWML `ai` method reference](/docs/swml/reference/calling/ai) for the complete configuration contract. + """) +model AIAgent { + @doc(""" + ${SWML.Calling.aiGlobalDataDescription} + + See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai). + """) + @example(#{ company_name: "Acme Corp", support_hours: "9am-5pm EST" }) + global_data?: TypeSpec.Record; + + @doc(""" + ${SWML.Calling.aiHintsDescription} + + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai). + """) + @example(#["pizza", "pepperoni"]) + hints?: (string | TypeSpec.Record)[]; + + @doc(""" + ${SWML.Calling.aiLanguagesDescription} + + See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). + """) + languages?: TypeSpec.Record[]; + + @doc(""" + ${SWML.Calling.aiMultilingualDescription} + + See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). + """) + multilingual?: TypeSpec.Record; + + @doc(""" + ${SWML.Calling.aiParamsDescription} + + See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). + """) + params?: TypeSpec.Record; + + @doc(""" + ${SWML.Calling.aiPostPromptDescription} + + See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). + """) + post_prompt?: TypeSpec.Record; + + @doc(""" + ${SWML.Calling.aiPostPromptUrlDescription} + + See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#post_prompt_url-callback). + """) + @example("username:password@https://example.com") + post_prompt_url?: url; + + @doc(""" + ${SWML.Calling.aiPronounceDescription} + + See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). + """) + pronounce?: TypeSpec.Record[]; + + @doc(""" + ${SWML.Calling.aiPromptDescription} + + See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). + """) + prompt: TypeSpec.Record; + + @doc(""" + ${SWML.Calling.aiSwaigDescription} + + See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). + """) + SWAIG?: TypeSpec.Record; + @doc("Unique ID of an AI Agent.") @example("3fa85f64-5717-4562-b3fc-2c963f66afa6") agent_id: uuid; diff --git a/specs/signalwire-rest/fabric-api/call-flows/models/core.tsp b/specs/signalwire-rest/fabric-api/call-flows/models/core.tsp index 7e1ffe6753..5bf8c38ecb 100644 --- a/specs/signalwire-rest/fabric-api/call-flows/models/core.tsp +++ b/specs/signalwire-rest/fabric-api/call-flows/models/core.tsp @@ -1,7 +1,5 @@ import "../../../types"; import "../../_shared/const.tsp"; -import "../../../../swml/calling"; - using TypeSpec.Http; model CallFlowPathID { @@ -28,7 +26,7 @@ model CallFlow { @doc("The calling SWML document this Call Flow executes. Uses [calling SWML methods](/docs/swml/reference/calling).") @example(SWML_CONTENTS_EXAMPLE) - relayml?: SWML.Calling.SWMLObject; + relayml?: TypeSpec.Record; @doc("The current revision of the call flow. Every update must increase this number.") @example(1) diff --git a/specs/signalwire-rest/fabric-api/call-flows/models/requests.tsp b/specs/signalwire-rest/fabric-api/call-flows/models/requests.tsp index eb9a0697df..c7bec94fa5 100644 --- a/specs/signalwire-rest/fabric-api/call-flows/models/requests.tsp +++ b/specs/signalwire-rest/fabric-api/call-flows/models/requests.tsp @@ -1,7 +1,5 @@ import "./core.tsp"; import "../../_shared/const.tsp"; -import "../../../../swml/calling"; - model CallFlowCreateRequest { @doc("The name of the Call Flow") @example("Booking Assistant") @@ -15,7 +13,7 @@ model CallFlowCreateRequest { @doc("The calling SWML document this Call Flow should execute. Uses [calling SWML methods](/docs/swml/reference/calling). Optional but must be paired with `flow_data` — provide both fields together or omit both. When both are omitted, SignalWire creates a starter SWML document.") @example(SWML_CONTENTS_EXAMPLE) - relayml?: SWML.Calling.SWMLObject; + relayml?: TypeSpec.Record; } model CallFlowUpdateRequest { @@ -35,5 +33,5 @@ model CallFlowUpdateRequest { @doc("The calling SWML document this Call Flow should execute. Uses [calling SWML methods](/docs/swml/reference/calling).") @example(SWML_CONTENTS_EXAMPLE) - relayml: SWML.Calling.SWMLObject; + relayml: TypeSpec.Record; } diff --git a/specs/signalwire-rest/fabric-api/call-flows/models/responses.tsp b/specs/signalwire-rest/fabric-api/call-flows/models/responses.tsp index c14d007236..7fbfbbfe8c 100644 --- a/specs/signalwire-rest/fabric-api/call-flows/models/responses.tsp +++ b/specs/signalwire-rest/fabric-api/call-flows/models/responses.tsp @@ -1,8 +1,6 @@ import "./core.tsp"; import "../../_shared/enums.tsp"; import "../../_shared/const.tsp"; -import "../../../../swml/calling"; - model CallFlowResponse { @doc("Unique ID of the Call Flow.") @example("993ed018-9e79-4e50-b97b-984bd5534095") @@ -57,7 +55,7 @@ model CallFlowVersionResponse { @doc("The calling SWML document this version snapshots. Uses [calling SWML methods](/docs/swml/reference/calling).") @example(SWML_CONTENTS_EXAMPLE) - relayml?: SWML.Calling.SWMLObject; + relayml?: TypeSpec.Record; } model CallFlowPaginationResponse { diff --git a/specs/signalwire-rest/fabric-api/call-flows/versions/models/responses.tsp b/specs/signalwire-rest/fabric-api/call-flows/versions/models/responses.tsp index 0aad2cba81..d60ff3ac1f 100644 --- a/specs/signalwire-rest/fabric-api/call-flows/versions/models/responses.tsp +++ b/specs/signalwire-rest/fabric-api/call-flows/versions/models/responses.tsp @@ -1,7 +1,5 @@ import "../../../../types"; import "../../../_shared/const.tsp"; -import "../../../../../swml/calling"; - model CallFlowVersion { @doc("The unique identifier of the version.") @example("3fa85f64-5717-4562-b3fc-2c963f66afa6") @@ -27,7 +25,7 @@ model CallFlowVersion { @doc("The calling SWML document this version snapshots. Uses [calling SWML methods](/docs/swml/reference/calling).") @example(SWML_CONTENTS_EXAMPLE) - relayml?: SWML.Calling.SWMLObject; + relayml?: TypeSpec.Record; } model CallFlowVersionListResponse { @@ -62,7 +60,7 @@ model CallFlowVersionDeployResponse { @doc("The calling SWML document deployed by this version. Uses [calling SWML methods](/docs/swml/reference/calling).") @example(SWML_CONTENTS_EXAMPLE) - relayml?: SWML.Calling.SWMLObject; + relayml?: TypeSpec.Record; } model CallFlowVersionsPaginationResponse { diff --git a/specs/signalwire-rest/fabric-api/swml-scripts/models/core.tsp b/specs/signalwire-rest/fabric-api/swml-scripts/models/core.tsp index daf104f46a..9428cfe21a 100644 --- a/specs/signalwire-rest/fabric-api/swml-scripts/models/core.tsp +++ b/specs/signalwire-rest/fabric-api/swml-scripts/models/core.tsp @@ -2,9 +2,6 @@ import "@typespec/openapi"; import "../../../types"; import "../../_shared/const.tsp"; import "../../_shared/enums.tsp"; -import "../../../../swml/calling"; -import "../../../../swml/messaging"; - using TypeSpec.Http; using TypeSpec.OpenAPI; @@ -36,7 +33,7 @@ model CallingSwmlScript { @doc("The calling SWML document executed when this script runs. Uses [calling SWML methods](/docs/swml/reference/calling).") @example(SWML_CONTENTS_EXAMPLE) - contents: SWML.Calling.SWMLObject; + contents: TypeSpec.Record; @doc("URL that receives status callbacks for messages sent or calls made by this script.") @example("https://website.com/status") @@ -69,7 +66,7 @@ model MessagingSwmlScript { @doc("The messaging SWML document executed when this script runs. Uses [messaging SWML methods](/docs/swml/reference/messaging).") @example(SWML_MESSAGING_CONTENTS_EXAMPLE) - contents: SWML.Messaging.SWMLObject; + contents: TypeSpec.Record; } @summary("SWML Script") diff --git a/specs/signalwire-rest/fabric-api/swml-scripts/models/requests.tsp b/specs/signalwire-rest/fabric-api/swml-scripts/models/requests.tsp index 5e97e219d6..5c543a9847 100644 --- a/specs/signalwire-rest/fabric-api/swml-scripts/models/requests.tsp +++ b/specs/signalwire-rest/fabric-api/swml-scripts/models/requests.tsp @@ -17,7 +17,7 @@ model CallingSwmlScriptCreateRequest { @doc("The calling SWML document. Uses [calling SWML methods](/docs/swml/reference/calling).") @example(SWML_CONTENTS_EXAMPLE) - contents: SWML.Calling.SWMLObject; + contents: TypeSpec.Record; @doc("URL that receives status callbacks for messages sent or calls made by this script.") @example("https://example.com/status") @@ -38,7 +38,7 @@ model MessagingSwmlScriptCreateRequest { @doc("The messaging SWML document. Uses [messaging SWML methods](/docs/swml/reference/messaging).") @example(SWML_MESSAGING_CONTENTS_EXAMPLE) - contents: SWML.Messaging.SWMLObject; + contents: TypeSpec.Record; } @summary("Create SWML Script") @@ -62,7 +62,7 @@ model CallingSwmlScriptUpdateRequest { @doc("The calling SWML document. Uses [calling SWML methods](/docs/swml/reference/calling).") @example(SWML_CONTENTS_EXAMPLE) - contents?: SWML.Calling.SWMLObject; + contents?: TypeSpec.Record; @doc("URL that receives status callbacks for messages sent or calls made by this script.") @example("https://example.com/status") @@ -83,7 +83,7 @@ model MessagingSwmlScriptUpdateRequest { @doc("The messaging SWML document. Uses [messaging SWML methods](/docs/swml/reference/messaging).") @example(SWML_MESSAGING_CONTENTS_EXAMPLE) - contents?: SWML.Messaging.SWMLObject; + contents?: TypeSpec.Record; } @summary("Update SWML Script") diff --git a/specs/signalwire-rest/main.tsp b/specs/signalwire-rest/main.tsp index 4388fc2755..e8a323ad1b 100644 --- a/specs/signalwire-rest/main.tsp +++ b/specs/signalwire-rest/main.tsp @@ -18,6 +18,7 @@ import "./datasphere-api"; import "./pubsub-api"; import "./logs-api"; import "./webhooks"; +import "./swml-document.tsp"; using TypeSpec.Http; using TypeSpec.OpenAPI; diff --git a/specs/signalwire-rest/swml-document.tsp b/specs/signalwire-rest/swml-document.tsp new file mode 100644 index 0000000000..12e03daac8 --- /dev/null +++ b/specs/signalwire-rest/swml-document.tsp @@ -0,0 +1,9 @@ +import "../swml/calling"; +import "../swml/messaging"; + +namespace SignalWireAPI; + +union SWMLDocument { + calling: SWML.Calling.SWMLObject, + messaging: SWML.Messaging.SWMLObject, +} diff --git a/specs/signalwire-rest/webhooks/calling/main.tsp b/specs/signalwire-rest/webhooks/calling/main.tsp index 59b57d0a7b..6912d7b88c 100644 --- a/specs/signalwire-rest/webhooks/calling/main.tsp +++ b/specs/signalwire-rest/webhooks/calling/main.tsp @@ -5,7 +5,6 @@ import "./models/status-callbacks.tsp"; import "./models/inbound-call.tsp"; import "@signalwire/typespec-webhook"; import "../../../_shared/webhook-ack.tsp"; -import "../../../swml/calling"; using TypeSpec.Http; using TypeSpec.OpenAPI; diff --git a/specs/signalwire-rest/webhooks/messaging/main.tsp b/specs/signalwire-rest/webhooks/messaging/main.tsp index 50147a0803..d7bb06e8e5 100644 --- a/specs/signalwire-rest/webhooks/messaging/main.tsp +++ b/specs/signalwire-rest/webhooks/messaging/main.tsp @@ -5,7 +5,6 @@ import "./models/status-callbacks.tsp"; import "./models/inbound-message.tsp"; import "@signalwire/typespec-webhook"; import "../../../_shared/webhook-ack.tsp"; -import "../../../swml/messaging"; using TypeSpec.Http; using TypeSpec.OpenAPI; diff --git a/specs/swml/calling/Methods/ai/main.tsp b/specs/swml/calling/Methods/ai/main.tsp index 21aa0ae7de..77bbcff3ef 100644 --- a/specs/swml/calling/Methods/ai/main.tsp +++ b/specs/swml/calling/Methods/ai/main.tsp @@ -11,68 +11,90 @@ using TypeSpec.JsonSchema; namespace SWML.Calling; +const aiDescription: string = """ + Creates an AI agent that conducts voice conversations using automatic speech recognition (ASR), + large language models (LLMs), and text-to-speech (TTS) synthesis. + The agent processes caller speech in real-time, generates contextually appropriate responses, + and can execute custom functions to interact with external systems through SignalWire AI Gateway (SWAIG). + """; + +const aiGlobalDataDescription: string = """ + A key-value object for storing data that persists throughout the AI session. + Can be set initially in the SWML script or modified during the conversation using the set_global_data action. + The global_data object is accessible everywhere in the AI session: prompts, AI parameters, + and SWML returned from SWAIG functions. Access properties using template strings (e.g. \${global_data.property_name}). + """; + +const aiHintsDescription: string = "Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately."; + +const aiLanguagesDescription: string = """ + An array of JSON objects defining supported languages in the conversation. + Mutually exclusive with `multilingual`: if both are set, `multilingual` is used and + this array is ignored. + """; + +const aiMultilingualDescription: string = """ + Configures a single agent to detect the caller's language and answer in it, switching + as the caller switches. Use this instead of `languages` when one conversation may span + several languages. Mutually exclusive with `languages`: if both are set, `multilingual` + is used and `languages` is ignored. + """; + +const aiParamsDescription: string = "A JSON object containing parameters as key-value pairs."; + +const aiPostPromptDescription: string = "The final set of instructions and configuration settings to send to the agent."; + +const aiPostPromptUrlDescription: string = "The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`."; + +const aiPronounceDescription: string = "An array of JSON objects to clarify the AI's pronunciation of words or expressions."; + +const aiPromptDescription: string = """ + Defines the AI agent's personality, goals, behaviors, and instructions for handling conversations. + The prompt establishes how the agent should interact with callers, what information it should gather, + and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. + """; + +const aiSwaigDescription: string = "An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue."; + @summary("AI Object") model AIObject { - @doc(""" - A key-value object for storing data that persists throughout the AI session. - Can be set initially in the SWML script or modified during the conversation using the set_global_data action. - The global_data object is accessible everywhere in the AI session: prompts, AI parameters, - and SWML returned from SWAIG functions. Access properties using template strings (e.g. \${global_data.property_name}). - """) + @doc(aiGlobalDataDescription) @example(#{ company_name: "Acme Corp", support_hours: "9am-5pm EST" }) global_data?: GlobalData; - @doc("Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately.") + @doc(aiHintsDescription) @example(#["pizza", "pepperoni"]) hints?: (string | Hint)[]; - @doc(""" - An array of JSON objects defining supported languages in the conversation. - Mutually exclusive with `multilingual`: if both are set, `multilingual` is used and - this array is ignored. - """) + @doc(aiLanguagesDescription) languages?: Languages[]; - @doc(""" - Configures a single agent to detect the caller's language and answer in it, switching - as the caller switches. Use this instead of `languages` when one conversation may span - several languages. Mutually exclusive with `languages`: if both are set, `multilingual` - is used and `languages` is ignored. - """) + @doc(aiMultilingualDescription) multilingual?: Multilingual; - @doc("A JSON object containing parameters as key-value pairs.") + @doc(aiParamsDescription) params?: AIParams; - @doc("The final set of instructions and configuration settings to send to the agent.") + @doc(aiPostPromptDescription) post_prompt?: AIPostPrompt; - @doc("The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`.") + @doc(aiPostPromptUrlDescription) @example("username:password@https://example.com") post_prompt_url?: url; - @doc("An array of JSON objects to clarify the AI's pronunciation of words or expressions.") + @doc(aiPronounceDescription) pronounce?: Pronounce[]; - @doc(""" - Defines the AI agent's personality, goals, behaviors, and instructions for handling conversations. - The prompt establishes how the agent should interact with callers, what information it should gather, - and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. - """) + @doc(aiPromptDescription) prompt: AIPrompt; - @doc("An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue.") + @doc(aiSwaigDescription) SWAIG?: SWAIG; } @summary("ai Method") model AI { - @doc(""" - Creates an AI agent that conducts voice conversations using automatic speech recognition (ASR), - large language models (LLMs), and text-to-speech (TTS) synthesis. - The agent processes caller speech in real-time, generates contextually appropriate responses, - and can execute custom functions to interact with external systems through SignalWire AI Gateway (SWAIG). - """) + @doc(aiDescription) @summary("ai") ai: AIObject; } From f3076f45f7929d9a7bbe48a1126f37e1b4bd0416 Mon Sep 17 00:00:00 2001 From: Devon-White Date: Thu, 20 Aug 2026 12:42:50 -0400 Subject: [PATCH 2/8] docs(api): add schema-validated SWML examples --- fern/apis/signalwire-rest/openapi.yaml | 124 ++++++++++++++++++ .../calling-api/calls/models/requests.tsp | 11 ++ .../fabric-api/ai-agent/models/core.tsp | 15 +++ specs/signalwire-rest/swml-document.tsp | 16 +++ 4 files changed, 166 insertions(+) diff --git a/fern/apis/signalwire-rest/openapi.yaml b/fern/apis/signalwire-rest/openapi.yaml index a66fa71254..fd2680bc71 100644 --- a/fern/apis/signalwire-rest/openapi.yaml +++ b/fern/apis/signalwire-rest/openapi.yaml @@ -15321,6 +15321,10 @@ components: this array is ignored. See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). + examples: + - - name: English + code: en-US + voice: rime.spore multilingual: type: object unevaluatedProperties: {} @@ -15331,6 +15335,15 @@ components: is used and `languages` is ignored. See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). + examples: + - languages: + - language: en + voice: rime.spore + - language: es + voice: elevenlabs.rachel:eleven_flash_v2_5 + allowed: + - en + - es params: type: object unevaluatedProperties: {} @@ -15338,6 +15351,9 @@ components: A JSON object containing parameters as key-value pairs. See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). + examples: + - ai_model: gpt-4o-mini + wait_for_user: true post_prompt: type: object unevaluatedProperties: {} @@ -15345,6 +15361,8 @@ components: The final set of instructions and configuration settings to send to the agent. See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). + examples: + - text: Summarize the conversation and provide any follow-up action items. post_prompt_url: type: string format: uri @@ -15363,6 +15381,10 @@ components: An array of JSON objects to clarify the AI's pronunciation of words or expressions. See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). + examples: + - - replace: SWML + with: swim-el + ignore_case: true prompt: type: object unevaluatedProperties: {} @@ -15372,6 +15394,8 @@ components: and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). + examples: + - text: You are a helpful customer support assistant. SWAIG: type: object unevaluatedProperties: {} @@ -15379,6 +15403,9 @@ components: An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). + examples: + - native_functions: + - check_time agent_id: allOf: - $ref: '#/components/schemas/uuid' @@ -15462,6 +15489,10 @@ components: this array is ignored. See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). + examples: + - - name: English + code: en-US + voice: rime.spore multilingual: type: object unevaluatedProperties: {} @@ -15472,6 +15503,15 @@ components: is used and `languages` is ignored. See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). + examples: + - languages: + - language: en + voice: rime.spore + - language: es + voice: elevenlabs.rachel:eleven_flash_v2_5 + allowed: + - en + - es params: type: object unevaluatedProperties: {} @@ -15479,6 +15519,9 @@ components: A JSON object containing parameters as key-value pairs. See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). + examples: + - ai_model: gpt-4o-mini + wait_for_user: true post_prompt: type: object unevaluatedProperties: {} @@ -15486,6 +15529,8 @@ components: The final set of instructions and configuration settings to send to the agent. See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). + examples: + - text: Summarize the conversation and provide any follow-up action items. post_prompt_url: type: string format: uri @@ -15504,6 +15549,10 @@ components: An array of JSON objects to clarify the AI's pronunciation of words or expressions. See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). + examples: + - - replace: SWML + with: swim-el + ignore_case: true prompt: type: object unevaluatedProperties: {} @@ -15513,6 +15562,8 @@ components: and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). + examples: + - text: You are a helpful customer support assistant. SWAIG: type: object unevaluatedProperties: {} @@ -15520,6 +15571,9 @@ components: An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). + examples: + - native_functions: + - check_time agent_id: allOf: - $ref: '#/components/schemas/uuid' @@ -15697,6 +15751,10 @@ components: this array is ignored. See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). + examples: + - - name: English + code: en-US + voice: rime.spore multilingual: type: object unevaluatedProperties: {} @@ -15707,6 +15765,15 @@ components: is used and `languages` is ignored. See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). + examples: + - languages: + - language: en + voice: rime.spore + - language: es + voice: elevenlabs.rachel:eleven_flash_v2_5 + allowed: + - en + - es params: type: object unevaluatedProperties: {} @@ -15714,6 +15781,9 @@ components: A JSON object containing parameters as key-value pairs. See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). + examples: + - ai_model: gpt-4o-mini + wait_for_user: true post_prompt: type: object unevaluatedProperties: {} @@ -15721,6 +15791,8 @@ components: The final set of instructions and configuration settings to send to the agent. See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). + examples: + - text: Summarize the conversation and provide any follow-up action items. post_prompt_url: type: string format: uri @@ -15739,6 +15811,10 @@ components: An array of JSON objects to clarify the AI's pronunciation of words or expressions. See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). + examples: + - - replace: SWML + with: swim-el + ignore_case: true prompt: type: object unevaluatedProperties: {} @@ -15748,6 +15824,8 @@ components: and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). + examples: + - text: You are a helpful customer support assistant. SWAIG: type: object unevaluatedProperties: {} @@ -15755,6 +15833,9 @@ components: An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). + examples: + - native_functions: + - check_time agent_id: allOf: - $ref: '#/components/schemas/uuid' @@ -18167,6 +18248,11 @@ components: unevaluatedProperties: {} description: Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. examples: + - version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 - https://example.com/destination.swml.json caller_id: type: string @@ -18299,6 +18385,11 @@ components: unevaluatedProperties: {} description: Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. examples: + - version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 - https://example.com/destination.swml.json caller_id: type: string @@ -18400,6 +18491,12 @@ components: type: object unevaluatedProperties: {} description: Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call. + examples: + - version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 unevaluatedProperties: not: {} title: dial (Inline SWML) @@ -18436,6 +18533,11 @@ components: unevaluatedProperties: {} description: Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. examples: + - version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 - https://example.com/destination.swml.json caller_id: type: string @@ -20050,6 +20152,11 @@ components: unevaluatedProperties: {} description: The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline SWML object. examples: + - version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 - sip:destination@example.com required: - dest @@ -20196,6 +20303,12 @@ components: type: object unevaluatedProperties: {} description: Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call. + examples: + - version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 unevaluatedProperties: not: {} title: update (Inline SWML) @@ -39882,6 +39995,12 @@ components: `sections.main`. See the [Calling SWML reference](/docs/swml/reference/calling) for the full list of available methods. title: Calling SWML Document + examples: + - version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 SWML.Calling.SayAction: type: object required: @@ -42301,6 +42420,11 @@ components: See the [Messaging SWML reference](/docs/swml/reference/messaging) for the full list of available methods. title: Messaging SWML Document + examples: + - version: 1.0.0 + sections: + main: + - reply: Thanks for your message! SWML.Messaging.Section: type: object required: diff --git a/specs/signalwire-rest/calling-api/calls/models/requests.tsp b/specs/signalwire-rest/calling-api/calls/models/requests.tsp index ad58d3dfa0..b17ca0e279 100644 --- a/specs/signalwire-rest/calling-api/calls/models/requests.tsp +++ b/specs/signalwire-rest/calling-api/calls/models/requests.tsp @@ -15,6 +15,13 @@ using SWML.Calling; const CallSWMLExample = "{'version': '1.0.0', 'sections': { 'main': [{ 'answer': { 'max_duration': 60 }},{ 'play': { 'urls': ['silence:2', 'say:Hello from SignalWire!']}}]}}"; +const CallSWMLDocumentExample = #{ + version: "1.0.0", + sections: #{ + main: #[#{ play: #{ url: "https://cdn.signalwire.com/swml/audio.mp3" } }], + }, +}; + const CallFallbackURLExample = "https://example.com/fallback"; const CallSWMLURLExample = "https://example.com/swml"; @@ -428,6 +435,7 @@ model CallCreateParamsBase { @doc("Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted.") @example("https://example.com/destination.swml.json") + @example(CallSWMLDocumentExample) to_script?: string | TypeSpec.Record; @doc("Caller ID displayed to the destination. E.164 for PSTN; short caller-id token or SIP URI for SIP/Verto.") @@ -503,6 +511,7 @@ model CallCreateParamsURL is CallCreateParamsBase { @summary("dial (Inline SWML)") model CallCreateParamsSWML is CallCreateParamsBase { @doc("Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call.") + @example(CallSWMLDocumentExample) swml: TypeSpec.Record; } @@ -531,6 +540,7 @@ model CallUpdateParamsBase { @summary("update (Inline SWML)") model CallUpdateParamsSWML is CallUpdateParamsBase { @doc("Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call.") + @example(CallSWMLDocumentExample) swml: TypeSpec.Record; } @@ -1919,6 +1929,7 @@ model CallTransferRequest { params: { @doc("The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline SWML object.") @example("sip:destination@example.com") + @example(CallSWMLDocumentExample) dest: string | TypeSpec.Record; }; } diff --git a/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp b/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp index 877a003e63..f18f0029c2 100644 --- a/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp +++ b/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp @@ -39,6 +39,7 @@ model AIAgent { See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). """) + @example(#[#{ name: "English", code: "en-US", voice: "rime.spore" }]) languages?: TypeSpec.Record[]; @doc(""" @@ -46,6 +47,13 @@ model AIAgent { See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). """) + @example(#{ + languages: #[ + #{ language: "en", voice: "rime.spore" }, + #{ language: "es", voice: "elevenlabs.rachel:eleven_flash_v2_5" } + ], + allowed: #["en", "es"], + }) multilingual?: TypeSpec.Record; @doc(""" @@ -53,6 +61,7 @@ model AIAgent { See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). """) + @example(#{ ai_model: "gpt-4o-mini", wait_for_user: true }) params?: TypeSpec.Record; @doc(""" @@ -60,6 +69,9 @@ model AIAgent { See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). """) + @example(#{ + text: "Summarize the conversation and provide any follow-up action items.", + }) post_prompt?: TypeSpec.Record; @doc(""" @@ -75,6 +87,7 @@ model AIAgent { See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). """) + @example(#[#{ replace: "SWML", with: "swim-el", ignore_case: true }]) pronounce?: TypeSpec.Record[]; @doc(""" @@ -82,6 +95,7 @@ model AIAgent { See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). """) + @example(#{ text: "You are a helpful customer support assistant." }) prompt: TypeSpec.Record; @doc(""" @@ -89,6 +103,7 @@ model AIAgent { See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). """) + @example(#{ native_functions: #["check_time"] }) SWAIG?: TypeSpec.Record; @doc("Unique ID of an AI Agent.") diff --git a/specs/signalwire-rest/swml-document.tsp b/specs/signalwire-rest/swml-document.tsp index 12e03daac8..730a4a413f 100644 --- a/specs/signalwire-rest/swml-document.tsp +++ b/specs/signalwire-rest/swml-document.tsp @@ -3,6 +3,22 @@ import "../swml/messaging"; namespace SignalWireAPI; +@@example(SWML.Calling.SWMLObject, + #{ + version: "1.0.0", + sections: #{ + main: #[#{ play: #{ url: "https://cdn.signalwire.com/swml/audio.mp3" } }], + }, + } +); + +@@example(SWML.Messaging.SWMLObject, + #{ + version: "1.0.0", + sections: #{ main: #[#{ reply: "Thanks for your message!" }] }, + } +); + union SWMLDocument { calling: SWML.Calling.SWMLObject, messaging: SWML.Messaging.SWMLObject, From 9ac08b611d7fea2db77863f5054563a5387362c1 Mon Sep 17 00:00:00 2001 From: Devon-White Date: Thu, 20 Aug 2026 13:07:09 -0400 Subject: [PATCH 3/8] docs(api): add manual SWML script operation example --- fern/apis/signalwire-rest/openapi.yaml | 35 +++++++++++++++++++ .../fabric-api/swml-scripts/main.tsp | 35 +++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/fern/apis/signalwire-rest/openapi.yaml b/fern/apis/signalwire-rest/openapi.yaml index fd2680bc71..f32fc34629 100644 --- a/fern/apis/signalwire-rest/openapi.yaml +++ b/fern/apis/signalwire-rest/openapi.yaml @@ -5169,6 +5169,28 @@ paths: application/json: schema: $ref: '#/components/schemas/SwmlScriptResponse' + examples: + Simple calling script: + summary: Simple calling script + description: Create a Calling SWML Script that plays a single audio file. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Welcome Script + type: swml_script + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:20:00Z' + swml_script: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + display_name: Welcome Script + script_type: calling + request_url: https://example.signalwire.com/api/fabric/resources/swml_scripts/993ed018-9e79-4e50-b97b-984bd5534095 + contents: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 '401': description: Access is unauthorized. content: @@ -5201,6 +5223,19 @@ paths: application/json: schema: $ref: '#/components/schemas/SwmlScriptCreateRequest' + examples: + Simple calling script: + summary: Simple calling script + description: Create a Calling SWML Script that plays a single audio file. + value: + name: Welcome Script + script_type: calling + contents: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 /api/fabric/resources/swml_scripts/{id}: get: operationId: get_swml_script diff --git a/specs/signalwire-rest/fabric-api/swml-scripts/main.tsp b/specs/signalwire-rest/fabric-api/swml-scripts/main.tsp index d6f09de1e5..00d3ec5520 100644 --- a/specs/signalwire-rest/fabric-api/swml-scripts/main.tsp +++ b/specs/signalwire-rest/fabric-api/swml-scripts/main.tsp @@ -13,6 +13,34 @@ using TypeSpec.Http; using TypeSpec.OpenAPI; using Types.StatusCodes; +const CreateCallingSwmlScriptExample = #{ + parameters: #{ + request: #{ + name: "Welcome Script", + script_type: "calling", + contents: SWML_CONTENTS_EXAMPLE, + } + }, + returnType: #{ + statusCode: 200, + swml_script: #{ + id: "993ed018-9e79-4e50-b97b-984bd5534095", + project_id: "1313fe58-5e14-4c11-bbe7-6fdfa11fe780", + display_name: "Welcome Script", + type: FabricResponseType.SwmlScript, + created_at: utcDateTime.fromISO("2024-05-06T12:20:00Z"), + updated_at: utcDateTime.fromISO("2024-05-06T12:20:00Z"), + swml_script: #{ + id: "993ed018-9e79-4e50-b97b-984bd5534095", + display_name: "Welcome Script", + script_type: "calling", + request_url: "https://example.signalwire.com/api/fabric/resources/swml_scripts/993ed018-9e79-4e50-b97b-984bd5534095", + contents: SWML_CONTENTS_EXAMPLE, + }, + } + }, +}; + @route("/resources/swml_scripts") namespace SignalWireAPI.Fabric.SwmlScripts { @tag(SWML_SCRIPTS_TAG) @@ -54,6 +82,13 @@ namespace SignalWireAPI.Fabric.SwmlScripts { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + CreateCallingSwmlScriptExample, + #{ + title: "Simple calling script", + description: "Create a Calling SWML Script that plays a single audio file.", + } + ) @post create(@body request: SwmlScriptCreateRequest): | { From 1fc336f256056b9783a71a60cbc426769ed0e613 Mon Sep 17 00:00:00 2001 From: Devon-White Date: Thu, 20 Aug 2026 13:34:47 -0400 Subject: [PATCH 4/8] docs: add compact AI and SWML operation examples --- fern/apis/signalwire-rest/openapi.yaml | 567 +++++++++++++++++- .../calling-api/calls/main.tsp | 28 + .../calling-api/calls/models/examples.tsp | 37 ++ .../fabric-api/_shared/examples.tsp | 126 ++++ .../fabric-api/ai-agent/main.tsp | 42 ++ .../fabric-api/call-flows/main.tsp | 51 ++ .../fabric-api/call-flows/versions/main.tsp | 40 ++ .../fabric-api/resources/main.tsp | 42 ++ .../fabric-api/swml-scripts/main.tsp | 109 +++- 9 files changed, 1027 insertions(+), 15 deletions(-) create mode 100644 specs/signalwire-rest/fabric-api/_shared/examples.tsp diff --git a/fern/apis/signalwire-rest/openapi.yaml b/fern/apis/signalwire-rest/openapi.yaml index f32fc34629..16679839d0 100644 --- a/fern/apis/signalwire-rest/openapi.yaml +++ b/fern/apis/signalwire-rest/openapi.yaml @@ -601,6 +601,47 @@ paths: schema: $ref: '#/components/schemas/Calling.CallRequest' examples: + calling.transfer with inline SWML: + summary: calling.transfer with inline SWML + description: Transfer an active call to a compact inline SWML document. + value: + command: calling.transfer + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + params: + dest: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 + dial with a destination script: + summary: dial with a destination script + description: Initiate a call whose destination executes a compact inline SWML document. + value: + command: dial + params: + from: '+15551234567' + to_script: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 + url: https://example.com/origin.swml.json + dial with inline SWML: + summary: dial with inline SWML + description: Initiate an outbound call using a compact inline SWML document. + value: + command: dial + params: + from: '+15551234567' + to: '+15557654321' + swml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 dial: summary: dial description: Initiate a new outbound call with the dial command @@ -622,6 +663,19 @@ paths: - PCMA timeout: 30 max_price_per_minute: 0.05 + update with inline SWML: + summary: update with inline SWML + description: Redirect an active call to a compact inline SWML document. + value: + command: update + params: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + swml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 update: summary: update description: Modify an existing call's parameters in real-time @@ -1736,6 +1790,26 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceListResponse' + examples: + Resource list: + summary: Resource list + description: A page containing one compact AI Agent resource. + value: + data: + - id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Support Assistant + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + type: ai_agent + ai_agent: + prompt: + text: You are a helpful customer support assistant. + agent_id: a87db7ed-8ebe-42e4-829f-8ba5a4152f54 + name: Support Assistant + links: + self: https://example.signalwire.com/api/fabric/resources?page_number=0&page_size=50 + first: https://example.signalwire.com/api/fabric/resources?page_number=0&page_size=50 '401': description: Access is unauthorized. content: @@ -1776,6 +1850,26 @@ paths: application/json: schema: $ref: '#/components/schemas/AIAgentListResponse' + examples: + AI agent list: + summary: AI agent list + description: A page containing one AI agent. + value: + data: + - id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Support Assistant + type: ai_agent + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + ai_agent: + prompt: + text: You are a helpful customer support assistant. + agent_id: a87db7ed-8ebe-42e4-829f-8ba5a4152f54 + name: Support Assistant + links: + self: https://example.signalwire.com/api/fabric/resources/ai_agents?page_number=0&page_size=50 + first: https://example.signalwire.com/api/fabric/resources/ai_agents?page_number=0&page_size=50 '401': description: Access is unauthorized. content: @@ -1815,6 +1909,22 @@ paths: application/json: schema: $ref: '#/components/schemas/AIAgentResponse' + examples: + Customer support agent: + summary: Customer support agent + description: Create an AI agent with a concise text prompt. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Support Assistant + type: ai_agent + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + ai_agent: + prompt: + text: You are a helpful customer support assistant. + agent_id: a87db7ed-8ebe-42e4-829f-8ba5a4152f54 + name: Support Assistant '401': description: Access is unauthorized. content: @@ -1847,6 +1957,15 @@ paths: application/json: schema: $ref: '#/components/schemas/AIAgentCreateRequest' + examples: + Customer support agent: + summary: Customer support agent + description: Create an AI agent with a concise text prompt. + value: + prompt: + text: You are a helpful customer support assistant. + agent_id: a87db7ed-8ebe-42e4-829f-8ba5a4152f54 + name: Support Assistant /api/fabric/resources/ai_agents/{ai_agent_id}/addresses: get: operationId: list_ai_agent_addresses @@ -1909,6 +2028,22 @@ paths: application/json: schema: $ref: '#/components/schemas/AIAgentResponse' + examples: + AI agent: + summary: AI agent + description: A customer support AI agent. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Support Assistant + type: ai_agent + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + ai_agent: + prompt: + text: You are a helpful customer support assistant. + agent_id: a87db7ed-8ebe-42e4-829f-8ba5a4152f54 + name: Support Assistant '401': description: Access is unauthorized. content: @@ -1949,6 +2084,22 @@ paths: application/json: schema: $ref: '#/components/schemas/AIAgentResponse' + examples: + Update the agent prompt: + summary: Update the agent prompt + description: Replace an AI agent's prompt while leaving its other settings unchanged. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Support Assistant + type: ai_agent + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + ai_agent: + prompt: + text: You are a helpful customer support assistant. + agent_id: a87db7ed-8ebe-42e4-829f-8ba5a4152f54 + name: Support Assistant '401': description: Access is unauthorized. content: @@ -1981,6 +2132,15 @@ paths: application/json: schema: $ref: '#/components/schemas/AIAgentUpdateRequest' + examples: + Update the agent prompt: + summary: Update the agent prompt + description: Replace an AI agent's prompt while leaving its other settings unchanged. + value: + prompt: + text: You are a concise customer support assistant. + agent_id: a87db7ed-8ebe-42e4-829f-8ba5a4152f54 + name: Support Assistant delete: operationId: delete_ai_agent summary: Delete AI agent @@ -2079,6 +2239,27 @@ paths: application/json: schema: $ref: '#/components/schemas/CallFlowVersionListResponse' + examples: + Call Flow version list: + summary: Call Flow version list + description: A page containing one compact Call Flow version. + value: + data: + - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + version: 1.0.0 + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + flow_data: {} + relayml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 + links: + self: https://example.signalwire.com/api/fabric/resources/call_flow/993ed018-9e79-4e50-b97b-984bd5534095/versions?page_number=0&page_size=50 + first: https://example.signalwire.com/api/fabric/resources/call_flow/993ed018-9e79-4e50-b97b-984bd5534095/versions?page_number=0&page_size=50 + next: https://example.signalwire.com/api/fabric/resources/call_flow/993ed018-9e79-4e50-b97b-984bd5534095/versions?page_number=1&page_size=50 '401': description: Access is unauthorized. content: @@ -2119,6 +2300,22 @@ paths: application/json: schema: $ref: '#/components/schemas/CallFlowVersionDeployResponse' + examples: + Deploy by document version: + summary: Deploy by document version + description: Deploy version 2 of a Call Flow. + value: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + document_version: 2 + flow_data: {} + relayml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 '401': description: Access is unauthorized. content: @@ -2151,6 +2348,12 @@ paths: application/json: schema: $ref: '#/components/schemas/CallFlowVersionDeployRequest' + examples: + Deploy by document version: + summary: Deploy by document version + description: Deploy version 2 of a Call Flow. + value: + document_version: 2 /api/fabric/resources/call_flows: get: operationId: list_call_flows @@ -2171,6 +2374,32 @@ paths: application/json: schema: $ref: '#/components/schemas/CallFlowListResponse' + examples: + Call flow list: + summary: Call flow list + description: A page containing one Call Flow. + value: + links: + self: https://example.signalwire.com/api/fabric/resources/call_flows?page_number=0&page_size=50 + first: https://example.signalwire.com/api/fabric/resources/call_flows?page_number=0&page_size=50 + data: + - id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Welcome Call Flow + type: call_flow + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + call_flow: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + title: Welcome Call Flow + flow_data: {} + relayml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 + document_version: 1 '401': description: Access is unauthorized. content: @@ -2210,6 +2439,28 @@ paths: application/json: schema: $ref: '#/components/schemas/CallFlowResponse' + examples: + Welcome Call Flow: + summary: Welcome Call Flow + description: Create a Call Flow that plays a single audio file. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Welcome Call Flow + type: call_flow + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + call_flow: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + title: Welcome Call Flow + flow_data: {} + relayml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 + document_version: 1 '401': description: Access is unauthorized. content: @@ -2242,6 +2493,19 @@ paths: application/json: schema: $ref: '#/components/schemas/CallFlowCreateRequest' + examples: + Welcome Call Flow: + summary: Welcome Call Flow + description: Create a Call Flow that plays a single audio file. + value: + title: Welcome Call Flow + flow_data: {} + relayml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 /api/fabric/resources/call_flows/{id}: get: operationId: get_call_flow @@ -2263,6 +2527,28 @@ paths: application/json: schema: $ref: '#/components/schemas/CallFlowResponse' + examples: + Call flow: + summary: Call flow + description: A Call Flow with a compact SWML document. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Welcome Call Flow + type: call_flow + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + call_flow: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + title: Welcome Call Flow + flow_data: {} + relayml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 + document_version: 1 '401': description: Access is unauthorized. content: @@ -2303,6 +2589,28 @@ paths: application/json: schema: $ref: '#/components/schemas/CallFlowResponse' + examples: + Update a Call Flow: + summary: Update a Call Flow + description: Update a Call Flow with its next document revision. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Welcome Call Flow + type: call_flow + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + call_flow: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + title: Welcome Call Flow + flow_data: {} + relayml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 + document_version: 1 '401': description: Access is unauthorized. content: @@ -2335,6 +2643,20 @@ paths: application/json: schema: $ref: '#/components/schemas/CallFlowUpdateRequest' + examples: + Update a Call Flow: + summary: Update a Call Flow + description: Update a Call Flow with its next document revision. + value: + title: Updated Welcome Call Flow + document_version: 2 + flow_data: {} + relayml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 delete: operationId: delete_call_flow summary: Delete call flow @@ -5130,6 +5452,32 @@ paths: type: array items: $ref: '#/components/schemas/SwmlScriptListResponse' + examples: + SWML Script list: + summary: SWML Script list + description: A page containing one compact Calling script. + value: + - data: + - id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Welcome Script + type: swml_script + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + swml_script: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + display_name: Welcome Script + script_type: calling + request_url: https://example.signalwire.com/api/fabric/resources/swml_scripts/993ed018-9e79-4e50-b97b-984bd5534095 + contents: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 + links: + self: https://example.signalwire.com/api/fabric/resources/swml_scripts?page_number=0&page_size=50 + first: https://example.signalwire.com/api/fabric/resources/swml_scripts?page_number=0&page_size=50 '401': description: Access is unauthorized. content: @@ -5170,6 +5518,26 @@ paths: schema: $ref: '#/components/schemas/SwmlScriptResponse' examples: + Simple messaging script: + summary: Simple messaging script + description: Create a Messaging SWML Script that sends a single reply. + value: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Reply Bot + type: swml_script + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + swml_script: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + display_name: Reply Bot + script_type: messaging + request_url: https://example.signalwire.com/api/fabric/resources/swml_scripts/3fa85f64-5717-4562-b3fc-2c963f66afa6 + contents: + version: 1.0.0 + sections: + main: + - reply: Thanks for your message! Simple calling script: summary: Simple calling script description: Create a Calling SWML Script that plays a single audio file. @@ -5179,7 +5547,7 @@ paths: display_name: Welcome Script type: swml_script created_at: '2024-05-06T12:20:00Z' - updated_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' swml_script: id: 993ed018-9e79-4e50-b97b-984bd5534095 display_name: Welcome Script @@ -5224,6 +5592,17 @@ paths: schema: $ref: '#/components/schemas/SwmlScriptCreateRequest' examples: + Simple messaging script: + summary: Simple messaging script + description: Create a Messaging SWML Script that sends a single reply. + value: + name: Reply Bot + script_type: messaging + contents: + version: 1.0.0 + sections: + main: + - reply: Thanks for your message! Simple calling script: summary: Simple calling script description: Create a Calling SWML Script that plays a single audio file. @@ -5257,6 +5636,48 @@ paths: application/json: schema: $ref: '#/components/schemas/SwmlScriptResponse' + examples: + Messaging script: + summary: Messaging script + description: A Messaging script that sends one reply. + value: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Reply Bot + type: swml_script + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + swml_script: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + display_name: Reply Bot + script_type: messaging + request_url: https://example.signalwire.com/api/fabric/resources/swml_scripts/3fa85f64-5717-4562-b3fc-2c963f66afa6 + contents: + version: 1.0.0 + sections: + main: + - reply: Thanks for your message! + Calling script: + summary: Calling script + description: A Calling script that plays one audio file. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Welcome Script + type: swml_script + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + swml_script: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + display_name: Welcome Script + script_type: calling + request_url: https://example.signalwire.com/api/fabric/resources/swml_scripts/993ed018-9e79-4e50-b97b-984bd5534095 + contents: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 '401': description: Access is unauthorized. content: @@ -5297,6 +5718,48 @@ paths: application/json: schema: $ref: '#/components/schemas/SwmlScriptResponse' + examples: + Update a messaging script: + summary: Update a messaging script + description: Update a Messaging script with a compact SWML document. + value: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Reply Bot + type: swml_script + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + swml_script: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + display_name: Reply Bot + script_type: messaging + request_url: https://example.signalwire.com/api/fabric/resources/swml_scripts/3fa85f64-5717-4562-b3fc-2c963f66afa6 + contents: + version: 1.0.0 + sections: + main: + - reply: Thanks for your message! + Update a calling script: + summary: Update a calling script + description: Update a Calling script with a compact SWML document. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Welcome Script + type: swml_script + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + swml_script: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + display_name: Welcome Script + script_type: calling + request_url: https://example.signalwire.com/api/fabric/resources/swml_scripts/993ed018-9e79-4e50-b97b-984bd5534095 + contents: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 '401': description: Access is unauthorized. content: @@ -5329,6 +5792,30 @@ paths: application/json: schema: $ref: '#/components/schemas/SwmlScriptUpdateRequest' + examples: + Update a messaging script: + summary: Update a messaging script + description: Update a Messaging script with a compact SWML document. + value: + display_name: Updated Reply Bot + script_type: messaging + contents: + version: 1.0.0 + sections: + main: + - reply: Thanks for your message! + Update a calling script: + summary: Update a calling script + description: Update a Calling script with a compact SWML document. + value: + display_name: Updated Welcome Script + script_type: calling + contents: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 delete: operationId: delete_swml_script summary: Delete SWML Script @@ -5688,6 +6175,84 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceResponse' + examples: + Messaging script: + summary: Messaging script + description: A compact Messaging SWML Script resource. + value: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Reply Bot + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + type: swml_script + swml_script: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + display_name: Reply Bot + script_type: messaging + request_url: https://example.signalwire.com/api/fabric/resources/swml_scripts/3fa85f64-5717-4562-b3fc-2c963f66afa6 + contents: + version: 1.0.0 + sections: + main: + - reply: Thanks for your message! + Calling script: + summary: Calling script + description: A compact Calling SWML Script resource. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Welcome Script + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + type: swml_script + swml_script: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + display_name: Welcome Script + script_type: calling + request_url: https://example.signalwire.com/api/fabric/resources/swml_scripts/993ed018-9e79-4e50-b97b-984bd5534095 + contents: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 + Call Flow: + summary: Call Flow + description: A Call Flow with compact SWML content. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Welcome Call Flow + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + type: call_flow + call_flow: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + title: Welcome Call Flow + flow_data: {} + relayml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 + document_version: 1 + AI Agent: + summary: AI Agent + description: An AI Agent Fabric resource. + value: + id: 993ed018-9e79-4e50-b97b-984bd5534095 + project_id: 1313fe58-5e14-4c11-bbe7-6fdfa11fe780 + display_name: Support Assistant + created_at: '2024-05-06T12:20:00Z' + updated_at: '2024-05-06T12:25:00Z' + type: ai_agent + ai_agent: + prompt: + text: You are a helpful customer support assistant. + agent_id: a87db7ed-8ebe-42e4-829f-8ba5a4152f54 + name: Support Assistant '401': description: Access is unauthorized. content: diff --git a/specs/signalwire-rest/calling-api/calls/main.tsp b/specs/signalwire-rest/calling-api/calls/main.tsp index d149bd5ceb..f6515b86a6 100644 --- a/specs/signalwire-rest/calling-api/calls/main.tsp +++ b/specs/signalwire-rest/calling-api/calls/main.tsp @@ -352,6 +352,13 @@ namespace SignalWireAPI.Calling.Calls { description: "Modify an existing call's parameters in real-time", } ) + @opExample( + #{ parameters: updateInlineSwmlCallExample }, + #{ + title: "update with inline SWML", + description: "Redirect an active call to a compact inline SWML document.", + } + ) @opExample( #{ parameters: dialCallExample }, #{ @@ -359,6 +366,27 @@ namespace SignalWireAPI.Calling.Calls { description: "Initiate a new outbound call with the dial command", } ) + @opExample( + #{ parameters: dialInlineSwmlCallExample }, + #{ + title: "dial with inline SWML", + description: "Initiate an outbound call using a compact inline SWML document.", + } + ) + @opExample( + #{ parameters: dialToScriptCallExample }, + #{ + title: "dial with a destination script", + description: "Initiate a call whose destination executes a compact inline SWML document.", + } + ) + @opExample( + #{ parameters: transferInlineSwmlCallExample }, + #{ + title: "calling.transfer with inline SWML", + description: "Transfer an active call to a compact inline SWML document.", + } + ) @post @operationId("call-commands") callCommand(@body request: CallRequest): diff --git a/specs/signalwire-rest/calling-api/calls/models/examples.tsp b/specs/signalwire-rest/calling-api/calls/models/examples.tsp index 1e867a8d93..a3024a2efc 100644 --- a/specs/signalwire-rest/calling-api/calls/models/examples.tsp +++ b/specs/signalwire-rest/calling-api/calls/models/examples.tsp @@ -29,6 +29,28 @@ const dialCallExample = #{ }, }; +const dialInlineSwmlCallExample = #{ + request: #{ + command: "dial", + params: #{ + from: "+15551234567", + to: "+15557654321", + swml: CallSWMLDocumentExample, + }, + }, +}; + +const dialToScriptCallExample = #{ + request: #{ + command: "dial", + params: #{ + from: "+15551234567", + to_script: CallSWMLDocumentExample, + url: "https://example.com/origin.swml.json", + }, + }, +}; + const updateCallExample = #{ request: #{ command: "update", @@ -40,6 +62,13 @@ const updateCallExample = #{ }, }; +const updateInlineSwmlCallExample = #{ + request: #{ + command: "update", + params: #{ id: callId, swml: CallSWMLDocumentExample }, + }, +}; + const hangupCallExample = #{ request: #{ command: "calling.end", @@ -503,6 +532,14 @@ const transferCallExample = #{ }, }; +const transferInlineSwmlCallExample = #{ + request: #{ + command: "calling.transfer", + id: callId, + params: #{ dest: CallSWMLDocumentExample }, + }, +}; + // User Event example const userEventCallExample = #{ request: #{ diff --git a/specs/signalwire-rest/fabric-api/_shared/examples.tsp b/specs/signalwire-rest/fabric-api/_shared/examples.tsp new file mode 100644 index 0000000000..50f169c745 --- /dev/null +++ b/specs/signalwire-rest/fabric-api/_shared/examples.tsp @@ -0,0 +1,126 @@ +import "./const.tsp"; +import "./enums.tsp"; + +const FABRIC_RESOURCE_ID_EXAMPLE = "993ed018-9e79-4e50-b97b-984bd5534095"; +const FABRIC_PROJECT_ID_EXAMPLE = "1313fe58-5e14-4c11-bbe7-6fdfa11fe780"; +const FABRIC_CREATED_AT_EXAMPLE = utcDateTime.fromISO("2024-05-06T12:20:00Z"); +const FABRIC_UPDATED_AT_EXAMPLE = utcDateTime.fromISO("2024-05-06T12:25:00Z"); + +const AI_AGENT_EXAMPLE = #{ + prompt: #{ text: "You are a helpful customer support assistant." }, + agent_id: "a87db7ed-8ebe-42e4-829f-8ba5a4152f54", + name: "Support Assistant", +}; + +const AI_AGENT_RESPONSE_EXAMPLE = #{ + id: FABRIC_RESOURCE_ID_EXAMPLE, + project_id: FABRIC_PROJECT_ID_EXAMPLE, + display_name: "Support Assistant", + type: FabricResponseType.AiAgent, + created_at: FABRIC_CREATED_AT_EXAMPLE, + updated_at: FABRIC_UPDATED_AT_EXAMPLE, + ai_agent: AI_AGENT_EXAMPLE, +}; + +const CALL_FLOW_EXAMPLE = #{ + id: FABRIC_RESOURCE_ID_EXAMPLE, + title: "Welcome Call Flow", + flow_data: #{}, + relayml: SWML_CONTENTS_EXAMPLE, + document_version: 1, +}; + +const CALL_FLOW_RESPONSE_EXAMPLE = #{ + id: FABRIC_RESOURCE_ID_EXAMPLE, + project_id: FABRIC_PROJECT_ID_EXAMPLE, + display_name: "Welcome Call Flow", + type: FabricResponseType.CallFlow, + created_at: FABRIC_CREATED_AT_EXAMPLE, + updated_at: FABRIC_UPDATED_AT_EXAMPLE, + call_flow: CALL_FLOW_EXAMPLE, +}; + +const CALL_FLOW_VERSION_EXAMPLE = #{ + id: "3fa85f64-5717-4562-b3fc-2c963f66afa6", + version: "1.0.0", + created_at: "2024-05-06T12:20:00Z", + updated_at: "2024-05-06T12:25:00Z", + flow_data: #{}, + relayml: SWML_CONTENTS_EXAMPLE, +}; + +const CALLING_SWML_SCRIPT_EXAMPLE = #{ + id: FABRIC_RESOURCE_ID_EXAMPLE, + display_name: "Welcome Script", + script_type: "calling", + request_url: "https://example.signalwire.com/api/fabric/resources/swml_scripts/993ed018-9e79-4e50-b97b-984bd5534095", + contents: SWML_CONTENTS_EXAMPLE, +}; + +const MESSAGING_SWML_SCRIPT_EXAMPLE = #{ + id: "3fa85f64-5717-4562-b3fc-2c963f66afa6", + display_name: "Reply Bot", + script_type: "messaging", + request_url: "https://example.signalwire.com/api/fabric/resources/swml_scripts/3fa85f64-5717-4562-b3fc-2c963f66afa6", + contents: SWML_MESSAGING_CONTENTS_EXAMPLE, +}; + +const CALLING_SWML_SCRIPT_RESPONSE_EXAMPLE = #{ + id: FABRIC_RESOURCE_ID_EXAMPLE, + project_id: FABRIC_PROJECT_ID_EXAMPLE, + display_name: "Welcome Script", + type: FabricResponseType.SwmlScript, + created_at: FABRIC_CREATED_AT_EXAMPLE, + updated_at: FABRIC_UPDATED_AT_EXAMPLE, + swml_script: CALLING_SWML_SCRIPT_EXAMPLE, +}; + +const MESSAGING_SWML_SCRIPT_RESPONSE_EXAMPLE = #{ + id: "3fa85f64-5717-4562-b3fc-2c963f66afa6", + project_id: FABRIC_PROJECT_ID_EXAMPLE, + display_name: "Reply Bot", + type: FabricResponseType.SwmlScript, + created_at: FABRIC_CREATED_AT_EXAMPLE, + updated_at: FABRIC_UPDATED_AT_EXAMPLE, + swml_script: MESSAGING_SWML_SCRIPT_EXAMPLE, +}; + +const RESOURCE_AI_EXAMPLE = #{ + id: FABRIC_RESOURCE_ID_EXAMPLE, + project_id: FABRIC_PROJECT_ID_EXAMPLE, + display_name: "Support Assistant", + created_at: FABRIC_CREATED_AT_EXAMPLE, + updated_at: FABRIC_UPDATED_AT_EXAMPLE, + type: FabricResponseType.AiAgent, + ai_agent: AI_AGENT_EXAMPLE, +}; + +const RESOURCE_CALL_FLOW_EXAMPLE = #{ + id: FABRIC_RESOURCE_ID_EXAMPLE, + project_id: FABRIC_PROJECT_ID_EXAMPLE, + display_name: "Welcome Call Flow", + created_at: FABRIC_CREATED_AT_EXAMPLE, + updated_at: FABRIC_UPDATED_AT_EXAMPLE, + type: FabricResponseType.CallFlow, + call_flow: CALL_FLOW_EXAMPLE, +}; + +const RESOURCE_CALLING_SWML_SCRIPT_EXAMPLE = #{ + id: FABRIC_RESOURCE_ID_EXAMPLE, + project_id: FABRIC_PROJECT_ID_EXAMPLE, + display_name: "Welcome Script", + created_at: FABRIC_CREATED_AT_EXAMPLE, + updated_at: FABRIC_UPDATED_AT_EXAMPLE, + type: FabricResponseType.SwmlScript, + swml_script: CALLING_SWML_SCRIPT_EXAMPLE, +}; + +const RESOURCE_MESSAGING_SWML_SCRIPT_EXAMPLE = #{ + id: "3fa85f64-5717-4562-b3fc-2c963f66afa6", + project_id: FABRIC_PROJECT_ID_EXAMPLE, + display_name: "Reply Bot", + created_at: FABRIC_CREATED_AT_EXAMPLE, + updated_at: FABRIC_UPDATED_AT_EXAMPLE, + type: FabricResponseType.SwmlScript, + swml_script: MESSAGING_SWML_SCRIPT_EXAMPLE, +}; diff --git a/specs/signalwire-rest/fabric-api/ai-agent/main.tsp b/specs/signalwire-rest/fabric-api/ai-agent/main.tsp index fe4c205708..564815a691 100644 --- a/specs/signalwire-rest/fabric-api/ai-agent/main.tsp +++ b/specs/signalwire-rest/fabric-api/ai-agent/main.tsp @@ -7,6 +7,7 @@ import "./models/errors.tsp"; import "./addresses"; import "../../types"; import "../tags.tsp"; +import "../_shared/examples.tsp"; import "../../../_shared/alias/token-permissions.tsp"; using TypeSpec.Http; @@ -25,6 +26,18 @@ namespace SignalWireAPI.Fabric.AIAgents { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + returnType: #{ + data: #[AI_AGENT_RESPONSE_EXAMPLE], + links: #{ + self: "https://example.signalwire.com/api/fabric/resources/ai_agents?page_number=0&page_size=50", + first: "https://example.signalwire.com/api/fabric/resources/ai_agents?page_number=0&page_size=50", + }, + }, + }, + #{ title: "AI agent list", description: "A page containing one AI agent." } + ) list(): AIAgentListResponse | StatusCode401 | StatusCode404 | StatusCode500; @operationId("get_ai_agent") @@ -34,6 +47,10 @@ namespace SignalWireAPI.Fabric.AIAgents { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ returnType: #{ statusCode: 200, ai_agent: AI_AGENT_RESPONSE_EXAMPLE } }, + #{ title: "AI agent", description: "A customer support AI agent." } + ) read(...AIAgentPathID): | { @statusCode statusCode: 200; @@ -50,6 +67,16 @@ namespace SignalWireAPI.Fabric.AIAgents { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + parameters: AI_AGENT_EXAMPLE, + returnType: #{ statusCode: 201, ai_agent: AI_AGENT_RESPONSE_EXAMPLE }, + }, + #{ + title: "Customer support agent", + description: "Create an AI agent with a concise text prompt.", + } + ) @post create(...AIAgentCreateRequest): | { @@ -68,6 +95,21 @@ namespace SignalWireAPI.Fabric.AIAgents { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + parameters: #{ + id: "993ed018-9e79-4e50-b97b-984bd5534095", + prompt: #{ text: "You are a concise customer support assistant." }, + agent_id: "a87db7ed-8ebe-42e4-829f-8ba5a4152f54", + name: "Support Assistant", + }, + returnType: #{ statusCode: 200, ai_agent: AI_AGENT_RESPONSE_EXAMPLE }, + }, + #{ + title: "Update the agent prompt", + description: "Replace an AI agent's prompt while leaving its other settings unchanged.", + } + ) @patch(#{ implicitOptionality: true }) update(...AIAgentPathID, ...AIAgentUpdateRequest): | { diff --git a/specs/signalwire-rest/fabric-api/call-flows/main.tsp b/specs/signalwire-rest/fabric-api/call-flows/main.tsp index fce6a00957..cd10a51779 100644 --- a/specs/signalwire-rest/fabric-api/call-flows/main.tsp +++ b/specs/signalwire-rest/fabric-api/call-flows/main.tsp @@ -8,6 +8,7 @@ import "./addresses"; import "./versions"; import "../../types"; import "../tags.tsp"; +import "../_shared/examples.tsp"; import "../../../_shared/alias/token-permissions.tsp"; using TypeSpec.Http; @@ -26,6 +27,18 @@ namespace SignalWireAPI.Fabric.CallFlows { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + returnType: #{ + links: #{ + self: "https://example.signalwire.com/api/fabric/resources/call_flows?page_number=0&page_size=50", + first: "https://example.signalwire.com/api/fabric/resources/call_flows?page_number=0&page_size=50", + }, + data: #[CALL_FLOW_RESPONSE_EXAMPLE], + }, + }, + #{ title: "Call flow list", description: "A page containing one Call Flow." } + ) list(): | CallFlowListResponse | StatusCode401 @@ -39,6 +52,10 @@ namespace SignalWireAPI.Fabric.CallFlows { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ returnType: #{ statusCode: 200, call_flow: CALL_FLOW_RESPONSE_EXAMPLE } }, + #{ title: "Call flow", description: "A Call Flow with a compact SWML document." } + ) read(...CallFlowPathID): | { @statusCode statusCode: 200; @@ -55,6 +72,22 @@ namespace SignalWireAPI.Fabric.CallFlows { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + parameters: #{ + request: #{ + title: "Welcome Call Flow", + flow_data: #{}, + relayml: SWML_CONTENTS_EXAMPLE, + }, + }, + returnType: #{ statusCode: 201, call_flow: CALL_FLOW_RESPONSE_EXAMPLE }, + }, + #{ + title: "Welcome Call Flow", + description: "Create a Call Flow that plays a single audio file.", + } + ) @post create(@body request: CallFlowCreateRequest): | { @@ -73,6 +106,24 @@ namespace SignalWireAPI.Fabric.CallFlows { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + parameters: #{ + id: "993ed018-9e79-4e50-b97b-984bd5534095", + request: #{ + title: "Updated Welcome Call Flow", + document_version: 2, + flow_data: #{}, + relayml: SWML_CONTENTS_EXAMPLE, + }, + }, + returnType: #{ statusCode: 200, call_flow: CALL_FLOW_RESPONSE_EXAMPLE }, + }, + #{ + title: "Update a Call Flow", + description: "Update a Call Flow with its next document revision.", + } + ) @put update(...CallFlowPathID, @body request: CallFlowUpdateRequest): | { diff --git a/specs/signalwire-rest/fabric-api/call-flows/versions/main.tsp b/specs/signalwire-rest/fabric-api/call-flows/versions/main.tsp index fde93dd875..6aaec2cdbe 100644 --- a/specs/signalwire-rest/fabric-api/call-flows/versions/main.tsp +++ b/specs/signalwire-rest/fabric-api/call-flows/versions/main.tsp @@ -5,6 +5,7 @@ import "./models/requests.tsp"; import "./models/responses.tsp"; import "../../../types"; import "../../tags.tsp"; +import "../../_shared/examples.tsp"; import "../../../../_shared/alias/token-permissions.tsp"; using TypeSpec.Http; @@ -22,6 +23,22 @@ namespace SignalWireAPI.Fabric.CallFlow.Versions { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + returnType: #{ + data: #[CALL_FLOW_VERSION_EXAMPLE], + links: #{ + self: "https://example.signalwire.com/api/fabric/resources/call_flow/993ed018-9e79-4e50-b97b-984bd5534095/versions?page_number=0&page_size=50", + first: "https://example.signalwire.com/api/fabric/resources/call_flow/993ed018-9e79-4e50-b97b-984bd5534095/versions?page_number=0&page_size=50", + next: "https://example.signalwire.com/api/fabric/resources/call_flow/993ed018-9e79-4e50-b97b-984bd5534095/versions?page_number=1&page_size=50", + }, + }, + }, + #{ + title: "Call Flow version list", + description: "A page containing one compact Call Flow version.", + } + ) list(...CallFlowVersionPathID): | CallFlowVersionListResponse | StatusCode401 @@ -35,6 +52,29 @@ namespace SignalWireAPI.Fabric.CallFlow.Versions { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + parameters: #{ + id: "993ed018-9e79-4e50-b97b-984bd5534095", + request: #{ document_version: 2 }, + }, + returnType: #{ + statusCode: 201, + response: #{ + id: "3fa85f64-5717-4562-b3fc-2c963f66afa6", + created_at: "2024-05-06T12:20:00Z", + updated_at: "2024-05-06T12:25:00Z", + document_version: 2, + flow_data: #{}, + relayml: SWML_CONTENTS_EXAMPLE, + }, + }, + }, + #{ + title: "Deploy by document version", + description: "Deploy version 2 of a Call Flow.", + } + ) @post deploy( ...CallFlowVersionPathID, diff --git a/specs/signalwire-rest/fabric-api/resources/main.tsp b/specs/signalwire-rest/fabric-api/resources/main.tsp index 7754167310..1154a4283b 100644 --- a/specs/signalwire-rest/fabric-api/resources/main.tsp +++ b/specs/signalwire-rest/fabric-api/resources/main.tsp @@ -7,6 +7,7 @@ import "./models/errors.tsp"; import "./addresses"; import "../../types"; import "../tags.tsp"; +import "../_shared/examples.tsp"; import "../../../_shared/alias/token-permissions.tsp"; using TypeSpec.Http; @@ -25,6 +26,21 @@ namespace SignalWireAPI.Fabric.Resources { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + returnType: #{ + data: #[RESOURCE_AI_EXAMPLE], + links: #{ + self: "https://example.signalwire.com/api/fabric/resources?page_number=0&page_size=50", + first: "https://example.signalwire.com/api/fabric/resources?page_number=0&page_size=50", + }, + }, + }, + #{ + title: "Resource list", + description: "A page containing one compact AI Agent resource.", + } + ) list(): | ResourceListResponse | StatusCode401 @@ -38,6 +54,32 @@ namespace SignalWireAPI.Fabric.Resources { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ returnType: #{ statusCode: 200, resource: RESOURCE_AI_EXAMPLE } }, + #{ title: "AI Agent", description: "An AI Agent Fabric resource." } + ) + @opExample( + #{ returnType: #{ statusCode: 200, resource: RESOURCE_CALL_FLOW_EXAMPLE } }, + #{ title: "Call Flow", description: "A Call Flow with compact SWML content." } + ) + @opExample( + #{ + returnType: #{ + statusCode: 200, + resource: RESOURCE_CALLING_SWML_SCRIPT_EXAMPLE, + }, + }, + #{ title: "Calling script", description: "A compact Calling SWML Script resource." } + ) + @opExample( + #{ + returnType: #{ + statusCode: 200, + resource: RESOURCE_MESSAGING_SWML_SCRIPT_EXAMPLE, + }, + }, + #{ title: "Messaging script", description: "A compact Messaging SWML Script resource." } + ) read(...ResourcePathID): | { @statusCode statusCode: 200; diff --git a/specs/signalwire-rest/fabric-api/swml-scripts/main.tsp b/specs/signalwire-rest/fabric-api/swml-scripts/main.tsp index 00d3ec5520..ba4a22a860 100644 --- a/specs/signalwire-rest/fabric-api/swml-scripts/main.tsp +++ b/specs/signalwire-rest/fabric-api/swml-scripts/main.tsp @@ -7,6 +7,7 @@ import "./models/errors.tsp"; import "./addresses"; import "../../types"; import "../tags.tsp"; +import "../_shared/examples.tsp"; import "../../../_shared/alias/token-permissions.tsp"; using TypeSpec.Http; @@ -23,22 +24,22 @@ const CreateCallingSwmlScriptExample = #{ }, returnType: #{ statusCode: 200, - swml_script: #{ - id: "993ed018-9e79-4e50-b97b-984bd5534095", - project_id: "1313fe58-5e14-4c11-bbe7-6fdfa11fe780", - display_name: "Welcome Script", - type: FabricResponseType.SwmlScript, - created_at: utcDateTime.fromISO("2024-05-06T12:20:00Z"), - updated_at: utcDateTime.fromISO("2024-05-06T12:20:00Z"), - swml_script: #{ - id: "993ed018-9e79-4e50-b97b-984bd5534095", - display_name: "Welcome Script", - script_type: "calling", - request_url: "https://example.signalwire.com/api/fabric/resources/swml_scripts/993ed018-9e79-4e50-b97b-984bd5534095", - contents: SWML_CONTENTS_EXAMPLE, - }, + swml_script: CALLING_SWML_SCRIPT_RESPONSE_EXAMPLE, + }, +}; + +const CreateMessagingSwmlScriptExample = #{ + parameters: #{ + request: #{ + name: "Reply Bot", + script_type: "messaging", + contents: SWML_MESSAGING_CONTENTS_EXAMPLE, } }, + returnType: #{ + statusCode: 200, + swml_script: MESSAGING_SWML_SCRIPT_RESPONSE_EXAMPLE, + }, }; @route("/resources/swml_scripts") @@ -53,6 +54,21 @@ namespace SignalWireAPI.Fabric.SwmlScripts { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + returnType: #[#{ + data: #[CALLING_SWML_SCRIPT_RESPONSE_EXAMPLE], + links: #{ + self: "https://example.signalwire.com/api/fabric/resources/swml_scripts?page_number=0&page_size=50", + first: "https://example.signalwire.com/api/fabric/resources/swml_scripts?page_number=0&page_size=50", + }, + }], + }, + #{ + title: "SWML Script list", + description: "A page containing one compact Calling script.", + } + ) list(): | SwmlScriptListResponse[] | StatusCode401 @@ -66,6 +82,24 @@ namespace SignalWireAPI.Fabric.SwmlScripts { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + returnType: #{ + statusCode: 200, + swml_script: CALLING_SWML_SCRIPT_RESPONSE_EXAMPLE, + }, + }, + #{ title: "Calling script", description: "A Calling script that plays one audio file." } + ) + @opExample( + #{ + returnType: #{ + statusCode: 200, + swml_script: MESSAGING_SWML_SCRIPT_RESPONSE_EXAMPLE, + }, + }, + #{ title: "Messaging script", description: "A Messaging script that sends one reply." } + ) read(...SwmlScriptPathID): | { @statusCode statusCode: 200; @@ -89,6 +123,13 @@ namespace SignalWireAPI.Fabric.SwmlScripts { description: "Create a Calling SWML Script that plays a single audio file.", } ) + @opExample( + CreateMessagingSwmlScriptExample, + #{ + title: "Simple messaging script", + description: "Create a Messaging SWML Script that sends a single reply.", + } + ) @post create(@body request: SwmlScriptCreateRequest): | { @@ -107,6 +148,46 @@ namespace SignalWireAPI.Fabric.SwmlScripts { ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">} """) + @opExample( + #{ + parameters: #{ + id: "993ed018-9e79-4e50-b97b-984bd5534095", + request: #{ + display_name: "Updated Welcome Script", + script_type: "calling", + contents: SWML_CONTENTS_EXAMPLE, + }, + }, + returnType: #{ + statusCode: 200, + swml_script: CALLING_SWML_SCRIPT_RESPONSE_EXAMPLE, + }, + }, + #{ + title: "Update a calling script", + description: "Update a Calling script with a compact SWML document.", + } + ) + @opExample( + #{ + parameters: #{ + id: "3fa85f64-5717-4562-b3fc-2c963f66afa6", + request: #{ + display_name: "Updated Reply Bot", + script_type: "messaging", + contents: SWML_MESSAGING_CONTENTS_EXAMPLE, + }, + }, + returnType: #{ + statusCode: 200, + swml_script: MESSAGING_SWML_SCRIPT_RESPONSE_EXAMPLE, + }, + }, + #{ + title: "Update a messaging script", + description: "Update a Messaging script with a compact SWML document.", + } + ) @put update(...SwmlScriptPathID, @body request: SwmlScriptUpdateRequest): | { From 3bdd2d5a88bf21836a54c396007e6c89447fafed Mon Sep 17 00:00:00 2001 From: Devon-White Date: Thu, 20 Aug 2026 13:48:42 -0400 Subject: [PATCH 5/8] docs: consolidate call command examples --- fern/apis/signalwire-rest/openapi.yaml | 76 +++---------------- .../calling-api/calls/main.tsp | 28 ------- .../calling-api/calls/models/examples.tsp | 49 ------------ 3 files changed, 12 insertions(+), 141 deletions(-) diff --git a/fern/apis/signalwire-rest/openapi.yaml b/fern/apis/signalwire-rest/openapi.yaml index 16679839d0..aa7c2557ff 100644 --- a/fern/apis/signalwire-rest/openapi.yaml +++ b/fern/apis/signalwire-rest/openapi.yaml @@ -601,36 +601,9 @@ paths: schema: $ref: '#/components/schemas/Calling.CallRequest' examples: - calling.transfer with inline SWML: - summary: calling.transfer with inline SWML - description: Transfer an active call to a compact inline SWML document. - value: - command: calling.transfer - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - params: - dest: - version: 1.0.0 - sections: - main: - - play: - url: https://cdn.signalwire.com/swml/audio.mp3 - dial with a destination script: - summary: dial with a destination script - description: Initiate a call whose destination executes a compact inline SWML document. - value: - command: dial - params: - from: '+15551234567' - to_script: - version: 1.0.0 - sections: - main: - - play: - url: https://cdn.signalwire.com/swml/audio.mp3 - url: https://example.com/origin.swml.json - dial with inline SWML: - summary: dial with inline SWML - description: Initiate an outbound call using a compact inline SWML document. + dial: + summary: dial + description: Initiate a new outbound call with the dial command value: command: dial params: @@ -642,30 +615,9 @@ paths: main: - play: url: https://cdn.signalwire.com/swml/audio.mp3 - dial: - summary: dial - description: Initiate a new outbound call with the dial command - value: - command: dial - params: - from: '+15551234567' - to: sip:alice@sip.example.com - url: https://example.com/swml - caller_id: '+15551234567' - username: alice - password: s3cr3t - status_url: https://example.com/status_callback - status_events: - - answered - - ended - codecs: - - PCMU - - PCMA - timeout: 30 - max_price_per_minute: 0.05 - update with inline SWML: - summary: update with inline SWML - description: Redirect an active call to a compact inline SWML document. + update: + summary: update + description: Modify an existing call's parameters in real-time value: command: update params: @@ -676,15 +628,6 @@ paths: main: - play: url: https://cdn.signalwire.com/swml/audio.mp3 - update: - summary: update - description: Modify an existing call's parameters in real-time - value: - command: update - params: - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - url: https://example.com/swml - fallback_url: https://example.com/fallback calling.end: summary: calling.end description: Terminate an active call immediately @@ -763,7 +706,12 @@ paths: command: calling.transfer id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 params: - dest: sip:destination@example.com + dest: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 calling.disconnect: summary: calling.disconnect description: Disconnect a call leg diff --git a/specs/signalwire-rest/calling-api/calls/main.tsp b/specs/signalwire-rest/calling-api/calls/main.tsp index f6515b86a6..d149bd5ceb 100644 --- a/specs/signalwire-rest/calling-api/calls/main.tsp +++ b/specs/signalwire-rest/calling-api/calls/main.tsp @@ -352,13 +352,6 @@ namespace SignalWireAPI.Calling.Calls { description: "Modify an existing call's parameters in real-time", } ) - @opExample( - #{ parameters: updateInlineSwmlCallExample }, - #{ - title: "update with inline SWML", - description: "Redirect an active call to a compact inline SWML document.", - } - ) @opExample( #{ parameters: dialCallExample }, #{ @@ -366,27 +359,6 @@ namespace SignalWireAPI.Calling.Calls { description: "Initiate a new outbound call with the dial command", } ) - @opExample( - #{ parameters: dialInlineSwmlCallExample }, - #{ - title: "dial with inline SWML", - description: "Initiate an outbound call using a compact inline SWML document.", - } - ) - @opExample( - #{ parameters: dialToScriptCallExample }, - #{ - title: "dial with a destination script", - description: "Initiate a call whose destination executes a compact inline SWML document.", - } - ) - @opExample( - #{ parameters: transferInlineSwmlCallExample }, - #{ - title: "calling.transfer with inline SWML", - description: "Transfer an active call to a compact inline SWML document.", - } - ) @post @operationId("call-commands") callCommand(@body request: CallRequest): diff --git a/specs/signalwire-rest/calling-api/calls/models/examples.tsp b/specs/signalwire-rest/calling-api/calls/models/examples.tsp index a3024a2efc..3c939e9d33 100644 --- a/specs/signalwire-rest/calling-api/calls/models/examples.tsp +++ b/specs/signalwire-rest/calling-api/calls/models/examples.tsp @@ -11,25 +11,6 @@ const callId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"; // Call command examples const dialCallExample = #{ - request: #{ - command: "dial", - params: #{ - from: "+15551234567", - to: "sip:alice@sip.example.com", - url: "https://example.com/swml", - caller_id: "+15551234567", - username: "alice", - password: "s3cr3t", - status_url: "https://example.com/status_callback", - status_events: #["answered", "ended"], - codecs: #[OutboundCallCodec.PCMU, OutboundCallCodec.PCMA], - timeout: 30, - max_price_per_minute: 0.05, - }, - }, -}; - -const dialInlineSwmlCallExample = #{ request: #{ command: "dial", params: #{ @@ -40,29 +21,7 @@ const dialInlineSwmlCallExample = #{ }, }; -const dialToScriptCallExample = #{ - request: #{ - command: "dial", - params: #{ - from: "+15551234567", - to_script: CallSWMLDocumentExample, - url: "https://example.com/origin.swml.json", - }, - }, -}; - const updateCallExample = #{ - request: #{ - command: "update", - params: #{ - id: callId, - url: "https://example.com/swml", - fallback_url: "https://example.com/fallback", - }, - }, -}; - -const updateInlineSwmlCallExample = #{ request: #{ command: "update", params: #{ id: callId, swml: CallSWMLDocumentExample }, @@ -525,14 +484,6 @@ const referCallExample = #{ // Transfer example const transferCallExample = #{ - request: #{ - command: "calling.transfer", - id: callId, - params: #{ dest: "sip:destination@example.com" }, - }, -}; - -const transferInlineSwmlCallExample = #{ request: #{ command: "calling.transfer", id: callId, From 1991b0d4740dcbc560ce04018d95bcf6d0a95717 Mon Sep 17 00:00:00 2001 From: Devon-White Date: Thu, 20 Aug 2026 14:01:25 -0400 Subject: [PATCH 6/8] docs: link AI fields to property anchors --- fern/apis/signalwire-rest/openapi.yaml | 60 +++++++++---------- .../fabric-api/ai-agent/models/core.tsp | 20 +++---- 2 files changed, 40 insertions(+), 40 deletions(-) diff --git a/fern/apis/signalwire-rest/openapi.yaml b/fern/apis/signalwire-rest/openapi.yaml index aa7c2557ff..178eaa4294 100644 --- a/fern/apis/signalwire-rest/openapi.yaml +++ b/fern/apis/signalwire-rest/openapi.yaml @@ -15840,7 +15840,7 @@ components: The global_data object is accessible everywhere in the AI session: prompts, AI parameters, and SWML returned from SWAIG functions. Access properties using template strings (e.g. ${global_data.property_name}). - See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai#aiglobal_data). examples: - company_name: Acme Corp support_hours: 9am-5pm EST @@ -15854,7 +15854,7 @@ components: description: |- Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. - See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). examples: - - pizza - pepperoni @@ -15868,7 +15868,7 @@ components: Mutually exclusive with `multilingual`: if both are set, `multilingual` is used and this array is ignored. - See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). + See [`ai.languages` in the SWML reference](/docs/swml/reference/calling/ai#ailanguages). examples: - - name: English code: en-US @@ -15882,7 +15882,7 @@ components: several languages. Mutually exclusive with `languages`: if both are set, `multilingual` is used and `languages` is ignored. - See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). + See [`ai.multilingual` in the SWML reference](/docs/swml/reference/calling/ai#aimultilingual). examples: - languages: - language: en @@ -15898,7 +15898,7 @@ components: description: |- A JSON object containing parameters as key-value pairs. - See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). + See [`ai.params` in the SWML reference](/docs/swml/reference/calling/ai#aiparams). examples: - ai_model: gpt-4o-mini wait_for_user: true @@ -15908,7 +15908,7 @@ components: description: |- The final set of instructions and configuration settings to send to the agent. - See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt). examples: - text: Summarize the conversation and provide any follow-up action items. post_prompt_url: @@ -15917,7 +15917,7 @@ components: description: |- The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. - See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#post_prompt_url-callback). + See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt_url). examples: - username:password@https://example.com pronounce: @@ -15928,7 +15928,7 @@ components: description: |- An array of JSON objects to clarify the AI's pronunciation of words or expressions. - See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai#aipronounce). examples: - - replace: SWML with: swim-el @@ -15941,7 +15941,7 @@ components: The prompt establishes how the agent should interact with callers, what information it should gather, and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. - See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). + See [`ai.prompt` in the SWML reference](/docs/swml/reference/calling/ai#aiprompt). examples: - text: You are a helpful customer support assistant. SWAIG: @@ -15950,7 +15950,7 @@ components: description: |- An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. - See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). + See [`ai.SWAIG` in the SWML reference](/docs/swml/reference/calling/ai#aiswaig). examples: - native_functions: - check_time @@ -16008,7 +16008,7 @@ components: The global_data object is accessible everywhere in the AI session: prompts, AI parameters, and SWML returned from SWAIG functions. Access properties using template strings (e.g. ${global_data.property_name}). - See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai#aiglobal_data). examples: - company_name: Acme Corp support_hours: 9am-5pm EST @@ -16022,7 +16022,7 @@ components: description: |- Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. - See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). examples: - - pizza - pepperoni @@ -16036,7 +16036,7 @@ components: Mutually exclusive with `multilingual`: if both are set, `multilingual` is used and this array is ignored. - See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). + See [`ai.languages` in the SWML reference](/docs/swml/reference/calling/ai#ailanguages). examples: - - name: English code: en-US @@ -16050,7 +16050,7 @@ components: several languages. Mutually exclusive with `languages`: if both are set, `multilingual` is used and `languages` is ignored. - See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). + See [`ai.multilingual` in the SWML reference](/docs/swml/reference/calling/ai#aimultilingual). examples: - languages: - language: en @@ -16066,7 +16066,7 @@ components: description: |- A JSON object containing parameters as key-value pairs. - See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). + See [`ai.params` in the SWML reference](/docs/swml/reference/calling/ai#aiparams). examples: - ai_model: gpt-4o-mini wait_for_user: true @@ -16076,7 +16076,7 @@ components: description: |- The final set of instructions and configuration settings to send to the agent. - See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt). examples: - text: Summarize the conversation and provide any follow-up action items. post_prompt_url: @@ -16085,7 +16085,7 @@ components: description: |- The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. - See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#post_prompt_url-callback). + See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt_url). examples: - username:password@https://example.com pronounce: @@ -16096,7 +16096,7 @@ components: description: |- An array of JSON objects to clarify the AI's pronunciation of words or expressions. - See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai#aipronounce). examples: - - replace: SWML with: swim-el @@ -16109,7 +16109,7 @@ components: The prompt establishes how the agent should interact with callers, what information it should gather, and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. - See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). + See [`ai.prompt` in the SWML reference](/docs/swml/reference/calling/ai#aiprompt). examples: - text: You are a helpful customer support assistant. SWAIG: @@ -16118,7 +16118,7 @@ components: description: |- An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. - See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). + See [`ai.SWAIG` in the SWML reference](/docs/swml/reference/calling/ai#aiswaig). examples: - native_functions: - check_time @@ -16270,7 +16270,7 @@ components: The global_data object is accessible everywhere in the AI session: prompts, AI parameters, and SWML returned from SWAIG functions. Access properties using template strings (e.g. ${global_data.property_name}). - See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai#aiglobal_data). examples: - company_name: Acme Corp support_hours: 9am-5pm EST @@ -16284,7 +16284,7 @@ components: description: |- Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. - See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). examples: - - pizza - pepperoni @@ -16298,7 +16298,7 @@ components: Mutually exclusive with `multilingual`: if both are set, `multilingual` is used and this array is ignored. - See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). + See [`ai.languages` in the SWML reference](/docs/swml/reference/calling/ai#ailanguages). examples: - - name: English code: en-US @@ -16312,7 +16312,7 @@ components: several languages. Mutually exclusive with `languages`: if both are set, `multilingual` is used and `languages` is ignored. - See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). + See [`ai.multilingual` in the SWML reference](/docs/swml/reference/calling/ai#aimultilingual). examples: - languages: - language: en @@ -16328,7 +16328,7 @@ components: description: |- A JSON object containing parameters as key-value pairs. - See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). + See [`ai.params` in the SWML reference](/docs/swml/reference/calling/ai#aiparams). examples: - ai_model: gpt-4o-mini wait_for_user: true @@ -16338,7 +16338,7 @@ components: description: |- The final set of instructions and configuration settings to send to the agent. - See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt). examples: - text: Summarize the conversation and provide any follow-up action items. post_prompt_url: @@ -16347,7 +16347,7 @@ components: description: |- The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. - See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#post_prompt_url-callback). + See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt_url). examples: - username:password@https://example.com pronounce: @@ -16358,7 +16358,7 @@ components: description: |- An array of JSON objects to clarify the AI's pronunciation of words or expressions. - See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai#aipronounce). examples: - - replace: SWML with: swim-el @@ -16371,7 +16371,7 @@ components: The prompt establishes how the agent should interact with callers, what information it should gather, and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting. - See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). + See [`ai.prompt` in the SWML reference](/docs/swml/reference/calling/ai#aiprompt). examples: - text: You are a helpful customer support assistant. SWAIG: @@ -16380,7 +16380,7 @@ components: description: |- An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. - See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). + See [`ai.SWAIG` in the SWML reference](/docs/swml/reference/calling/ai#aiswaig). examples: - native_functions: - check_time diff --git a/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp b/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp index f18f0029c2..7cfbced86f 100644 --- a/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp +++ b/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp @@ -21,7 +21,7 @@ model AIAgent { @doc(""" ${SWML.Calling.aiGlobalDataDescription} - See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai#aiglobal_data). """) @example(#{ company_name: "Acme Corp", support_hours: "9am-5pm EST" }) global_data?: TypeSpec.Record; @@ -29,7 +29,7 @@ model AIAgent { @doc(""" ${SWML.Calling.aiHintsDescription} - See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). """) @example(#["pizza", "pepperoni"]) hints?: (string | TypeSpec.Record)[]; @@ -37,7 +37,7 @@ model AIAgent { @doc(""" ${SWML.Calling.aiLanguagesDescription} - See the [SWML `ai.languages` reference](/docs/swml/reference/calling/ai/languages). + See [`ai.languages` in the SWML reference](/docs/swml/reference/calling/ai#ailanguages). """) @example(#[#{ name: "English", code: "en-US", voice: "rime.spore" }]) languages?: TypeSpec.Record[]; @@ -45,7 +45,7 @@ model AIAgent { @doc(""" ${SWML.Calling.aiMultilingualDescription} - See the [SWML `ai.multilingual` reference](/docs/swml/reference/calling/ai/multilingual). + See [`ai.multilingual` in the SWML reference](/docs/swml/reference/calling/ai#aimultilingual). """) @example(#{ languages: #[ @@ -59,7 +59,7 @@ model AIAgent { @doc(""" ${SWML.Calling.aiParamsDescription} - See the [SWML `ai.params` reference](/docs/swml/reference/calling/ai/params). + See [`ai.params` in the SWML reference](/docs/swml/reference/calling/ai#aiparams). """) @example(#{ ai_model: "gpt-4o-mini", wait_for_user: true }) params?: TypeSpec.Record; @@ -67,7 +67,7 @@ model AIAgent { @doc(""" ${SWML.Calling.aiPostPromptDescription} - See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt). """) @example(#{ text: "Summarize the conversation and provide any follow-up action items.", @@ -77,7 +77,7 @@ model AIAgent { @doc(""" ${SWML.Calling.aiPostPromptUrlDescription} - See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#post_prompt_url-callback). + See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt_url). """) @example("username:password@https://example.com") post_prompt_url?: url; @@ -85,7 +85,7 @@ model AIAgent { @doc(""" ${SWML.Calling.aiPronounceDescription} - See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai). + See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai#aipronounce). """) @example(#[#{ replace: "SWML", with: "swim-el", ignore_case: true }]) pronounce?: TypeSpec.Record[]; @@ -93,7 +93,7 @@ model AIAgent { @doc(""" ${SWML.Calling.aiPromptDescription} - See the [SWML `ai.prompt` reference](/docs/swml/reference/calling/ai/prompt). + See [`ai.prompt` in the SWML reference](/docs/swml/reference/calling/ai#aiprompt). """) @example(#{ text: "You are a helpful customer support assistant." }) prompt: TypeSpec.Record; @@ -101,7 +101,7 @@ model AIAgent { @doc(""" ${SWML.Calling.aiSwaigDescription} - See the [SWML `ai.SWAIG` reference](/docs/swml/reference/calling/ai/swaig). + See [`ai.SWAIG` in the SWML reference](/docs/swml/reference/calling/ai#aiswaig). """) @example(#{ native_functions: #["check_time"] }) SWAIG?: TypeSpec.Record; From 6e8c639da6b3a9c60230c22f9f82575cf9ee0255 Mon Sep 17 00:00:00 2001 From: Devon-White Date: Thu, 20 Aug 2026 14:06:07 -0400 Subject: [PATCH 7/8] docs: link open SWML call fields to reference --- fern/apis/signalwire-rest/openapi.yaml | 12 ++++++------ .../calling-api/calls/models/requests.tsp | 8 ++++---- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/fern/apis/signalwire-rest/openapi.yaml b/fern/apis/signalwire-rest/openapi.yaml index 178eaa4294..b68dd53b3a 100644 --- a/fern/apis/signalwire-rest/openapi.yaml +++ b/fern/apis/signalwire-rest/openapi.yaml @@ -18794,7 +18794,7 @@ components: - type: string - type: object unevaluatedProperties: {} - description: Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. + description: Inline [Calling SWML document](/docs/swml/reference/calling) (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. examples: - version: 1.0.0 sections: @@ -18931,7 +18931,7 @@ components: - type: string - type: object unevaluatedProperties: {} - description: Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. + description: Inline [Calling SWML document](/docs/swml/reference/calling) (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. examples: - version: 1.0.0 sections: @@ -19038,7 +19038,7 @@ components: swml: type: object unevaluatedProperties: {} - description: Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call. + description: Inline [Calling SWML document](/docs/swml/reference/calling) containing instructions for handling the call. Either `url` or `swml` must be included for a new call. examples: - version: 1.0.0 sections: @@ -19079,7 +19079,7 @@ components: - type: string - type: object unevaluatedProperties: {} - description: Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. + description: Inline [Calling SWML document](/docs/swml/reference/calling) (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. examples: - version: 1.0.0 sections: @@ -20698,7 +20698,7 @@ components: - type: string - type: object unevaluatedProperties: {} - description: The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline SWML object. + description: The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline [Calling SWML document](/docs/swml/reference/calling). examples: - version: 1.0.0 sections: @@ -20850,7 +20850,7 @@ components: swml: type: object unevaluatedProperties: {} - description: Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call. + description: Inline [Calling SWML document](/docs/swml/reference/calling) containing instructions for handling the call. Either `url` or `swml` must be included for a new call. examples: - version: 1.0.0 sections: diff --git a/specs/signalwire-rest/calling-api/calls/models/requests.tsp b/specs/signalwire-rest/calling-api/calls/models/requests.tsp index b17ca0e279..0a47eb1c91 100644 --- a/specs/signalwire-rest/calling-api/calls/models/requests.tsp +++ b/specs/signalwire-rest/calling-api/calls/models/requests.tsp @@ -433,7 +433,7 @@ model CallCreateParamsBase { @example("s3cr3t") password?: string; - @doc("Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted.") + @doc("Inline [Calling SWML document](/docs/swml/reference/calling) (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted.") @example("https://example.com/destination.swml.json") @example(CallSWMLDocumentExample) to_script?: string | TypeSpec.Record; @@ -510,7 +510,7 @@ model CallCreateParamsURL is CallCreateParamsBase { @summary("dial (Inline SWML)") model CallCreateParamsSWML is CallCreateParamsBase { - @doc("Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call.") + @doc("Inline [Calling SWML document](/docs/swml/reference/calling) containing instructions for handling the call. Either `url` or `swml` must be included for a new call.") @example(CallSWMLDocumentExample) swml: TypeSpec.Record; } @@ -539,7 +539,7 @@ model CallUpdateParamsBase { @summary("update (Inline SWML)") model CallUpdateParamsSWML is CallUpdateParamsBase { - @doc("Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call.") + @doc("Inline [Calling SWML document](/docs/swml/reference/calling) containing instructions for handling the call. Either `url` or `swml` must be included for a new call.") @example(CallSWMLDocumentExample) swml: TypeSpec.Record; } @@ -1927,7 +1927,7 @@ model CallTransferRequest { @doc(paramsDescription) params: { - @doc("The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline SWML object.") + @doc("The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline [Calling SWML document](/docs/swml/reference/calling).") @example("sip:destination@example.com") @example(CallSWMLDocumentExample) dest: string | TypeSpec.Record; From a371d82020459847ceaf9e6b5bd79a9641a53940 Mon Sep 17 00:00:00 2001 From: Devon-White Date: Thu, 20 Aug 2026 16:07:54 -0400 Subject: [PATCH 8/8] fix: align fabric AI agent schema with API --- fern/apis/signalwire-rest/openapi.yaml | 153 +----------------- .../fabric-api/_shared/examples.tsp | 5 + .../fabric-api/ai-agent/main.tsp | 3 +- .../fabric-api/ai-agent/models/core.tsp | 16 +- .../fabric-api/ai-agent/models/requests.tsp | 6 +- 5 files changed, 28 insertions(+), 155 deletions(-) diff --git a/fern/apis/signalwire-rest/openapi.yaml b/fern/apis/signalwire-rest/openapi.yaml index b68dd53b3a..91c1b6a215 100644 --- a/fern/apis/signalwire-rest/openapi.yaml +++ b/fern/apis/signalwire-rest/openapi.yaml @@ -1912,7 +1912,6 @@ paths: value: prompt: text: You are a helpful customer support assistant. - agent_id: a87db7ed-8ebe-42e4-829f-8ba5a4152f54 name: Support Assistant /api/fabric/resources/ai_agents/{ai_agent_id}/addresses: get: @@ -2087,7 +2086,6 @@ paths: value: prompt: text: You are a concise customer support assistant. - agent_id: a87db7ed-8ebe-42e4-829f-8ba5a4152f54 name: Support Assistant delete: operationId: delete_ai_agent @@ -15831,26 +15829,10 @@ components: - agent_id - name properties: - global_data: - type: object - unevaluatedProperties: {} - description: |- - A key-value object for storing data that persists throughout the AI session. - Can be set initially in the SWML script or modified during the conversation using the set_global_data action. - The global_data object is accessible everywhere in the AI session: prompts, AI parameters, - and SWML returned from SWAIG functions. Access properties using template strings (e.g. ${global_data.property_name}). - - See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai#aiglobal_data). - examples: - - company_name: Acme Corp - support_hours: 9am-5pm EST hints: type: array items: - anyOf: - - type: string - - type: object - unevaluatedProperties: {} + type: string description: |- Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. @@ -15873,25 +15855,6 @@ components: - - name: English code: en-US voice: rime.spore - multilingual: - type: object - unevaluatedProperties: {} - description: |- - Configures a single agent to detect the caller's language and answer in it, switching - as the caller switches. Use this instead of `languages` when one conversation may span - several languages. Mutually exclusive with `languages`: if both are set, `multilingual` - is used and `languages` is ignored. - - See [`ai.multilingual` in the SWML reference](/docs/swml/reference/calling/ai#aimultilingual). - examples: - - languages: - - language: en - voice: rime.spore - - language: es - voice: elevenlabs.rachel:eleven_flash_v2_5 - allowed: - - en - - es params: type: object unevaluatedProperties: {} @@ -15911,15 +15874,6 @@ components: See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt). examples: - text: Summarize the conversation and provide any follow-up action items. - post_prompt_url: - type: string - format: uri - description: |- - The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. - - See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt_url). - examples: - - username:password@https://example.com pronounce: type: array items: @@ -15996,29 +15950,12 @@ components: type: object required: - prompt - - agent_id - name properties: - global_data: - type: object - unevaluatedProperties: {} - description: |- - A key-value object for storing data that persists throughout the AI session. - Can be set initially in the SWML script or modified during the conversation using the set_global_data action. - The global_data object is accessible everywhere in the AI session: prompts, AI parameters, - and SWML returned from SWAIG functions. Access properties using template strings (e.g. ${global_data.property_name}). - - See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai#aiglobal_data). - examples: - - company_name: Acme Corp - support_hours: 9am-5pm EST hints: type: array items: - anyOf: - - type: string - - type: object - unevaluatedProperties: {} + type: string description: |- Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. @@ -16041,25 +15978,6 @@ components: - - name: English code: en-US voice: rime.spore - multilingual: - type: object - unevaluatedProperties: {} - description: |- - Configures a single agent to detect the caller's language and answer in it, switching - as the caller switches. Use this instead of `languages` when one conversation may span - several languages. Mutually exclusive with `languages`: if both are set, `multilingual` - is used and `languages` is ignored. - - See [`ai.multilingual` in the SWML reference](/docs/swml/reference/calling/ai#aimultilingual). - examples: - - languages: - - language: en - voice: rime.spore - - language: es - voice: elevenlabs.rachel:eleven_flash_v2_5 - allowed: - - en - - es params: type: object unevaluatedProperties: {} @@ -16079,15 +15997,6 @@ components: See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt). examples: - text: Summarize the conversation and provide any follow-up action items. - post_prompt_url: - type: string - format: uri - description: |- - The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. - - See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt_url). - examples: - - username:password@https://example.com pronounce: type: array items: @@ -16122,12 +16031,6 @@ components: examples: - native_functions: - check_time - agent_id: - allOf: - - $ref: '#/components/schemas/uuid' - description: Unique ID of an AI Agent. - examples: - - 3fa85f64-5717-4562-b3fc-2c963f66afa6 name: type: string description: Name of the AI Agent. @@ -16261,26 +16164,10 @@ components: AIAgentUpdateRequest: type: object properties: - global_data: - type: object - unevaluatedProperties: {} - description: |- - A key-value object for storing data that persists throughout the AI session. - Can be set initially in the SWML script or modified during the conversation using the set_global_data action. - The global_data object is accessible everywhere in the AI session: prompts, AI parameters, - and SWML returned from SWAIG functions. Access properties using template strings (e.g. ${global_data.property_name}). - - See [`ai.global_data` in the SWML reference](/docs/swml/reference/calling/ai#aiglobal_data). - examples: - - company_name: Acme Corp - support_hours: 9am-5pm EST hints: type: array items: - anyOf: - - type: string - - type: object - unevaluatedProperties: {} + type: string description: |- Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately. @@ -16303,25 +16190,6 @@ components: - - name: English code: en-US voice: rime.spore - multilingual: - type: object - unevaluatedProperties: {} - description: |- - Configures a single agent to detect the caller's language and answer in it, switching - as the caller switches. Use this instead of `languages` when one conversation may span - several languages. Mutually exclusive with `languages`: if both are set, `multilingual` - is used and `languages` is ignored. - - See [`ai.multilingual` in the SWML reference](/docs/swml/reference/calling/ai#aimultilingual). - examples: - - languages: - - language: en - voice: rime.spore - - language: es - voice: elevenlabs.rachel:eleven_flash_v2_5 - allowed: - - en - - es params: type: object unevaluatedProperties: {} @@ -16341,15 +16209,6 @@ components: See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt). examples: - text: Summarize the conversation and provide any follow-up action items. - post_prompt_url: - type: string - format: uri - description: |- - The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of `username:password@url`. - - See [`ai.post_prompt_url` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt_url). - examples: - - username:password@https://example.com pronounce: type: array items: @@ -16384,12 +16243,6 @@ components: examples: - native_functions: - check_time - agent_id: - allOf: - - $ref: '#/components/schemas/uuid' - description: Unique ID of an AI Agent. - examples: - - 3fa85f64-5717-4562-b3fc-2c963f66afa6 name: type: string description: Name of the AI Agent. diff --git a/specs/signalwire-rest/fabric-api/_shared/examples.tsp b/specs/signalwire-rest/fabric-api/_shared/examples.tsp index 50f169c745..0f84a3276c 100644 --- a/specs/signalwire-rest/fabric-api/_shared/examples.tsp +++ b/specs/signalwire-rest/fabric-api/_shared/examples.tsp @@ -6,6 +6,11 @@ const FABRIC_PROJECT_ID_EXAMPLE = "1313fe58-5e14-4c11-bbe7-6fdfa11fe780"; const FABRIC_CREATED_AT_EXAMPLE = utcDateTime.fromISO("2024-05-06T12:20:00Z"); const FABRIC_UPDATED_AT_EXAMPLE = utcDateTime.fromISO("2024-05-06T12:25:00Z"); +const AI_AGENT_REQUEST_EXAMPLE = #{ + prompt: #{ text: "You are a helpful customer support assistant." }, + name: "Support Assistant", +}; + const AI_AGENT_EXAMPLE = #{ prompt: #{ text: "You are a helpful customer support assistant." }, agent_id: "a87db7ed-8ebe-42e4-829f-8ba5a4152f54", diff --git a/specs/signalwire-rest/fabric-api/ai-agent/main.tsp b/specs/signalwire-rest/fabric-api/ai-agent/main.tsp index 564815a691..a5725d2f5d 100644 --- a/specs/signalwire-rest/fabric-api/ai-agent/main.tsp +++ b/specs/signalwire-rest/fabric-api/ai-agent/main.tsp @@ -69,7 +69,7 @@ namespace SignalWireAPI.Fabric.AIAgents { """) @opExample( #{ - parameters: AI_AGENT_EXAMPLE, + parameters: AI_AGENT_REQUEST_EXAMPLE, returnType: #{ statusCode: 201, ai_agent: AI_AGENT_RESPONSE_EXAMPLE }, }, #{ @@ -100,7 +100,6 @@ namespace SignalWireAPI.Fabric.AIAgents { parameters: #{ id: "993ed018-9e79-4e50-b97b-984bd5534095", prompt: #{ text: "You are a concise customer support assistant." }, - agent_id: "a87db7ed-8ebe-42e4-829f-8ba5a4152f54", name: "Support Assistant", }, returnType: #{ statusCode: 200, ai_agent: AI_AGENT_RESPONSE_EXAMPLE }, diff --git a/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp b/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp index 7cfbced86f..59ad7be7eb 100644 --- a/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp +++ b/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp @@ -18,6 +18,9 @@ model AIAgentPathID { See the [SWML `ai` method reference](/docs/swml/reference/calling/ai) for the complete configuration contract. """) model AIAgent { + // TODO(https://github.com/signalwire/cloud-product/issues/20538): Re-enable + // when the Fabric AI Agent API persists this SWML property. + /* @doc(""" ${SWML.Calling.aiGlobalDataDescription} @@ -25,6 +28,7 @@ model AIAgent { """) @example(#{ company_name: "Acme Corp", support_hours: "9am-5pm EST" }) global_data?: TypeSpec.Record; + */ @doc(""" ${SWML.Calling.aiHintsDescription} @@ -32,7 +36,9 @@ model AIAgent { See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). """) @example(#["pizza", "pepperoni"]) - hints?: (string | TypeSpec.Record)[]; + // TODO(https://github.com/signalwire/cloud-product/issues/20539): Restore + // `(string | TypeSpec.Record)[]` when structured hints are accepted. + hints?: string[]; @doc(""" ${SWML.Calling.aiLanguagesDescription} @@ -42,6 +48,9 @@ model AIAgent { @example(#[#{ name: "English", code: "en-US", voice: "rime.spore" }]) languages?: TypeSpec.Record[]; + // TODO(https://github.com/signalwire/cloud-product/issues/20538): Re-enable + // when the Fabric AI Agent API persists this SWML property. + /* @doc(""" ${SWML.Calling.aiMultilingualDescription} @@ -55,6 +64,7 @@ model AIAgent { allowed: #["en", "es"], }) multilingual?: TypeSpec.Record; + */ @doc(""" ${SWML.Calling.aiParamsDescription} @@ -74,6 +84,9 @@ model AIAgent { }) post_prompt?: TypeSpec.Record; + // TODO(https://github.com/signalwire/cloud-product/issues/20538): Re-enable + // when the Fabric AI Agent API persists this SWML property. + /* @doc(""" ${SWML.Calling.aiPostPromptUrlDescription} @@ -81,6 +94,7 @@ model AIAgent { """) @example("username:password@https://example.com") post_prompt_url?: url; + */ @doc(""" ${SWML.Calling.aiPronounceDescription} diff --git a/specs/signalwire-rest/fabric-api/ai-agent/models/requests.tsp b/specs/signalwire-rest/fabric-api/ai-agent/models/requests.tsp index 1ade2c6717..4d4392d9b0 100644 --- a/specs/signalwire-rest/fabric-api/ai-agent/models/requests.tsp +++ b/specs/signalwire-rest/fabric-api/ai-agent/models/requests.tsp @@ -1,7 +1,9 @@ model AIAgentCreateRequest { - ...AIAgent; + // agent_id is server-generated and ignored when supplied by clients. + ...OmitProperties; } model AIAgentUpdateRequest { - ...AIAgent; + // agent_id is server-generated and ignored when supplied by clients. + ...OmitProperties; }