diff --git a/fern/apis/signalwire-rest/openapi.yaml b/fern/apis/signalwire-rest/openapi.yaml index 832a5330c1..91c1b6a215 100644 --- a/fern/apis/signalwire-rest/openapi.yaml +++ b/fern/apis/signalwire-rest/openapi.yaml @@ -608,20 +608,13 @@ paths: 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 + to: '+15557654321' + 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 @@ -629,8 +622,12 @@ paths: command: update params: id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - url: https://example.com/swml - fallback_url: https://example.com/fallback + swml: + version: 1.0.0 + sections: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 calling.end: summary: calling.end description: Terminate an active call immediately @@ -709,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 @@ -1736,6 +1738,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 +1798,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 +1857,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 +1905,14 @@ 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. + name: Support Assistant /api/fabric/resources/ai_agents/{ai_agent_id}/addresses: get: operationId: list_ai_agent_addresses @@ -1909,6 +1975,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 +2031,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 +2079,14 @@ 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. + name: Support Assistant delete: operationId: delete_ai_agent summary: Delete AI agent @@ -2079,6 +2185,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 +2246,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 +2294,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 +2320,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 +2385,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 +2439,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 +2473,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 +2535,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 +2589,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 +5398,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: @@ -5169,6 +5463,48 @@ paths: application/json: 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. + 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: @@ -5201,6 +5537,30 @@ paths: application/json: 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. + 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 @@ -5222,6 +5582,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: @@ -5262,6 +5664,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: @@ -5294,6 +5738,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 @@ -5653,6 +6121,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: @@ -15283,73 +15829,85 @@ components: - agent_id - name properties: - global_data: - allOf: - - $ref: '#/components/schemas/SWML.Calling.GlobalData' - 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}). - examples: - - company_name: Acme Corp - support_hours: 9am-5pm EST hints: type: array 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: 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. + + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). 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. - multilingual: - allOf: - - $ref: '#/components/schemas/SWML.Calling.Multilingual' - 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.languages` in the SWML reference](/docs/swml/reference/calling/ai#ailanguages). + examples: + - - name: English + code: en-US + voice: rime.spore 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 [`ai.params` in the SWML reference](/docs/swml/reference/calling/ai#aiparams). + examples: + - ai_model: gpt-4o-mini + wait_for_user: true post_prompt: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIPostPrompt' - description: The final set of instructions and configuration settings to send to the agent. - 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`. + 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#aipost_prompt). examples: - - username:password@https://example.com + - text: Summarize the conversation and provide any follow-up action items. 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#aipronounce). + examples: + - - replace: SWML + with: swim-el + ignore_case: true 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 [`ai.prompt` in the SWML reference](/docs/swml/reference/calling/ai#aiprompt). + examples: + - text: You are a helpful customer support assistant. 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 [`ai.SWAIG` in the SWML reference](/docs/swml/reference/calling/ai#aiswaig). + examples: + - native_functions: + - check_time agent_id: allOf: - $ref: '#/components/schemas/uuid' @@ -15363,7 +15921,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 @@ -15386,82 +15950,87 @@ components: type: object required: - prompt - - agent_id - name properties: - global_data: - allOf: - - $ref: '#/components/schemas/SWML.Calling.GlobalData' - 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}). - examples: - - company_name: Acme Corp - support_hours: 9am-5pm EST hints: type: array 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: 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. + + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). 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. - multilingual: - allOf: - - $ref: '#/components/schemas/SWML.Calling.Multilingual' - 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.languages` in the SWML reference](/docs/swml/reference/calling/ai#ailanguages). + examples: + - - name: English + code: en-US + voice: rime.spore 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 [`ai.params` in the SWML reference](/docs/swml/reference/calling/ai#aiparams). + examples: + - ai_model: gpt-4o-mini + wait_for_user: true post_prompt: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIPostPrompt' - description: The final set of instructions and configuration settings to send to the agent. - 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`. + 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#aipost_prompt). examples: - - username:password@https://example.com + - text: Summarize the conversation and provide any follow-up action items. 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#aipronounce). + examples: + - - replace: SWML + with: swim-el + ignore_case: true 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 [`ai.prompt` in the SWML reference](/docs/swml/reference/calling/ai#aiprompt). + examples: + - text: You are a helpful customer support assistant. 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. - agent_id: - allOf: - - $ref: '#/components/schemas/uuid' - description: Unique ID of an AI Agent. + type: object + unevaluatedProperties: {} + description: |- + An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. + + See [`ai.SWAIG` in the SWML reference](/docs/swml/reference/calling/ai#aiswaig). examples: - - 3fa85f64-5717-4562-b3fc-2c963f66afa6 + - native_functions: + - check_time name: type: string description: Name of the AI Agent. @@ -15595,79 +16164,85 @@ components: AIAgentUpdateRequest: type: object properties: - global_data: - allOf: - - $ref: '#/components/schemas/SWML.Calling.GlobalData' - 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}). - examples: - - company_name: Acme Corp - support_hours: 9am-5pm EST hints: type: array 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: 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. + + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). 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. - multilingual: - allOf: - - $ref: '#/components/schemas/SWML.Calling.MultilingualUpdate' - 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.languages` in the SWML reference](/docs/swml/reference/calling/ai#ailanguages). + examples: + - - name: English + code: en-US + voice: rime.spore 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 [`ai.params` in the SWML reference](/docs/swml/reference/calling/ai#aiparams). + examples: + - ai_model: gpt-4o-mini + wait_for_user: true post_prompt: - allOf: - - $ref: '#/components/schemas/SWML.Calling.AIPostPromptUpdate' - description: The final set of instructions and configuration settings to send to the agent. - 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`. + 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#aipost_prompt). examples: - - username:password@https://example.com + - text: Summarize the conversation and provide any follow-up action items. 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#aipronounce). + examples: + - - replace: SWML + with: swim-el + ignore_case: true 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 [`ai.prompt` in the SWML reference](/docs/swml/reference/calling/ai#aiprompt). + examples: + - text: You are a helpful customer support assistant. 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. - agent_id: - allOf: - - $ref: '#/components/schemas/uuid' - description: Unique ID of an AI Agent. + type: object + unevaluatedProperties: {} + description: |- + An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. + + See [`ai.SWAIG` in the SWML reference](/docs/swml/reference/calling/ai#aiswaig). examples: - - 3fa85f64-5717-4562-b3fc-2c963f66afa6 + - native_functions: + - check_time name: type: string description: Name of the AI Agent. @@ -17072,8 +17647,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 +17730,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 +17857,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 +17925,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 +18005,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,9 +18645,15 @@ components: to_script: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' - 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. + - type: object + unevaluatedProperties: {} + 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: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 - https://example.com/destination.swml.json caller_id: type: string @@ -18201,9 +18782,15 @@ components: to_script: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' - 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. + - type: object + unevaluatedProperties: {} + 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: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 - https://example.com/destination.swml.json caller_id: type: string @@ -18302,9 +18889,15 @@ components: - id: '12345' case_number: '54321' swml: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' - description: Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call. + type: object + unevaluatedProperties: {} + 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: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 unevaluatedProperties: not: {} title: dial (Inline SWML) @@ -18337,9 +18930,15 @@ components: to_script: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' - 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. + - type: object + unevaluatedProperties: {} + 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: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 - https://example.com/destination.swml.json caller_id: type: string @@ -19950,9 +20549,15 @@ components: dest: anyOf: - type: string - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' - description: The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline SWML object. + - type: object + unevaluatedProperties: {} + 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: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 - sip:destination@example.com required: - dest @@ -20096,9 +20701,15 @@ components: examples: - https://example.com/status_callback swml: - allOf: - - $ref: '#/components/schemas/SWML.Calling.SWMLObject' - description: Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call. + type: object + unevaluatedProperties: {} + 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: + main: + - play: + url: https://cdn.signalwire.com/swml/audio.mp3 unevaluatedProperties: not: {} title: update (Inline SWML) @@ -21463,8 +22074,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 +22120,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 +22156,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 +29227,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 +29258,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 +29286,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,70 +33798,6 @@ components: unevaluatedProperties: not: {} title: Post-Prompt with POM - SWML.Calling.AIPostPromptPomUpdate: - 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: The instructions to send to the agent. - unevaluatedProperties: - not: {} - title: Post-Prompt with POM SWML.Calling.AIPostPromptText: type: object required: @@ -33316,73 +33863,6 @@ components: 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' @@ -33464,81 +33944,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 +34016,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 +36873,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 +36907,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 +36939,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 +38857,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: @@ -40262,6 +40396,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: @@ -42681,6 +42821,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: @@ -42806,6 +42951,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/examples.tsp b/specs/signalwire-rest/calling-api/calls/models/examples.tsp index 1e867a8d93..3c939e9d33 100644 --- a/specs/signalwire-rest/calling-api/calls/models/examples.tsp +++ b/specs/signalwire-rest/calling-api/calls/models/examples.tsp @@ -15,16 +15,8 @@ const dialCallExample = #{ 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, + to: "+15557654321", + swml: CallSWMLDocumentExample, }, }, }; @@ -32,11 +24,7 @@ const dialCallExample = #{ const updateCallExample = #{ request: #{ command: "update", - params: #{ - id: callId, - url: "https://example.com/swml", - fallback_url: "https://example.com/fallback", - }, + params: #{ id: callId, swml: CallSWMLDocumentExample }, }, }; @@ -499,7 +487,7 @@ const transferCallExample = #{ request: #{ command: "calling.transfer", id: callId, - params: #{ dest: "sip:destination@example.com" }, + params: #{ dest: CallSWMLDocumentExample }, }, }; diff --git a/specs/signalwire-rest/calling-api/calls/models/requests.tsp b/specs/signalwire-rest/calling-api/calls/models/requests.tsp index 9a810edcd0..0a47eb1c91 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; @@ -14,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"; @@ -425,9 +433,10 @@ 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") - to_script?: string | SWMLObject; + @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.") @example("+1234567890") @@ -501,8 +510,9 @@ 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; + @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; } @summary("update") @@ -529,8 +539,9 @@ 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; + @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; } @summary("update (URL)") @@ -1916,9 +1927,10 @@ 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") - dest: string | SWMLObject; + @example(CallSWMLDocumentExample) + dest: string | TypeSpec.Record; }; } 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..0f84a3276c --- /dev/null +++ b/specs/signalwire-rest/fabric-api/_shared/examples.tsp @@ -0,0 +1,131 @@ +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_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", + 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..a5725d2f5d 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_REQUEST_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,20 @@ 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." }, + 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/ai-agent/models/core.tsp b/specs/signalwire-rest/fabric-api/ai-agent/models/core.tsp index 68a43c8dd3..59ad7be7eb 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,114 @@ 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 { + // 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} + + 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; + */ + + @doc(""" + ${SWML.Calling.aiHintsDescription} + + See [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). + """) + @example(#["pizza", "pepperoni"]) + // TODO(https://github.com/signalwire/cloud-product/issues/20539): Restore + // `(string | TypeSpec.Record)[]` when structured hints are accepted. + hints?: string[]; + + @doc(""" + ${SWML.Calling.aiLanguagesDescription} + + 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[]; + + // 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} + + See [`ai.multilingual` in the SWML reference](/docs/swml/reference/calling/ai#aimultilingual). + """) + @example(#{ + languages: #[ + #{ language: "en", voice: "rime.spore" }, + #{ language: "es", voice: "elevenlabs.rachel:eleven_flash_v2_5" } + ], + allowed: #["en", "es"], + }) + multilingual?: TypeSpec.Record; + */ + + @doc(""" + ${SWML.Calling.aiParamsDescription} + + 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; + + @doc(""" + ${SWML.Calling.aiPostPromptDescription} + + 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.", + }) + 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} + + 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; + */ + + @doc(""" + ${SWML.Calling.aiPronounceDescription} + + 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[]; + + @doc(""" + ${SWML.Calling.aiPromptDescription} + + 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; + + @doc(""" + ${SWML.Calling.aiSwaigDescription} + + See [`ai.SWAIG` in the SWML reference](/docs/swml/reference/calling/ai#aiswaig). + """) + @example(#{ native_functions: #["check_time"] }) + 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/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; } 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/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/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/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/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 d6f09de1e5..ba4a22a860 100644 --- a/specs/signalwire-rest/fabric-api/swml-scripts/main.tsp +++ b/specs/signalwire-rest/fabric-api/swml-scripts/main.tsp @@ -7,12 +7,41 @@ import "./models/errors.tsp"; import "./addresses"; import "../../types"; import "../tags.tsp"; +import "../_shared/examples.tsp"; import "../../../_shared/alias/token-permissions.tsp"; 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: 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") namespace SignalWireAPI.Fabric.SwmlScripts { @tag(SWML_SCRIPTS_TAG) @@ -25,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 @@ -38,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; @@ -54,6 +116,20 @@ 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.", + } + ) + @opExample( + CreateMessagingSwmlScriptExample, + #{ + title: "Simple messaging script", + description: "Create a Messaging SWML Script that sends a single reply.", + } + ) @post create(@body request: SwmlScriptCreateRequest): | { @@ -72,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): | { 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..730a4a413f --- /dev/null +++ b/specs/signalwire-rest/swml-document.tsp @@ -0,0 +1,25 @@ +import "../swml/calling"; +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, +} 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; }