Skip to content

Commit 574d371

Browse files
Devon-WhiteDevon-White
authored
Calling api command updates (#343)
* Calling api command updates * Push calling api updates * calling api changes * calling api changes
1 parent d8a5d97 commit 574d371

File tree

5 files changed

+392
-42
lines changed

5 files changed

+392
-42
lines changed

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

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import "@typespec/http";
22
import "../../types";
33
import "./models/requests.tsp";
44
import "./models/responses.tsp";
5+
import "./models/examples.tsp";
56

67

78
using TypeSpec.Http;
@@ -15,17 +16,21 @@ namespace CallingAPI.Calls {
1516
interface Calls {
1617

1718
@summary("Create a Call")
18-
@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`.")
19-
create(...CallCreateRequest):
19+
@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`.")
20+
create(@body request: CallCreateRequest):
2021
{ @statusCode statusCode: 201; @body call: CallResponse; } |
2122
StatusCode401 |
2223
StatusCode404 |
2324
CallCreate422Error;
2425

2526

2627
@summary("Update a Call")
27-
@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`.")
28-
@put update(...CallUpdateRequest):
28+
@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`.")
29+
@opExample(#{parameters: holdCallExample}, #{title: "Hold active call", description: "Put an active AI call on hold, pausing the conversation"})
30+
@opExample(#{parameters: unholdCallExample}, #{title: "Unhold active call", description: "Resume an AI call that was previously put on hold"})
31+
@opExample(#{parameters: aiMessageExample}, #{title: "Inject AI message", description: "Send a message to the AI conversation to modify behavior or add context"})
32+
//@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"})
33+
@put update(@body request: CallUpdateRequest):
2934
{ @statusCode statusCode: 200; @body call: CallResponse; } |
3035
StatusCode401 |
3136
StatusCode404 |
@@ -35,4 +40,4 @@ namespace CallingAPI.Calls {
3540

3641

3742

38-
}
43+
}

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

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
/**
2+
* Operation examples for the Calling API
3+
*
4+
* These examples can be imported and used with @opExample decorator on operations
5+
*/
6+
7+
const callId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
8+
9+
// Hangup Call Examples
10+
const hangupCallExample = #{
11+
request: #{
12+
id: callId,
13+
command: "calling.end",
14+
params: #{
15+
reason: "hangup"
16+
}
17+
}
18+
};
19+
20+
const holdCallExample = #{
21+
request: #{
22+
id: callId,
23+
command: "calling.ai_hold",
24+
params: #{}
25+
}
26+
};
27+
28+
const unholdCallExample = #{
29+
request: #{
30+
id: callId,
31+
command: "calling.ai_unhold",
32+
params: #{}
33+
}
34+
};
35+
36+
const aiMessageExample = #{
37+
request: #{
38+
id: callId,
39+
command: "calling.ai_message",
40+
params: #{
41+
role: "system",
42+
message_text: "You are now in expert mode. Provide detailed technical responses and use industry terminology."
43+
}
44+
}
45+
};
46+
47+
const updateCallExample = #{
48+
request: #{
49+
command: "update",
50+
params: #{
51+
id: callId,
52+
url: "https://example.com/swml",
53+
fallback_url: "https://example.com/fallback"
54+
}
55+
}
56+
};

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

Lines changed: 129 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import "@typespec/http";
22
import "@typespec/openapi3";
33

4+
45
using TypeSpec.Http;
56
using TypeSpec.OpenAPI;
67

@@ -14,11 +15,100 @@ const CallSWMLURLExample = "https://example.com/swml";
1415

1516
const CallIdExample = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
1617

18+
const updateCommandDescription = "The `update` command is used to update a existing call with a new dialplan.";
19+
20+
const uuidDescription = "The unique identifying ID of a existing call.";
21+
22+
const paramsDescription = "An object of parameters to that will be utilized by the active command.";
23+
1724
alias CallCreateRequestAlias = CallCreateParamsURL | CallCreateParamsSWML;
1825

1926

