diff --git a/specs/package.json b/specs/package.json index 56935c197..3e3d8b7f9 100644 --- a/specs/package.json +++ b/specs/package.json @@ -5,10 +5,11 @@ "scripts": { "build": "yarn build:api", "build:all": "yarn build:api && yarn build:schema", - "build:api": "yarn build:calling-api && yarn build:chat-api && yarn build:datasphere-api && yarn build:fabric-api && yarn build:logs-api && yarn build:fax-api && yarn build:message-api && yarn build:voice-api && yarn build:pubsub-api", + "build:api": "yarn build:calling-api && yarn build:calling-api-docs && yarn build:chat-api && yarn build:datasphere-api && yarn build:fabric-api && yarn build:logs-api && yarn build:fax-api && yarn build:message-api && yarn build:voice-api && yarn build:pubsub-api", "build:schema": "yarn build:swml", "build:swml": "cd ./swml && tsp compile . && cd ../", "build:calling-api": "cd ./signalwire-rest/calling-api && tsp compile . && cd ../../", + "build:calling-api-docs": "cd ./signalwire-rest/calling-api/open-rpc/dial && tsp compile . && cd ../../../../ && cd ./signalwire-rest/calling-api/open-rpc/update && tsp compile . && cd ../../../../ && cd ./signalwire-rest/calling-api/open-rpc/calling-end && tsp compile . && cd ../../../../ && cd ./signalwire-rest/calling-api/open-rpc/calling-ai-hold && tsp compile . && cd ../../../../ && cd ./signalwire-rest/calling-api/open-rpc/calling-ai-unhold && tsp compile . && cd ../../../../ && cd ./signalwire-rest/calling-api/open-rpc/calling-ai-message && tsp compile . && cd ../../../../", "build:chat-api": "cd ./signalwire-rest/chat-api && tsp compile . && cd ../../", "build:datasphere-api": "cd ./signalwire-rest/datasphere-api && tsp compile . && cd ../../", "build:fabric-api": "cd ./signalwire-rest/fabric-api && tsp compile . && cd ../../", diff --git a/specs/signalwire-rest/calling-api/calls/models/requests.tsp b/specs/signalwire-rest/calling-api/calls/models/requests.tsp index 129119750..a861576ee 100644 --- a/specs/signalwire-rest/calling-api/calls/models/requests.tsp +++ b/specs/signalwire-rest/calling-api/calls/models/requests.tsp @@ -18,7 +18,9 @@ const uuidDescription = "The unique identifying ID of a existing call."; const paramsDescription = "An object of parameters that will be utilized by the active command."; -alias CallCreateRequestAlias = CallCreateParamsURL | CallCreateParamsSWML; +alias CallCreateParamsAlias = CallCreateParamsURL | CallCreateParamsSWML; + +alias CallUpdateParamsAlias = CallUpdateParamsURL | CallUpdateParamsSWML; @summary("Hangup call") model CallHangupRequest { @@ -101,7 +103,7 @@ model CallCreateRequest { command: "dial"; @doc(paramsDescription) - params: CallCreateRequestAlias; + params: CallCreateParamsAlias; } model CallCreateParamsBase { @@ -189,34 +191,19 @@ model CallUpdateParamsURL is CallUpdateParamsBase { } @summary("Update call") -@oneOf -union UpdateCurrentCallRequest { - CallUpdateSWMLRequest, - CallUpdateURLRequest, -} - -union CallUpdateRequest { - UpdateCurrentCallRequest, - CallHangupRequest, - CallHoldRequest, - CallUnholdRequest, - CallAIMessageRequest, -} - -model CallUpdateRequestBase { +model CallUpdateCurrentCallRequest { @doc(updateCommandDescription) @example("update") command: "update"; -} -@summary("Update call (SWML)") -model CallUpdateSWMLRequest is CallUpdateRequestBase { @doc(paramsDescription) - params: CallUpdateParamsSWML; + params: CallUpdateParamsAlias; } -@summary("Update call (URL)") -model CallUpdateURLRequest is CallUpdateRequestBase { - @doc(paramsDescription) - params: CallUpdateParamsURL; +union CallUpdateRequest { + CallUpdateCurrentCallRequest, + CallHangupRequest, + CallHoldRequest, + CallUnholdRequest, + CallAIMessageRequest, } diff --git a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/main.tsp b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/main.tsp new file mode 100644 index 000000000..c7e628134 --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/main.tsp @@ -0,0 +1,55 @@ +import "@typespec/http"; +import "@typespec/openapi"; +import "../../../types"; +import "../../calls/models/requests.tsp"; +import "../../calls/models/responses.tsp"; +import "../../../_globally_shared/const.tsp"; +import "../../tags.tsp"; + +using TypeSpec.Http; +using TypeSpec.OpenAPI; +using Types.StatusCodes; + +@tagMetadata(CALLS_TAG, CALLS_TAG_METADATA) +@externalDocs( + "https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/calling-ai-hold", + "Documentation for the calling.ai_hold command to hold AI calls." +) +@info(#{ + title: "Calling API - Calling AI Hold", + version: "1.0.0", + contact: CONTACT_INFO, + license: LICENSE_INFO, + termsOfService: TERMS_OF_SERVICE, +}) +@service(#{ title: "Calling API - Calling AI Hold" }) +@server( + "https://{space_name}.${SERVER_URL}/calling", + "Endpoint", + { + @doc(SERVER_URL_DESCRIPTION) + @example("example") + space_name: string = "{Your_Space_Name}", + } +) +@useAuth(BasicAuth) +@doc("API to hold AI SignalWire calls using the calling.ai_hold command.") +namespace CallingAPI.AIHold; + +@route("/calls") +@tag("Calls") +interface AIHoldCommand { + @summary("Hold an AI Call") + @doc("To hold an existing AI call, you send a `POST` request to the Call resource with a payload including a `calling.ai_hold` command and the call ID. This pauses the AI conversation.") + @operationId("hold-ai") + @post + hold(@body request: CallHoldRequest): + | { + @statusCode statusCode: 200; + @body call: CallResponse; + } + | StatusCode401 + | StatusCode404 + | CallUpdate422Error + | StatusCode500; +} diff --git a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/tsp-output/@typespec/openapi3/openapi.yaml b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/tsp-output/@typespec/openapi3/openapi.yaml new file mode 100644 index 000000000..fae20806c --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/tsp-output/@typespec/openapi3/openapi.yaml @@ -0,0 +1,292 @@ +openapi: 3.0.0 +info: + title: Calling API - Calling AI Hold + version: 1.0.0 + contact: + name: SignalWire + url: https://support.signalwire.com/portal/en/newticket?departmentId=1029313000000006907&layoutId=1029313000000074011 + email: support@signalwire.com + license: + name: MIT + url: https://github.com/signalwire/docs/blob/main/LICENSE + termsOfService: https://signalwire.com/legal/signalwire-cloud-agreement + description: API to hold AI SignalWire calls using the calling.ai_hold command. +externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/calling-ai-hold + description: Documentation for the calling.ai_hold command to hold AI calls. +tags: + - name: Calls + description: Endpoints related to creating and managing calls + externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls + description: Developer documentation on Calling API Call endpoints +paths: + /calls: + post: + operationId: hold-ai + summary: Hold an AI Call + description: To hold an existing AI call, you send a `POST` request to the Call resource with a payload including a `calling.ai_hold` command and the call ID. This pauses the AI conversation. + parameters: [] + responses: + '200': + description: The request has succeeded. + content: + application/json: + schema: + $ref: '#/components/schemas/CallResponse' + '401': + description: Access is unauthorized. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' + '404': + description: The server cannot find the requested resource. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode404' + '422': + description: Client error + content: + application/json: + schema: + $ref: '#/components/schemas/CallUpdate422Error' + '500': + description: Server error + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' + tags: + - Calls + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CallHoldRequest' +security: + - BasicAuth: [] +components: + schemas: + CallHoldRequest: + type: object + required: + - id + - command + - params + properties: + id: + allOf: + - $ref: '#/components/schemas/uuid' + description: The unique identifying ID of a existing call. + example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + command: + type: string + enum: + - calling.ai_hold + description: The `calling.ai_hold` command is used to hold a call. + example: calling.ai_hold + params: + type: object + description: An object of parameters that will be utilized by the active command. + title: Hold call + CallResponse: + type: object + required: + - id + - from + - to + - direction + - status + - duration + - duration_ms + - billing_ms + - source + - type + - url + - charge + - created_at + - parent_id + - charge_details + properties: + id: + type: string + description: The unique identifier of the call on SignalWire. This can be used to update the call programmatically. + example: 0e9c80d7-a149-4917-892d-420043709f45 + from: + type: string + description: The origin number or address. + example: '+12069708643' + to: + type: string + description: The destination number or address. + example: '+18048390497' + direction: + type: string + enum: + - outbound-api + description: The direction of the call. + example: outbound-api + status: + type: string + enum: + - answered + - queued + - initiated + - ringing + - ending + - ended + description: The status of the call. + example: queued + duration: + type: integer + nullable: true + description: The duration of the call in seconds. + example: null + duration_ms: + type: integer + nullable: true + description: The duration of the call in milliseconds. + example: null + billing_ms: + type: integer + nullable: true + description: The billable duration of the call in milliseconds. + example: null + source: + type: string + enum: + - realtime_api + description: Source of this call. + example: realtime_api + type: + type: string + enum: + - relay_pstn_call + - relay_sip_call + - relay_webrtc_call + description: Type of this call. + example: relay_pstn_call + url: + type: string + nullable: true + description: The URL associated with this call. + example: null + charge: + type: number + format: double + description: Total charge for this call. + example: 0 + created_at: + type: string + format: date-time + description: The date and time when the call was created. + example: '2024-05-06T12:20:00Z' + parent_id: + type: string + nullable: true + description: The parent call ID if this is a child call. + example: null + charge_details: + type: array + items: + $ref: '#/components/schemas/ChargeDetails' + description: Details on charges associated with this call. + CallUpdate422Error: + type: object + required: + - errors + properties: + errors: + type: array + items: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode422Error' + example: + errors: + - type: validation_error + code: missing_required_parameter + message: url must be a valid http or https url + attribute: url + url: https://developer.signalwire.com/rest/signalwire-rest/overview/error-codes#http_url_required + ChargeDetails: + type: object + required: + - description + - amount + properties: + description: + type: string + description: Description for this charge. + example: Text to Speech + amount: + type: number + description: Charged amount. + example: 0.121176 + Types.StatusCodes.StatusCode401: + type: object + required: + - error + properties: + error: + type: string + enum: + - Unauthorized + Types.StatusCodes.StatusCode404: + type: object + required: + - error + properties: + error: + type: string + enum: + - Not Found + Types.StatusCodes.StatusCode422Error: + type: object + required: + - type + - code + - message + - attribute + - url + properties: + type: + type: string + description: Error type. + code: + type: string + description: Error code. + message: + type: string + description: Error details. + attribute: + type: string + description: Request parameter associated with this error. + url: + type: string + description: Link to developer resource for this error. + Types.StatusCodes.StatusCode500: + type: object + required: + - error + properties: + error: + type: string + enum: + - Internal Server Error + uuid: + type: string + format: uuid + description: Universal Unique Identifier. + securitySchemes: + BasicAuth: + type: http + scheme: Basic +servers: + - url: https://{space_name}.signalwire.com/api/calling + description: Endpoint + variables: + space_name: + default: '{Your_Space_Name}' + description: The domain of the users SignalWire space. diff --git a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/main.tsp b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/main.tsp new file mode 100644 index 000000000..23264790d --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/main.tsp @@ -0,0 +1,55 @@ +import "@typespec/http"; +import "@typespec/openapi"; +import "../../../types"; +import "../../calls/models/requests.tsp"; +import "../../calls/models/responses.tsp"; +import "../../../_globally_shared/const.tsp"; +import "../../tags.tsp"; + +using TypeSpec.Http; +using TypeSpec.OpenAPI; +using Types.StatusCodes; + +@tagMetadata(CALLS_TAG, CALLS_TAG_METADATA) +@externalDocs( + "https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/calling-ai-message", + "Documentation for the calling.ai_message command to inject messages into AI conversations." +) +@info(#{ + title: "Calling API - Inject AI Message", + version: "1.0.0", + contact: CONTACT_INFO, + license: LICENSE_INFO, + termsOfService: TERMS_OF_SERVICE, +}) +@service(#{ title: "Calling API - Calling Inject AI Message" }) +@server( + "https://{space_name}.${SERVER_URL}/calling", + "Endpoint", + { + @doc(SERVER_URL_DESCRIPTION) + @example("example") + space_name: string = "{Your_Space_Name}", + } +) +@useAuth(BasicAuth) +@doc("API to inject messages into AI SignalWire call conversations using the calling.ai_message command.") +namespace CallingAPI.AIMessage; + +@route("/calls") +@tag("Calls") +interface CallingAIMessageCommand { + @summary("Inject AI Message") + @doc("To inject a message into an existing AI call conversation, you send a `POST` request to the Call resource with a payload including a `calling.ai_message` command, the call ID, and message details. Messages can be injected as system instructions, user messages, or assistant responses.") + @operationId("inject-ai-message") + @post + message(@body request: CallAIMessageRequest): + | { + @statusCode statusCode: 200; + @body call: CallResponse; + } + | StatusCode401 + | StatusCode404 + | CallUpdate422Error + | StatusCode500; +} diff --git a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/tsp-output/@typespec/openapi3/openapi.yaml b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/tsp-output/@typespec/openapi3/openapi.yaml new file mode 100644 index 000000000..79390a2e1 --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/tsp-output/@typespec/openapi3/openapi.yaml @@ -0,0 +1,312 @@ +openapi: 3.0.0 +info: + title: Calling API - Inject AI Message + version: 1.0.0 + contact: + name: SignalWire + url: https://support.signalwire.com/portal/en/newticket?departmentId=1029313000000006907&layoutId=1029313000000074011 + email: support@signalwire.com + license: + name: MIT + url: https://github.com/signalwire/docs/blob/main/LICENSE + termsOfService: https://signalwire.com/legal/signalwire-cloud-agreement + description: API to inject messages into AI SignalWire call conversations using the calling.ai_message command. +externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/calling-ai-message + description: Documentation for the calling.ai_message command to inject messages into AI conversations. +tags: + - name: Calls + description: Endpoints related to creating and managing calls + externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls + description: Developer documentation on Calling API Call endpoints +paths: + /calls: + post: + operationId: inject-ai-message + summary: Inject AI Message + description: To inject a message into an existing AI call conversation, you send a `POST` request to the Call resource with a payload including a `calling.ai_message` command, the call ID, and message details. Messages can be injected as system instructions, user messages, or assistant responses. + parameters: [] + responses: + '200': + description: The request has succeeded. + content: + application/json: + schema: + $ref: '#/components/schemas/CallResponse' + '401': + description: Access is unauthorized. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' + '404': + description: The server cannot find the requested resource. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode404' + '422': + description: Client error + content: + application/json: + schema: + $ref: '#/components/schemas/CallUpdate422Error' + '500': + description: Server error + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' + tags: + - Calls + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CallAIMessageRequest' +security: + - BasicAuth: [] +components: + schemas: + CallAIMessageRequest: + type: object + required: + - id + - command + - params + properties: + id: + allOf: + - $ref: '#/components/schemas/uuid' + description: The unique identifying ID of a existing call. + example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + command: + type: string + enum: + - calling.ai_message + description: The `calling.ai_message` command is used to inject a message into the AI conversation. + example: calling.ai_message + params: + type: object + properties: + role: + type: string + enum: + - system + - user + - assistant + description: |- + 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 + message_text: + type: string + description: The text content that will be sent to the AI. + example: You are now in expert mode. Provide detailed technical responses. + required: + - role + - message_text + description: An object of parameters that will be utilized by the active command. + title: Inject AI message + CallResponse: + type: object + required: + - id + - from + - to + - direction + - status + - duration + - duration_ms + - billing_ms + - source + - type + - url + - charge + - created_at + - parent_id + - charge_details + properties: + id: + type: string + description: The unique identifier of the call on SignalWire. This can be used to update the call programmatically. + example: 0e9c80d7-a149-4917-892d-420043709f45 + from: + type: string + description: The origin number or address. + example: '+12069708643' + to: + type: string + description: The destination number or address. + example: '+18048390497' + direction: + type: string + enum: + - outbound-api + description: The direction of the call. + example: outbound-api + status: + type: string + enum: + - answered + - queued + - initiated + - ringing + - ending + - ended + description: The status of the call. + example: queued + duration: + type: integer + nullable: true + description: The duration of the call in seconds. + example: null + duration_ms: + type: integer + nullable: true + description: The duration of the call in milliseconds. + example: null + billing_ms: + type: integer + nullable: true + description: The billable duration of the call in milliseconds. + example: null + source: + type: string + enum: + - realtime_api + description: Source of this call. + example: realtime_api + type: + type: string + enum: + - relay_pstn_call + - relay_sip_call + - relay_webrtc_call + description: Type of this call. + example: relay_pstn_call + url: + type: string + nullable: true + description: The URL associated with this call. + example: null + charge: + type: number + format: double + description: Total charge for this call. + example: 0 + created_at: + type: string + format: date-time + description: The date and time when the call was created. + example: '2024-05-06T12:20:00Z' + parent_id: + type: string + nullable: true + description: The parent call ID if this is a child call. + example: null + charge_details: + type: array + items: + $ref: '#/components/schemas/ChargeDetails' + description: Details on charges associated with this call. + CallUpdate422Error: + type: object + required: + - errors + properties: + errors: + type: array + items: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode422Error' + example: + errors: + - type: validation_error + code: missing_required_parameter + message: url must be a valid http or https url + attribute: url + url: https://developer.signalwire.com/rest/signalwire-rest/overview/error-codes#http_url_required + ChargeDetails: + type: object + required: + - description + - amount + properties: + description: + type: string + description: Description for this charge. + example: Text to Speech + amount: + type: number + description: Charged amount. + example: 0.121176 + Types.StatusCodes.StatusCode401: + type: object + required: + - error + properties: + error: + type: string + enum: + - Unauthorized + Types.StatusCodes.StatusCode404: + type: object + required: + - error + properties: + error: + type: string + enum: + - Not Found + Types.StatusCodes.StatusCode422Error: + type: object + required: + - type + - code + - message + - attribute + - url + properties: + type: + type: string + description: Error type. + code: + type: string + description: Error code. + message: + type: string + description: Error details. + attribute: + type: string + description: Request parameter associated with this error. + url: + type: string + description: Link to developer resource for this error. + Types.StatusCodes.StatusCode500: + type: object + required: + - error + properties: + error: + type: string + enum: + - Internal Server Error + uuid: + type: string + format: uuid + description: Universal Unique Identifier. + securitySchemes: + BasicAuth: + type: http + scheme: Basic +servers: + - url: https://{space_name}.signalwire.com/api/calling + description: Endpoint + variables: + space_name: + default: '{Your_Space_Name}' + description: The domain of the users SignalWire space. diff --git a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/main.tsp b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/main.tsp new file mode 100644 index 000000000..fbe047bb1 --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/main.tsp @@ -0,0 +1,55 @@ +import "@typespec/http"; +import "@typespec/openapi"; +import "../../../types"; +import "../../calls/models/requests.tsp"; +import "../../calls/models/responses.tsp"; +import "../../../_globally_shared/const.tsp"; +import "../../tags.tsp"; + +using TypeSpec.Http; +using TypeSpec.OpenAPI; +using Types.StatusCodes; + +@tagMetadata(CALLS_TAG, CALLS_TAG_METADATA) +@externalDocs( + "https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/calling-ai-unhold", + "Documentation for the calling.ai_unhold command to resume AI calls." +) +@info(#{ + title: "Calling API - Calling Unhold AI", + version: "1.0.0", + contact: CONTACT_INFO, + license: LICENSE_INFO, + termsOfService: TERMS_OF_SERVICE, +}) +@service(#{ title: "Calling API - Calling AI Unhold" }) +@server( + "https://{space_name}.${SERVER_URL}/calling", + "Endpoint", + { + @doc(SERVER_URL_DESCRIPTION) + @example("example") + space_name: string = "{Your_Space_Name}", + } +) +@useAuth(BasicAuth) +@doc("API to resume AI SignalWire calls using the calling.ai_unhold command.") +namespace CallingAPI.AIUnhold; + +@route("/calls") +@tag("Calls") +interface CallingAIUnholdCommand { + @summary("Unhold an AI Call") + @doc("To resume an existing AI call that was previously held, you send a `POST` request to the Call resource with a payload including a `calling.ai_unhold` command and the call ID. This resumes the AI conversation.") + @operationId("unhold-ai") + @post + unhold(@body request: CallUnholdRequest): + | { + @statusCode statusCode: 200; + @body call: CallResponse; + } + | StatusCode401 + | StatusCode404 + | CallUpdate422Error + | StatusCode500; +} diff --git a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/tsp-output/@typespec/openapi3/openapi.yaml b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/tsp-output/@typespec/openapi3/openapi.yaml new file mode 100644 index 000000000..9ad461063 --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/tsp-output/@typespec/openapi3/openapi.yaml @@ -0,0 +1,292 @@ +openapi: 3.0.0 +info: + title: Calling API - Calling Unhold AI + version: 1.0.0 + contact: + name: SignalWire + url: https://support.signalwire.com/portal/en/newticket?departmentId=1029313000000006907&layoutId=1029313000000074011 + email: support@signalwire.com + license: + name: MIT + url: https://github.com/signalwire/docs/blob/main/LICENSE + termsOfService: https://signalwire.com/legal/signalwire-cloud-agreement + description: API to resume AI SignalWire calls using the calling.ai_unhold command. +externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/calling-ai-unhold + description: Documentation for the calling.ai_unhold command to resume AI calls. +tags: + - name: Calls + description: Endpoints related to creating and managing calls + externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls + description: Developer documentation on Calling API Call endpoints +paths: + /calls: + post: + operationId: unhold-ai + summary: Unhold an AI Call + description: To resume an existing AI call that was previously held, you send a `POST` request to the Call resource with a payload including a `calling.ai_unhold` command and the call ID. This resumes the AI conversation. + parameters: [] + responses: + '200': + description: The request has succeeded. + content: + application/json: + schema: + $ref: '#/components/schemas/CallResponse' + '401': + description: Access is unauthorized. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' + '404': + description: The server cannot find the requested resource. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode404' + '422': + description: Client error + content: + application/json: + schema: + $ref: '#/components/schemas/CallUpdate422Error' + '500': + description: Server error + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' + tags: + - Calls + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CallUnholdRequest' +security: + - BasicAuth: [] +components: + schemas: + CallResponse: + type: object + required: + - id + - from + - to + - direction + - status + - duration + - duration_ms + - billing_ms + - source + - type + - url + - charge + - created_at + - parent_id + - charge_details + properties: + id: + type: string + description: The unique identifier of the call on SignalWire. This can be used to update the call programmatically. + example: 0e9c80d7-a149-4917-892d-420043709f45 + from: + type: string + description: The origin number or address. + example: '+12069708643' + to: + type: string + description: The destination number or address. + example: '+18048390497' + direction: + type: string + enum: + - outbound-api + description: The direction of the call. + example: outbound-api + status: + type: string + enum: + - answered + - queued + - initiated + - ringing + - ending + - ended + description: The status of the call. + example: queued + duration: + type: integer + nullable: true + description: The duration of the call in seconds. + example: null + duration_ms: + type: integer + nullable: true + description: The duration of the call in milliseconds. + example: null + billing_ms: + type: integer + nullable: true + description: The billable duration of the call in milliseconds. + example: null + source: + type: string + enum: + - realtime_api + description: Source of this call. + example: realtime_api + type: + type: string + enum: + - relay_pstn_call + - relay_sip_call + - relay_webrtc_call + description: Type of this call. + example: relay_pstn_call + url: + type: string + nullable: true + description: The URL associated with this call. + example: null + charge: + type: number + format: double + description: Total charge for this call. + example: 0 + created_at: + type: string + format: date-time + description: The date and time when the call was created. + example: '2024-05-06T12:20:00Z' + parent_id: + type: string + nullable: true + description: The parent call ID if this is a child call. + example: null + charge_details: + type: array + items: + $ref: '#/components/schemas/ChargeDetails' + description: Details on charges associated with this call. + CallUnholdRequest: + type: object + required: + - id + - command + - params + properties: + id: + allOf: + - $ref: '#/components/schemas/uuid' + description: The unique identifying ID of a existing call. + example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + command: + type: string + enum: + - calling.ai_unhold + description: The `calling.ai_unhold` command is used to unhold a call. + example: calling.ai_unhold + params: + type: object + description: An object of parameters that will be utilized by the active command. + title: Unhold call + CallUpdate422Error: + type: object + required: + - errors + properties: + errors: + type: array + items: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode422Error' + example: + errors: + - type: validation_error + code: missing_required_parameter + message: url must be a valid http or https url + attribute: url + url: https://developer.signalwire.com/rest/signalwire-rest/overview/error-codes#http_url_required + ChargeDetails: + type: object + required: + - description + - amount + properties: + description: + type: string + description: Description for this charge. + example: Text to Speech + amount: + type: number + description: Charged amount. + example: 0.121176 + Types.StatusCodes.StatusCode401: + type: object + required: + - error + properties: + error: + type: string + enum: + - Unauthorized + Types.StatusCodes.StatusCode404: + type: object + required: + - error + properties: + error: + type: string + enum: + - Not Found + Types.StatusCodes.StatusCode422Error: + type: object + required: + - type + - code + - message + - attribute + - url + properties: + type: + type: string + description: Error type. + code: + type: string + description: Error code. + message: + type: string + description: Error details. + attribute: + type: string + description: Request parameter associated with this error. + url: + type: string + description: Link to developer resource for this error. + Types.StatusCodes.StatusCode500: + type: object + required: + - error + properties: + error: + type: string + enum: + - Internal Server Error + uuid: + type: string + format: uuid + description: Universal Unique Identifier. + securitySchemes: + BasicAuth: + type: http + scheme: Basic +servers: + - url: https://{space_name}.signalwire.com/api/calling + description: Endpoint + variables: + space_name: + default: '{Your_Space_Name}' + description: The domain of the users SignalWire space. diff --git a/specs/signalwire-rest/calling-api/open-rpc/calling-end/main.tsp b/specs/signalwire-rest/calling-api/open-rpc/calling-end/main.tsp new file mode 100644 index 000000000..d59011913 --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/calling-end/main.tsp @@ -0,0 +1,55 @@ +import "@typespec/http"; +import "@typespec/openapi"; +import "../../../types"; +import "../../calls/models/requests.tsp"; +import "../../calls/models/responses.tsp"; +import "../../../_globally_shared/const.tsp"; +import "../../tags.tsp"; + +using TypeSpec.Http; +using TypeSpec.OpenAPI; +using Types.StatusCodes; + +@tagMetadata(CALLS_TAG, CALLS_TAG_METADATA) +@externalDocs( + "https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/calling-end", + "Documentation for the calling.end command to hangup calls." +) +@info(#{ + title: "Calling API - Hangup Call", + version: "1.0.0", + contact: CONTACT_INFO, + license: LICENSE_INFO, + termsOfService: TERMS_OF_SERVICE, +}) +@service(#{ title: "Calling API - Hangup Call" }) +@server( + "https://{space_name}.${SERVER_URL}/calling", + "Endpoint", + { + @doc(SERVER_URL_DESCRIPTION) + @example("example") + space_name: string = "{Your_Space_Name}", + } +) +@useAuth(BasicAuth) +@doc("API to end/hangup SignalWire calls using the calling.end command.") +namespace CallingAPI.End; + +@route("/calls") +@tag("Calls") +interface CallingEndCommand { + @summary("Hangup a Call") + @doc("To hangup an existing call, you send a `POST` request to the Call resource with a payload including a `calling.end` command and the call ID.") + @operationId("hangup-call") + @post + end(@body request: CallHangupRequest): + | { + @statusCode statusCode: 200; + @body call: CallResponse; + } + | StatusCode401 + | StatusCode404 + | CallUpdate422Error + | StatusCode500; +} diff --git a/specs/signalwire-rest/calling-api/open-rpc/calling-end/tsp-output/@typespec/openapi3/openapi.yaml b/specs/signalwire-rest/calling-api/open-rpc/calling-end/tsp-output/@typespec/openapi3/openapi.yaml new file mode 100644 index 000000000..15b7e5029 --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/calling-end/tsp-output/@typespec/openapi3/openapi.yaml @@ -0,0 +1,300 @@ +openapi: 3.0.0 +info: + title: Calling API - Hangup Call + version: 1.0.0 + contact: + name: SignalWire + url: https://support.signalwire.com/portal/en/newticket?departmentId=1029313000000006907&layoutId=1029313000000074011 + email: support@signalwire.com + license: + name: MIT + url: https://github.com/signalwire/docs/blob/main/LICENSE + termsOfService: https://signalwire.com/legal/signalwire-cloud-agreement + description: API to end/hangup SignalWire calls using the calling.end command. +externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/calling-end + description: Documentation for the calling.end command to hangup calls. +tags: + - name: Calls + description: Endpoints related to creating and managing calls + externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls + description: Developer documentation on Calling API Call endpoints +paths: + /calls: + post: + operationId: hangup-call + summary: Hangup a Call + description: To hangup an existing call, you send a `POST` request to the Call resource with a payload including a `calling.end` command and the call ID. + parameters: [] + responses: + '200': + description: The request has succeeded. + content: + application/json: + schema: + $ref: '#/components/schemas/CallResponse' + '401': + description: Access is unauthorized. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' + '404': + description: The server cannot find the requested resource. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode404' + '422': + description: Client error + content: + application/json: + schema: + $ref: '#/components/schemas/CallUpdate422Error' + '500': + description: Server error + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' + tags: + - Calls + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CallHangupRequest' +security: + - BasicAuth: [] +components: + schemas: + CallHangupRequest: + type: object + required: + - id + - command + - params + properties: + id: + allOf: + - $ref: '#/components/schemas/uuid' + description: The unique identifying ID of a existing call. + example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + command: + type: string + enum: + - calling.end + description: The `calling.end` command is used to hang up a call. + example: calling.end + params: + type: object + properties: + reason: + type: string + enum: + - hangup + - busy + description: Set the reason why the call was hung up. + example: hangup + description: An object of parameters that will be utilized by the active command. + title: Hangup call + CallResponse: + type: object + required: + - id + - from + - to + - direction + - status + - duration + - duration_ms + - billing_ms + - source + - type + - url + - charge + - created_at + - parent_id + - charge_details + properties: + id: + type: string + description: The unique identifier of the call on SignalWire. This can be used to update the call programmatically. + example: 0e9c80d7-a149-4917-892d-420043709f45 + from: + type: string + description: The origin number or address. + example: '+12069708643' + to: + type: string + description: The destination number or address. + example: '+18048390497' + direction: + type: string + enum: + - outbound-api + description: The direction of the call. + example: outbound-api + status: + type: string + enum: + - answered + - queued + - initiated + - ringing + - ending + - ended + description: The status of the call. + example: queued + duration: + type: integer + nullable: true + description: The duration of the call in seconds. + example: null + duration_ms: + type: integer + nullable: true + description: The duration of the call in milliseconds. + example: null + billing_ms: + type: integer + nullable: true + description: The billable duration of the call in milliseconds. + example: null + source: + type: string + enum: + - realtime_api + description: Source of this call. + example: realtime_api + type: + type: string + enum: + - relay_pstn_call + - relay_sip_call + - relay_webrtc_call + description: Type of this call. + example: relay_pstn_call + url: + type: string + nullable: true + description: The URL associated with this call. + example: null + charge: + type: number + format: double + description: Total charge for this call. + example: 0 + created_at: + type: string + format: date-time + description: The date and time when the call was created. + example: '2024-05-06T12:20:00Z' + parent_id: + type: string + nullable: true + description: The parent call ID if this is a child call. + example: null + charge_details: + type: array + items: + $ref: '#/components/schemas/ChargeDetails' + description: Details on charges associated with this call. + CallUpdate422Error: + type: object + required: + - errors + properties: + errors: + type: array + items: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode422Error' + example: + errors: + - type: validation_error + code: missing_required_parameter + message: url must be a valid http or https url + attribute: url + url: https://developer.signalwire.com/rest/signalwire-rest/overview/error-codes#http_url_required + ChargeDetails: + type: object + required: + - description + - amount + properties: + description: + type: string + description: Description for this charge. + example: Text to Speech + amount: + type: number + description: Charged amount. + example: 0.121176 + Types.StatusCodes.StatusCode401: + type: object + required: + - error + properties: + error: + type: string + enum: + - Unauthorized + Types.StatusCodes.StatusCode404: + type: object + required: + - error + properties: + error: + type: string + enum: + - Not Found + Types.StatusCodes.StatusCode422Error: + type: object + required: + - type + - code + - message + - attribute + - url + properties: + type: + type: string + description: Error type. + code: + type: string + description: Error code. + message: + type: string + description: Error details. + attribute: + type: string + description: Request parameter associated with this error. + url: + type: string + description: Link to developer resource for this error. + Types.StatusCodes.StatusCode500: + type: object + required: + - error + properties: + error: + type: string + enum: + - Internal Server Error + uuid: + type: string + format: uuid + description: Universal Unique Identifier. + securitySchemes: + BasicAuth: + type: http + scheme: Basic +servers: + - url: https://{space_name}.signalwire.com/api/calling + description: Endpoint + variables: + space_name: + default: '{Your_Space_Name}' + description: The domain of the users SignalWire space. diff --git a/specs/signalwire-rest/calling-api/open-rpc/dial/main.tsp b/specs/signalwire-rest/calling-api/open-rpc/dial/main.tsp new file mode 100644 index 000000000..524af9efc --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/dial/main.tsp @@ -0,0 +1,55 @@ +import "@typespec/http"; +import "@typespec/openapi"; +import "../../../types"; +import "../../calls/models/requests.tsp"; +import "../../calls/models/responses.tsp"; +import "../../../_globally_shared/const.tsp"; +import "../../tags.tsp"; + +using TypeSpec.Http; +using TypeSpec.OpenAPI; +using Types.StatusCodes; + +@tagMetadata(CALLS_TAG, CALLS_TAG_METADATA) +@externalDocs( + "https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/dial", + "Documentation for the dial command to create new calls." +) +@info(#{ + title: "Calling API - Create Call", + version: "1.0.0", + contact: CONTACT_INFO, + license: LICENSE_INFO, + termsOfService: TERMS_OF_SERVICE, +}) +@service(#{ title: "Calling API - Create Call" }) +@server( + "https://{space_name}.${SERVER_URL}/calling", + "Endpoint", + { + @doc(SERVER_URL_DESCRIPTION) + @example("example") + space_name: string = "{Your_Space_Name}", + } +) +@useAuth(BasicAuth) +@doc("API to create SignalWire calls using the dial command.") +namespace CallingAPI.Dial; + +@route("/calls") +@tag("Calls") +interface CallingDialCommand { + @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`.") + @operationId("create-call") + @post + dial(@body request: CallCreateRequest): + | { + @statusCode statusCode: 201; + @body call: CallResponse; + } + | StatusCode401 + | StatusCode404 + | CallCreate422Error + | StatusCode500; +} diff --git a/specs/signalwire-rest/calling-api/open-rpc/dial/tsp-output/@typespec/openapi3/openapi.yaml b/specs/signalwire-rest/calling-api/open-rpc/dial/tsp-output/@typespec/openapi3/openapi.yaml new file mode 100644 index 000000000..0d8eeeb59 --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/dial/tsp-output/@typespec/openapi3/openapi.yaml @@ -0,0 +1,382 @@ +openapi: 3.0.0 +info: + title: Calling API - Create Call + version: 1.0.0 + contact: + name: SignalWire + url: https://support.signalwire.com/portal/en/newticket?departmentId=1029313000000006907&layoutId=1029313000000074011 + email: support@signalwire.com + license: + name: MIT + url: https://github.com/signalwire/docs/blob/main/LICENSE + termsOfService: https://signalwire.com/legal/signalwire-cloud-agreement + description: API to create SignalWire calls using the dial command. +externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/dial + description: Documentation for the dial command to create new calls. +tags: + - name: Calls + description: Endpoints related to creating and managing calls + externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls + description: Developer documentation on Calling API Call endpoints +paths: + /calls: + post: + operationId: create-call + summary: Create a Call + description: 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`. + parameters: [] + responses: + '201': + description: The request has succeeded and a new resource has been created as a result. + content: + application/json: + schema: + $ref: '#/components/schemas/CallResponse' + '401': + description: Access is unauthorized. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' + '404': + description: The server cannot find the requested resource. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode404' + '422': + description: Client error + content: + application/json: + schema: + $ref: '#/components/schemas/CallCreate422Error' + '500': + description: Server error + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' + tags: + - Calls + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CallCreateRequest' +security: + - BasicAuth: [] +components: + schemas: + CallCreate422Error: + type: object + required: + - errors + properties: + errors: + type: array + items: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode422Error' + example: + errors: + - type: validation_error + code: missing_required_parameter + message: url must be a valid http or https url + attribute: url + url: https://developer.signalwire.com/rest/signalwire-rest/overview/error-codes#http_url_required + CallCreateParamsSWML: + type: object + required: + - from + - to + - swml + properties: + from: + type: string + description: The address that initiated the call. Can be either a E.164 formatted number (`+xxxxxxxxxxx`), or a SIP endpoint (`sip:xxx@yyy.zzz`). + example: sip:from-sip@example-112233445566.sip.signalwire.com + to: + type: string + description: The address that received the call. Can be either a E.164 formatted number (`+xxxxxxxxxxx`), or a SIP endpoint (`sip:xxx@yyy.zzz`). + example: sip:from-sip@example-112233445567.sip.signalwire.com + caller_id: + type: string + description: The number, in E.164 format, or identifier of the caller. + example: '+1234567890' + fallback_url: + type: string + description: The Fallback URL to handle the call. This parameter allows you to specify a backup webhook or different route in your code containing SWML instructions for handling the call. + example: https://example.com/fallback + status_url: + type: string + format: uri + description: A URL that will recieve status updates of the current call. Any call events defined in `status_events` will be delivered to the defined URL. + example: https://example.com/status_callback + status_events: + type: array + items: + type: string + enum: + - answered + - queued + - initiated + - ringing + - ending + - ended + description: The call events that will be monitored and sent to the `status_url` when active. + example: + - answered + - ended + swml: + type: string + description: 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: "{'version': '1.0.0', 'sections': { 'main': [{ 'answer': { 'max_duration': 60 }},{ 'play': { 'urls': ['silence:2', 'say:Hello from SignalWire!']}}]}}" + title: Create call (SWML) + CallCreateParamsURL: + type: object + required: + - from + - to + - url + properties: + from: + type: string + description: The address that initiated the call. Can be either a E.164 formatted number (`+xxxxxxxxxxx`), or a SIP endpoint (`sip:xxx@yyy.zzz`). + example: sip:from-sip@example-112233445566.sip.signalwire.com + to: + type: string + description: The address that received the call. Can be either a E.164 formatted number (`+xxxxxxxxxxx`), or a SIP endpoint (`sip:xxx@yyy.zzz`). + example: sip:from-sip@example-112233445567.sip.signalwire.com + caller_id: + type: string + description: The number, in E.164 format, or identifier of the caller. + example: '+1234567890' + fallback_url: + type: string + description: The Fallback URL to handle the call. This parameter allows you to specify a backup webhook or different route in your code containing SWML instructions for handling the call. + example: https://example.com/fallback + status_url: + type: string + format: uri + description: A URL that will recieve status updates of the current call. Any call events defined in `status_events` will be delivered to the defined URL. + example: https://example.com/status_callback + status_events: + type: array + items: + type: string + enum: + - answered + - queued + - initiated + - ringing + - ending + - ended + description: The call events that will be monitored and sent to the `status_url` when active. + example: + - answered + - ended + url: + type: string + description: |- + The URL to handle the call. This parameter allows you to specify a webhook or different route in your code containing SWML instructions for handling the call. + Either `url` or `swml` must be included for a new call. + example: https://example.com/swml + title: Create call (URL) + CallCreateRequest: + type: object + required: + - command + - params + properties: + command: + type: string + enum: + - dial + description: The `dial` command is used to create a new call. + example: dial + params: + anyOf: + - $ref: '#/components/schemas/CallCreateParamsURL' + - $ref: '#/components/schemas/CallCreateParamsSWML' + description: An object of parameters that will be utilized by the active command. + title: Create call + CallResponse: + type: object + required: + - id + - from + - to + - direction + - status + - duration + - duration_ms + - billing_ms + - source + - type + - url + - charge + - created_at + - parent_id + - charge_details + properties: + id: + type: string + description: The unique identifier of the call on SignalWire. This can be used to update the call programmatically. + example: 0e9c80d7-a149-4917-892d-420043709f45 + from: + type: string + description: The origin number or address. + example: '+12069708643' + to: + type: string + description: The destination number or address. + example: '+18048390497' + direction: + type: string + enum: + - outbound-api + description: The direction of the call. + example: outbound-api + status: + type: string + enum: + - answered + - queued + - initiated + - ringing + - ending + - ended + description: The status of the call. + example: queued + duration: + type: integer + nullable: true + description: The duration of the call in seconds. + example: null + duration_ms: + type: integer + nullable: true + description: The duration of the call in milliseconds. + example: null + billing_ms: + type: integer + nullable: true + description: The billable duration of the call in milliseconds. + example: null + source: + type: string + enum: + - realtime_api + description: Source of this call. + example: realtime_api + type: + type: string + enum: + - relay_pstn_call + - relay_sip_call + - relay_webrtc_call + description: Type of this call. + example: relay_pstn_call + url: + type: string + nullable: true + description: The URL associated with this call. + example: null + charge: + type: number + format: double + description: Total charge for this call. + example: 0 + created_at: + type: string + format: date-time + description: The date and time when the call was created. + example: '2024-05-06T12:20:00Z' + parent_id: + type: string + nullable: true + description: The parent call ID if this is a child call. + example: null + charge_details: + type: array + items: + $ref: '#/components/schemas/ChargeDetails' + description: Details on charges associated with this call. + ChargeDetails: + type: object + required: + - description + - amount + properties: + description: + type: string + description: Description for this charge. + example: Text to Speech + amount: + type: number + description: Charged amount. + example: 0.121176 + Types.StatusCodes.StatusCode401: + type: object + required: + - error + properties: + error: + type: string + enum: + - Unauthorized + Types.StatusCodes.StatusCode404: + type: object + required: + - error + properties: + error: + type: string + enum: + - Not Found + Types.StatusCodes.StatusCode422Error: + type: object + required: + - type + - code + - message + - attribute + - url + properties: + type: + type: string + description: Error type. + code: + type: string + description: Error code. + message: + type: string + description: Error details. + attribute: + type: string + description: Request parameter associated with this error. + url: + type: string + description: Link to developer resource for this error. + Types.StatusCodes.StatusCode500: + type: object + required: + - error + properties: + error: + type: string + enum: + - Internal Server Error + securitySchemes: + BasicAuth: + type: http + scheme: Basic +servers: + - url: https://{space_name}.signalwire.com/api/calling + description: Endpoint + variables: + space_name: + default: '{Your_Space_Name}' + description: The domain of the users SignalWire space. diff --git a/specs/signalwire-rest/calling-api/open-rpc/update/main.tsp b/specs/signalwire-rest/calling-api/open-rpc/update/main.tsp new file mode 100644 index 000000000..560fb2682 --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/update/main.tsp @@ -0,0 +1,55 @@ +import "@typespec/http"; +import "@typespec/openapi"; +import "../../../types"; +import "../../calls/models/requests.tsp"; +import "../../calls/models/responses.tsp"; +import "../../../_globally_shared/const.tsp"; +import "../../tags.tsp"; + +using TypeSpec.Http; +using TypeSpec.OpenAPI; +using Types.StatusCodes; + +@tagMetadata(CALLS_TAG, CALLS_TAG_METADATA) +@externalDocs( + "https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/update", + "Documentation for the update command to modify existing calls." +) +@info(#{ + title: "Calling API - Update Call", + version: "1.0.0", + contact: CONTACT_INFO, + license: LICENSE_INFO, + termsOfService: TERMS_OF_SERVICE, +}) +@service(#{ title: "Calling API - Update Call" }) +@server( + "https://{space_name}.${SERVER_URL}/calling", + "Endpoint", + { + @doc(SERVER_URL_DESCRIPTION) + @example("example") + space_name: string = "{Your_Space_Name}", + } +) +@useAuth(BasicAuth) +@doc("API to update existing SignalWire calls with new SWML instructions.") +namespace CallingAPI.Update; + +@route("/calls") +@tag("Calls") +interface CallingUpdateCommand { + @summary("Update a Call") + @doc("To update an existing call, you send a `POST` request to the Call resource with a payload including an `update` command and additional nested `params` containing new SWML instructions.") + @operationId("update-call") + @post + update(@body request: CallUpdateCurrentCallRequest): + | { + @statusCode statusCode: 200; + @body call: CallResponse; + } + | StatusCode401 + | StatusCode404 + | CallUpdate422Error + | StatusCode500; +} diff --git a/specs/signalwire-rest/calling-api/open-rpc/update/tsp-output/@typespec/openapi3/openapi.yaml b/specs/signalwire-rest/calling-api/open-rpc/update/tsp-output/@typespec/openapi3/openapi.yaml new file mode 100644 index 000000000..df145034d --- /dev/null +++ b/specs/signalwire-rest/calling-api/open-rpc/update/tsp-output/@typespec/openapi3/openapi.yaml @@ -0,0 +1,342 @@ +openapi: 3.0.0 +info: + title: Calling API - Update Call + version: 1.0.0 + contact: + name: SignalWire + url: https://support.signalwire.com/portal/en/newticket?departmentId=1029313000000006907&layoutId=1029313000000074011 + email: support@signalwire.com + license: + name: MIT + url: https://github.com/signalwire/docs/blob/main/LICENSE + termsOfService: https://signalwire.com/legal/signalwire-cloud-agreement + description: API to update existing SignalWire calls with new SWML instructions. +externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/update + description: Documentation for the update command to modify existing calls. +tags: + - name: Calls + description: Endpoints related to creating and managing calls + externalDocs: + url: https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls + description: Developer documentation on Calling API Call endpoints +paths: + /calls: + post: + operationId: update-call + summary: Update a Call + description: To update an existing call, you send a `POST` request to the Call resource with a payload including an `update` command and additional nested `params` containing new SWML instructions. + parameters: [] + responses: + '200': + description: The request has succeeded. + content: + application/json: + schema: + $ref: '#/components/schemas/CallResponse' + '401': + description: Access is unauthorized. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' + '404': + description: The server cannot find the requested resource. + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode404' + '422': + description: Client error + content: + application/json: + schema: + $ref: '#/components/schemas/CallUpdate422Error' + '500': + description: Server error + content: + application/json: + schema: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' + tags: + - Calls + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CallUpdateCurrentCallRequest' +security: + - BasicAuth: [] +components: + schemas: + CallResponse: + type: object + required: + - id + - from + - to + - direction + - status + - duration + - duration_ms + - billing_ms + - source + - type + - url + - charge + - created_at + - parent_id + - charge_details + properties: + id: + type: string + description: The unique identifier of the call on SignalWire. This can be used to update the call programmatically. + example: 0e9c80d7-a149-4917-892d-420043709f45 + from: + type: string + description: The origin number or address. + example: '+12069708643' + to: + type: string + description: The destination number or address. + example: '+18048390497' + direction: + type: string + enum: + - outbound-api + description: The direction of the call. + example: outbound-api + status: + type: string + enum: + - answered + - queued + - initiated + - ringing + - ending + - ended + description: The status of the call. + example: queued + duration: + type: integer + nullable: true + description: The duration of the call in seconds. + example: null + duration_ms: + type: integer + nullable: true + description: The duration of the call in milliseconds. + example: null + billing_ms: + type: integer + nullable: true + description: The billable duration of the call in milliseconds. + example: null + source: + type: string + enum: + - realtime_api + description: Source of this call. + example: realtime_api + type: + type: string + enum: + - relay_pstn_call + - relay_sip_call + - relay_webrtc_call + description: Type of this call. + example: relay_pstn_call + url: + type: string + nullable: true + description: The URL associated with this call. + example: null + charge: + type: number + format: double + description: Total charge for this call. + example: 0 + created_at: + type: string + format: date-time + description: The date and time when the call was created. + example: '2024-05-06T12:20:00Z' + parent_id: + type: string + nullable: true + description: The parent call ID if this is a child call. + example: null + charge_details: + type: array + items: + $ref: '#/components/schemas/ChargeDetails' + description: Details on charges associated with this call. + CallUpdate422Error: + type: object + required: + - errors + properties: + errors: + type: array + items: + $ref: '#/components/schemas/Types.StatusCodes.StatusCode422Error' + example: + errors: + - type: validation_error + code: missing_required_parameter + message: url must be a valid http or https url + attribute: url + url: https://developer.signalwire.com/rest/signalwire-rest/overview/error-codes#http_url_required + CallUpdateCurrentCallRequest: + type: object + required: + - command + - params + properties: + command: + type: string + enum: + - update + description: The `update` command is used to update a existing call with a new dialplan. + example: update + params: + anyOf: + - $ref: '#/components/schemas/CallUpdateParamsURL' + - $ref: '#/components/schemas/CallUpdateParamsSWML' + description: An object of parameters that will be utilized by the active command. + title: Update call + CallUpdateParamsSWML: + type: object + required: + - id + - swml + properties: + id: + type: string + description: The unique identifying ID of a existing call. + example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + fallback_url: + type: string + description: |- + The Fallback URL to handle the call. + This parameter allows you to specify a backup webhook or different route in your code containing SWML instructions for handling the call. + example: https://example.com/fallback + status: + type: string + enum: + - canceled + - completed + description: Either `canceled` (to cancel a not yet connected call) or `completed` (to end a call that is in progress). + example: canceled + swml: + type: string + description: 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: "{'version': '1.0.0', 'sections': { 'main': [{ 'answer': { 'max_duration': 60 }},{ 'play': { 'urls': ['silence:2', 'say:Hello from SignalWire!']}}]}}" + title: Update call (SWML) + CallUpdateParamsURL: + type: object + required: + - id + - url + properties: + id: + type: string + description: The unique identifying ID of a existing call. + example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + fallback_url: + type: string + description: |- + The Fallback URL to handle the call. + This parameter allows you to specify a backup webhook or different route in your code containing SWML instructions for handling the call. + example: https://example.com/fallback + status: + type: string + enum: + - canceled + - completed + description: Either `canceled` (to cancel a not yet connected call) or `completed` (to end a call that is in progress). + example: canceled + url: + type: string + description: |- + The URL to handle the call. This parameter allows you to specify a webhook or different route in your code containing SWML instructions for handling the call. + Either `url` or `swml` must be included for a new call. + example: https://example.com/swml + title: Update call (URL) + ChargeDetails: + type: object + required: + - description + - amount + properties: + description: + type: string + description: Description for this charge. + example: Text to Speech + amount: + type: number + description: Charged amount. + example: 0.121176 + Types.StatusCodes.StatusCode401: + type: object + required: + - error + properties: + error: + type: string + enum: + - Unauthorized + Types.StatusCodes.StatusCode404: + type: object + required: + - error + properties: + error: + type: string + enum: + - Not Found + Types.StatusCodes.StatusCode422Error: + type: object + required: + - type + - code + - message + - attribute + - url + properties: + type: + type: string + description: Error type. + code: + type: string + description: Error code. + message: + type: string + description: Error details. + attribute: + type: string + description: Request parameter associated with this error. + url: + type: string + description: Link to developer resource for this error. + Types.StatusCodes.StatusCode500: + type: object + required: + - error + properties: + error: + type: string + enum: + - Internal Server Error + securitySchemes: + BasicAuth: + type: http + scheme: Basic +servers: + - url: https://{space_name}.signalwire.com/api/calling + description: Endpoint + variables: + space_name: + default: '{Your_Space_Name}' + description: The domain of the users SignalWire space. diff --git a/specs/signalwire-rest/calling-api/tsp-output/@typespec/openapi3/openapi.yaml b/specs/signalwire-rest/calling-api/tsp-output/@typespec/openapi3/openapi.yaml index 8c707e659..2cbc281a6 100644 --- a/specs/signalwire-rest/calling-api/tsp-output/@typespec/openapi3/openapi.yaml +++ b/specs/signalwire-rest/calling-api/tsp-output/@typespec/openapi3/openapi.yaml @@ -504,6 +504,24 @@ components: message: url must be a valid http or https url attribute: url url: https://developer.signalwire.com/rest/signalwire-rest/overview/error-codes#http_url_required + CallUpdateCurrentCallRequest: + type: object + required: + - command + - params + properties: + command: + type: string + enum: + - update + description: The `update` command is used to update a existing call with a new dialplan. + example: update + params: + anyOf: + - $ref: '#/components/schemas/CallUpdateParamsURL' + - $ref: '#/components/schemas/CallUpdateParamsSWML' + description: An object of parameters that will be utilized by the active command. + title: Update call CallUpdateParamsSWML: type: object required: @@ -564,45 +582,11 @@ components: title: Update call (URL) CallUpdateRequest: anyOf: - - $ref: '#/components/schemas/UpdateCurrentCallRequest' + - $ref: '#/components/schemas/CallUpdateCurrentCallRequest' - $ref: '#/components/schemas/CallHangupRequest' - $ref: '#/components/schemas/CallHoldRequest' - $ref: '#/components/schemas/CallUnholdRequest' - $ref: '#/components/schemas/CallAIMessageRequest' - CallUpdateSWMLRequest: - type: object - required: - - command - - params - properties: - command: - type: string - enum: - - update - description: The `update` command is used to update a existing call with a new dialplan. - example: update - params: - allOf: - - $ref: '#/components/schemas/CallUpdateParamsSWML' - description: An object of parameters that will be utilized by the active command. - title: Update call (SWML) - CallUpdateURLRequest: - type: object - required: - - command - - params - properties: - command: - type: string - enum: - - update - description: The `update` command is used to update a existing call with a new dialplan. - example: update - params: - allOf: - - $ref: '#/components/schemas/CallUpdateParamsURL' - description: An object of parameters that will be utilized by the active command. - title: Update call (URL) ChargeDetails: type: object required: @@ -668,11 +652,6 @@ components: type: string enum: - Internal Server Error - UpdateCurrentCallRequest: - oneOf: - - $ref: '#/components/schemas/CallUpdateSWMLRequest' - - $ref: '#/components/schemas/CallUpdateURLRequest' - title: Update call uuid: type: string format: uuid diff --git a/website/config/pluginsConfig/docusaurus-plugin-openapi-docs.ts b/website/config/pluginsConfig/docusaurus-plugin-openapi-docs.ts index b5fdf970c..70357b296 100644 --- a/website/config/pluginsConfig/docusaurus-plugin-openapi-docs.ts +++ b/website/config/pluginsConfig/docusaurus-plugin-openapi-docs.ts @@ -23,14 +23,44 @@ export const openapiPlugin: PluginConfig = [ groupPathsBy: "tag", }, }, - signalwireCallingApi: { - specPath: "../specs/signalwire-rest/calling-api/tsp-output/@typespec/openapi3/openapi.yaml", - outputDir: "docs/main/rest/signalwire-rest/endpoints/calling", - maskCredentials: false, - sidebarOptions: { - categoryLinkSource: "tag", - groupPathsBy: "tag", - }, + // BACKUP: Previous config with subdirectories + // To revert: restore outputDir to subdirectories (dial/, update/, calling-end/, etc.) + // and remove the outputDir override below + signalwireCallingApiDial: { + specPath: "../specs/signalwire-rest/calling-api/open-rpc/dial/tsp-output/@typespec/openapi3/openapi.yaml", + outputDir: "docs/main/rest/signalwire-rest/endpoints/calling", // FLAT - no subdirectories + maskCredentials: false, + // NO sidebarOptions - we'll create a manual sidebar to avoid overwriting + }, + signalwireCallingApiUpdate: { + specPath: "../specs/signalwire-rest/calling-api/open-rpc/update/tsp-output/@typespec/openapi3/openapi.yaml", + outputDir: "docs/main/rest/signalwire-rest/endpoints/calling", // FLAT + maskCredentials: false, + // NO sidebarOptions + }, + signalwireCallingApiEnd: { + specPath: "../specs/signalwire-rest/calling-api/open-rpc/calling-end/tsp-output/@typespec/openapi3/openapi.yaml", + outputDir: "docs/main/rest/signalwire-rest/endpoints/calling", // FLAT + maskCredentials: false, + // NO sidebarOptions + }, + signalwireCallingApiAiHold: { + specPath: "../specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/tsp-output/@typespec/openapi3/openapi.yaml", + outputDir: "docs/main/rest/signalwire-rest/endpoints/calling", // FLAT + maskCredentials: false, + // NO sidebarOptions + }, + signalwireCallingApiAiUnhold: { + specPath: "../specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/tsp-output/@typespec/openapi3/openapi.yaml", + outputDir: "docs/main/rest/signalwire-rest/endpoints/calling", // FLAT + maskCredentials: false, + // NO sidebarOptions + }, + signalwireCallingApiAiMessage: { + specPath: "../specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/tsp-output/@typespec/openapi3/openapi.yaml", + outputDir: "docs/main/rest/signalwire-rest/endpoints/calling", // FLAT + maskCredentials: false, + // NO sidebarOptions }, signalwireChatApi: { specPath: "../specs/signalwire-rest/chat-api/tsp-output/@typespec/openapi3/openapi.yaml", diff --git a/website/config/sidebarsConfig/main/rest-api-sidebar.ts b/website/config/sidebarsConfig/main/rest-api-sidebar.ts index 106297881..50c2d9a26 100644 --- a/website/config/sidebarsConfig/main/rest-api-sidebar.ts +++ b/website/config/sidebarsConfig/main/rest-api-sidebar.ts @@ -74,7 +74,45 @@ const apiSidebar: SidebarsConfig = { }, type: "category", label: "Calling", - items: require("../../../docs/main/rest/signalwire-rest/endpoints/calling/sidebar"), + // Manual sidebar items since all specs output to flat directory without auto-sidebar generation + items: [ + { + type: "doc", + id: "rest/signalwire-rest/endpoints/calling/create-call", + label: "Create a Call (dial)", + className: "api-method post", + }, + { + type: "doc", + id: "rest/signalwire-rest/endpoints/calling/update-call", + label: "Update a Call (update)", + className: "api-method post", + }, + { + type: "doc", + id: "rest/signalwire-rest/endpoints/calling/hangup-call", + label: "Hangup a Call (calling.end)", + className: "api-method post", + }, + { + type: "doc", + id: "rest/signalwire-rest/endpoints/calling/hold-ai", + label: "Hold an AI Call (calling.ai_hold)", + className: "api-method post", + }, + { + type: "doc", + id: "rest/signalwire-rest/endpoints/calling/unhold-ai", + label: "Unhold an AI Call (calling.ai_unhold)", + className: "api-method post", + }, + { + type: "doc", + id: "rest/signalwire-rest/endpoints/calling/inject-ai-message", + label: "Inject AI Message (calling.ai_message)", + className: "api-method post", + }, + ], }, { link: { diff --git a/website/docs/main/home/calling/fax/getting-started/first-steps-with-fax/index.mdx b/website/docs/main/home/calling/fax/getting-started/first-steps-with-fax/index.mdx index c2b98f56e..0a970f339 100644 --- a/website/docs/main/home/calling/fax/getting-started/first-steps-with-fax/index.mdx +++ b/website/docs/main/home/calling/fax/getting-started/first-steps-with-fax/index.mdx @@ -208,7 +208,7 @@ sections: -You can also utilize SWML to send faxes via a POST request to the SignalWire REST API [Create a Call endpoint](/rest/signalwire-rest/endpoints/calling/calls-create). +You can also utilize SWML to send faxes via a POST request to the SignalWire REST API [Create a Call endpoint](/rest/signalwire-rest/endpoints/calling/create-call). This can be done either by referencing a SWML script via webhook URL or by including the SWML inline in the request body. diff --git a/website/docs/main/home/calling/voice/sip/byoc/index.mdx b/website/docs/main/home/calling/voice/sip/byoc/index.mdx index 68f198d03..5444566be 100644 --- a/website/docs/main/home/calling/voice/sip/byoc/index.mdx +++ b/website/docs/main/home/calling/voice/sip/byoc/index.mdx @@ -226,7 +226,7 @@ If you are using BYOC to do outbound calls from SignalWire, you will need a SIP ##### Calling API -To create an outbound call using the Calling API with curl, you can use the [Create a Call endpoint](/rest/signalwire-rest/endpoints/calling/calls-create) with the following format: +To create an outbound call using the Calling API with curl, you can use the [Create a Call endpoint](/rest/signalwire-rest/endpoints/calling/create-call) with the following format: ```bash curl -L 'https://.signalwire.com/api/calling/calls' \ diff --git a/website/docs/main/home/calling/voice/sip/sip-endpoints/index.mdx b/website/docs/main/home/calling/voice/sip/sip-endpoints/index.mdx index a18692a78..c80e16bf3 100644 --- a/website/docs/main/home/calling/voice/sip/sip-endpoints/index.mdx +++ b/website/docs/main/home/calling/voice/sip/sip-endpoints/index.mdx @@ -104,7 +104,7 @@ Great for users looking to migrate from a TwiML-based application. - Use the `Sip` noun to [dial a SIP endpoint](/compatibility-api/cxml/voice/sip-noun) from an XML Bin. - [**REST API**](/rest) - A RESTful API for creating SignalWire applications. You can host your own webhook server to use these REST APIs. - - SignalWire REST API to [create a call](/rest/signalwire-rest/endpoints/calling/calls-create) to your SIP endpoint. + - SignalWire REST API to [create a call](/rest/signalwire-rest/endpoints/calling/create-call) to your SIP endpoint. - Compatibility REST API to [create a call](/rest/compatibility-api/endpoints/create-a-call) to your SIP endpoint. diff --git a/website/provisioning/nginx/redirects.map b/website/provisioning/nginx/redirects.map index 29f665887..9820c60bb 100644 --- a/website/provisioning/nginx/redirects.map +++ b/website/provisioning/nginx/redirects.map @@ -504,10 +504,6 @@ /rest/compatibility-api/overview/client-libraries-and-sdks/ /compatibility-api/sdks; # Redirects for REST APIs after TypeSpec conversion -/rest/signalwire-rest/endpoints/calling/update-call /rest/signalwire-rest/endpoints/calling/calls-update; -/rest/signalwire-rest/endpoints/calling/update-call/ /rest/signalwire-rest/endpoints/calling/calls-update; -/rest/signalwire-rest/endpoints/calling/create-call /rest/signalwire-rest/endpoints/calling/calls-create; -/rest/signalwire-rest/endpoints/calling/create-call/ /rest/signalwire-rest/endpoints/calling/calls-create; /rest/signalwire-rest/endpoints/chat/create-token /rest/signalwire-rest/endpoints/chat/chat-tokens-create; /rest/signalwire-rest/endpoints/chat/create-token/ /rest/signalwire-rest/endpoints/chat/chat-tokens-create; /rest/signalwire-rest/endpoints/fabric/list-external-laml-handler-addresses /rest/signalwire-rest/endpoints/fabric/external-laml-handler-addresses-list; @@ -1674,3 +1670,9 @@ # Remove Platform stub category page - 17-10-2025 /platform /platform/call-fabric; /platform/ /platform/call-fabric; + +# Rework Calling API Specs +/rest/signalwire-rest/endpoints/calling/calls-create /rest/signalwire-rest/endpoints/calling/create-call; +/rest/signalwire-rest/endpoints/calling/calls-create/ /rest/signalwire-rest/endpoints/calling/create-call; +/rest/signalwire-rest/endpoints/calling/calls-update /rest/signalwire-rest/endpoints/calling/update-call; +/rest/signalwire-rest/endpoints/calling/calls-update/ /rest/signalwire-rest/endpoints/calling/update-call;