Calling api command updates

api/signalwire-rest/calling-api/calls/main.tsp

@@ -2,6 +2,7 @@ import "@typespec/http";
 import "../../types";
 import "./models/requests.tsp";
 import "./models/responses.tsp";
+import "./models/examples.tsp";
 
 
 using TypeSpec.Http;
@@ -15,17 +16,21 @@ namespace CallingAPI.Calls {
     interface Calls {
 
         @summary("Create a Call")
-        @doc("To create a new Call, you send a `POST` request to the Call resource with a payload including a `dial` command and additional nested `params`.")
-        create(...CallCreateRequest):
+        @doc("To create a new call, you send a `POST` request to the Call resource with a payload including a `dial` command and additional nested `params`.")
+        create(@body request: CallCreateRequest):
         { @statusCode statusCode: 201; @body call: CallResponse; } |
         StatusCode401 |
         StatusCode404 |
         CallCreate422Error;
 
 
         @summary("Update a Call")
-        @doc("To update an existing Call, you send a `PUT` request to the Call resource with a payload including an `update` command and additional nested `params`.")
-        @put update(...CallUpdateRequest):
+        @doc("To update an existing call, you send a `PUT` request to the Call resource with a payload including a `command` and additional nested `params`.")
+        @opExample(#{parameters: holdCallExample}, #{title: "Hold active call", description: "Put an active AI call on hold, pausing the conversation"})
+        @opExample(#{parameters: unholdCallExample}, #{title: "Unhold active call", description: "Resume an AI call that was previously put on hold"})
+        @opExample(#{parameters: aiMessageExample}, #{title: "Inject AI message", description: "Send a message to the AI conversation to modify behavior or add context"})
+        //@opExample(#{parameters: #{request: #{command: "update", params: #{id: "3fa85f64-5717-4562-b3fc-2c963f66afa6", url: "https://example.com/swml", fallback_url: "https://example.com/fallback"}}}}, #{title: "Update active call", description: "Modify an active call's behavior using new SWML instructions"})
+        @put update(@body request: CallUpdateRequest):
         { @statusCode statusCode: 200; @body call: CallResponse; } |
         StatusCode401 |
         StatusCode404 |
@@ -35,4 +40,4 @@ namespace CallingAPI.Calls {
 
 
 
-}
+}

api/signalwire-rest/calling-api/calls/models/examples.tsp

@@ -0,0 +1,56 @@
+/**
+ * Operation examples for the Calling API
+ * 
+ * These examples can be imported and used with @opExample decorator on operations
+ */
+
+const callId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
+
+// Hangup Call Examples
+const hangupCallExample = #{
+  request: #{
+    id: callId,
+    command: "calling.end",
+    params: #{
+      reason: "hangup"
+    }
+  }
+};
+
+const holdCallExample = #{
+  request: #{
+    id: callId,
+    command: "calling.ai_hold",
+    params: #{}
+  }
+};
+
+const unholdCallExample = #{
+  request: #{
+    id: callId,
+    command: "calling.ai_unhold", 
+    params: #{}
+  }
+};
+
+const aiMessageExample = #{
+  request: #{
+    id: callId,
+    command: "calling.ai_message",
+    params: #{
+      role: "system",
+      message_text: "You are now in expert mode. Provide detailed technical responses and use industry terminology."
+    }
+  }
+};
+
+const updateCallExample = #{
+  request: #{
+    command: "update",
+    params: #{
+      id: callId,
+      url: "https://example.com/swml",
+      fallback_url: "https://example.com/fallback"
+    }
+  }
+};

api/signalwire-rest/calling-api/calls/models/requests.tsp

@@ -1,6 +1,7 @@
 import "@typespec/http";
 import "@typespec/openapi3";
 
+
 using TypeSpec.Http;
 using TypeSpec.OpenAPI;
 
@@ -14,11 +15,100 @@ const CallSWMLURLExample = "https://example.com/swml";
 
 const CallIdExample = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
 
+const updateCommandDescription = "The `update` command is used to update a existing call with a new dialplan.";
+
+const uuidDescription = "The unique identifying ID of a existing call.";
+
+const paramsDescription = "An object of parameters to that will be utilized by the active command.";
+
 alias CallCreateRequestAlias = CallCreateParamsURL | CallCreateParamsSWML;
 
 