27+
@summary("Hangup call")
28+
model CallHangupRequest {
29+
@doc(uuidDescription)
30+
@example(CallIdExample)
31+
id: uuid;
32+
33+
@doc("The `calling.end` command is used to hang up a call.")
34+
@example("calling.end")
35+
command: "calling.end";
36+
37+
@doc(paramsDescription)
38+
params: {
39+
@doc("Set the reason why the call was hung up.")
40+
@example("hangup")
41+
reason?: "hangup" | "busy"
42+
};
43+
}
44+
@summary("Hold call")
45+
model CallHoldRequest {
46+
@doc(uuidDescription)
47+
@example(CallIdExample)
48+
id: uuid;
49+
50+
@doc("The `calling.ai_hold` command is used to hold a call.")
51+
@example("calling.ai_hold")
52+
command: "calling.ai_hold";
53+
54+
@doc(paramsDescription)
55+
params: {}
56+
}
57+
58+
@summary("Unhold call")
59+
model CallUnholdRequest {
60+
@doc(uuidDescription)
61+
@example(CallIdExample)
62+
id: uuid;
63+
64+
@doc("The `calling.ai_unhold` command is used to unhold a call.")
65+
@example("calling.ai_unhold")
66+
command: "calling.ai_unhold";
67+
68+
@doc(paramsDescription)
69+
params: {};
70+
}
71+
72+
@summary("Inject AI message")
73+
model CallAIMessageRequest {
74+
@doc(uuidDescription)
75+
@example(CallIdExample)
76+
id: uuid;
77+
78+
@doc("The `calling.ai_message` command is used to inject a message into the AI conversation.")
79+
@example("calling.ai_message")
80+
command: "calling.ai_message";
81+
82+
@doc(paramsDescription)
83+
params: {
84+
@doc("""
85+
The role that the message is from. Each role type has a different purpose and will influence how the AI will interpret the message.
86+
- `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.
87+
- `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.
88+
- `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.
89+
""")
90+
@example("system")
91+
role: "system" | "user" | "assistant",
92+
93+
94+
@doc("""
95+
The text content that will be sent to the AI.
96+
""")
97+
@example("You are now in expert mode. Provide detailed technical responses.")
98+
message_text: string
99+
}
100+
}
101+
102+
103+
104+
@summary("Create call")
20105
model CallCreateRequest {
106+
@doc("The `dial` command is used to create a new call.")
107+
@example("dial")
21108
command: "dial";
109+
110+
111+
@doc(paramsDescription)
22112
params: CallCreateRequestAlias;
23113
}
24114

@@ -42,7 +132,7 @@ model CallCreateParamsBase {
42132

43133
}
44134

45-
@summary("Create a call with a URL")
135+
@summary("Create call (URL)")
46136
model CallCreateParamsURL is CallCreateParamsBase {
47137

48138
@doc("""
@@ -54,17 +144,18 @@ model CallCreateParamsURL is CallCreateParamsBase {
54144

55145
}
56146

57-
@summary("Create a call with SWML")
147+
@summary("Create call (SWML)")
58148
model CallCreateParamsSWML is CallCreateParamsBase {
59149

60150
@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.")
61151
@example(CallSWMLExample)
62152
swml: string;
63153
}
64154

155+
@summary("Update call")
65156
model CallUpdateParamsBase {
66157

67-
@doc("The id of an existing call.")
158+
@doc(uuidDescription)
68159
@example(CallIdExample)
69160
id: string;
70161

@@ -82,15 +173,15 @@ model CallUpdateParamsBase {
82173
}
83174

84175

85-
@summary("Update a call with SWML")
176+
@summary("Update call (SWML)")
86177
model CallUpdateParamsSWML is CallUpdateParamsBase {
87178

88179
@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.")
89180
@example(CallSWMLExample)
90181
swml: string;
91182
}
92183

93-
@summary("Update a call with a URL")
184+
@summary("Update call (URL)")
94185
model CallUpdateParamsURL is CallUpdateParamsBase {
95186

96187
@doc("""
@@ -102,10 +193,40 @@ model CallUpdateParamsURL is CallUpdateParamsBase {
102193

103194
}
104195

105-
model CallUpdateRequest {
196+
@summary("Update call")
197+
@oneOf
198+
union UpdateCurrentCallRequest {
199+
CallUpdateSWMLRequest;
200+
CallUpdateURLRequest;
201+
}
202+
203+
union CallUpdateRequest {
204+
UpdateCurrentCallRequest;
205+
CallHangupRequest;
206+
CallHoldRequest;
207+
CallUnholdRequest;
208+
CallAIMessageRequest;
209+
}
210+
211+
212+
model CallUpdateRequestBase {
213+
@doc(updateCommandDescription)
214+
@example("update")
106215
command: "update";
107-
@oneOf
108-
params: CallUpdateParamsURL | CallUpdateParamsSWML;
216+
}
217+
218+
@summary("Update call (SWML)")
219+
model CallUpdateSWMLRequest is CallUpdateRequestBase {
220+
221+
@doc(paramsDescription)
222+
params: CallUpdateParamsSWML;
223+
}
224+
225+
@summary("Update call (URL)")
226+
model CallUpdateURLRequest is CallUpdateRequestBase {
227+
228+
@doc(paramsDescription)
229+
params: CallUpdateParamsURL;
109230
}
110231

111232

0 commit comments

Comments
 (0)