+@summary("Hangup call")
+model CallHangupRequest {
+    @doc(uuidDescription)
+    @example(CallIdExample)
+    id: uuid;
+
+    @doc("The `calling.end` command is used to hang up a call.")
+    @example("calling.end")
+    command: "calling.end";
+
+    @doc(paramsDescription)
+    params: {
+        @doc("Set the reason why the call was hung up.")
+        @example("hangup")
+        reason?: "hangup" | "busy"
+    };
+}
+@summary("Hold call")
+model CallHoldRequest {
+    @doc(uuidDescription)
+    @example(CallIdExample)
+    id: uuid;
+
+    @doc("The `calling.ai_hold` command is used to hold a call.")
+    @example("calling.ai_hold")
+    command: "calling.ai_hold";
+
+    @doc(paramsDescription)
+    params: {}
+}
+
+@summary("Unhold call")
+model CallUnholdRequest {
+    @doc(uuidDescription)
+    @example(CallIdExample)
+    id: uuid;
+
+    @doc("The `calling.ai_unhold` command is used to unhold a call.")
+    @example("calling.ai_unhold")
+    command: "calling.ai_unhold";
+
+    @doc(paramsDescription)
+    params: {};
+}
+
+@summary("Inject AI message")
+model CallAIMessageRequest {
+    @doc(uuidDescription)
+    @example(CallIdExample)
+    id: uuid;
+
+    @doc("The `calling.ai_message` command is used to inject a message into the AI conversation.")
+    @example("calling.ai_message")
+    command: "calling.ai_message";
+
+    @doc(paramsDescription)
+    params: {
+        @doc("""
+        The role that the message is from. Each role type has a different purpose and will influence how the AI will interpret the message.
+        - `system`: Inject instructions or context that modify the AI's behavior mid-conversation without the caller hearing it. This could change the AI's personality, add new constraints, provide context about the conversation, or give the AI information it should know going forward.
+        - `user`: Inject a message as if the caller said it. This would appear in the conversation history as coming from the caller, and the AI would respond to it as if the caller just spoke it.
+        - `assistant`: Inject a message as if the AI said it. This would appear as an AI response in the conversation history. The AI would treat this as its own previous response when generating future replies.
+        """)
+        @example("system")
+        role: "system" | "user" | "assistant",
+
+
+        @doc("""
+        The text content that will be sent to the AI.
+        """)
+        @example("You are now in expert mode. Provide detailed technical responses.")
+        message_text: string
+    }
+}
+
+
+
+@summary("Create call")
 model CallCreateRequest {
+    @doc("The `dial` command is used to create a new call.")
+    @example("dial")
     command: "dial";
+
+
+    @doc(paramsDescription)
     params: CallCreateRequestAlias;
 }
 
@@ -42,7 +132,7 @@ model CallCreateParamsBase {
 
 }
 
-@summary("Create a call with a URL")
+@summary("Create call (URL)")
 model CallCreateParamsURL is CallCreateParamsBase {
 
     @doc("""
@@ -54,17 +144,18 @@ model CallCreateParamsURL is CallCreateParamsBase {
 
 }
 
-@summary("Create a call with SWML") 
+@summary("Create call (SWML)") 
 model CallCreateParamsSWML is CallCreateParamsBase {
 
     @doc("Inline SWML, passed as a string, containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call.")
     @example(CallSWMLExample)
     swml: string;
 }
 
+@summary("Update call")
 model CallUpdateParamsBase {
 
-    @doc("The id of an existing call.")
+    @doc(uuidDescription)
     @example(CallIdExample)
     id: string;
 
@@ -82,15 +173,15 @@ model CallUpdateParamsBase {
 }
 
 
-@summary("Update a call with SWML") 
+@summary("Update call (SWML)") 
 model CallUpdateParamsSWML is CallUpdateParamsBase {
 
     @doc("Inline SWML, passed as a string, containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call.")
     @example(CallSWMLExample)
     swml: string;
 }
 
-@summary("Update a call with a URL")
+@summary("Update call (URL)")
 model CallUpdateParamsURL is CallUpdateParamsBase {
 
     @doc("""
@@ -102,10 +193,40 @@ model CallUpdateParamsURL is CallUpdateParamsBase {
 
 }
 
-model CallUpdateRequest {
+@summary("Update call")
+@oneOf
+union UpdateCurrentCallRequest {
+    CallUpdateSWMLRequest;
+    CallUpdateURLRequest;
+}
+
+union CallUpdateRequest {
+    UpdateCurrentCallRequest;
+    CallHangupRequest;
+    CallHoldRequest;
+    CallUnholdRequest;
+    CallAIMessageRequest;
+}
+
+
+model CallUpdateRequestBase {
+    @doc(updateCommandDescription)
+    @example("update")
     command: "update";
-    @oneOf
-    params: CallUpdateParamsURL | CallUpdateParamsSWML;
+}
+
+@summary("Update call (SWML)")
+model CallUpdateSWMLRequest is CallUpdateRequestBase {
+
+    @doc(paramsDescription)
+    params: CallUpdateParamsSWML;
+}
+
+@summary("Update call (URL)")
+model CallUpdateURLRequest is CallUpdateRequestBase {
+
+    @doc(paramsDescription)
+    params: CallUpdateParamsURL;
 }