From 9fe6029f00f6543ec5f4afbc4b5e3c76b1b41b2f Mon Sep 17 00:00:00 2001 From: Devon White Date: Mon, 3 Nov 2025 07:45:31 -0500 Subject: [PATCH 1/6] Update Calling API specs to reflect OpenRPC better --- specs/package.json | 3 +- .../calling-api/calls/models/requests.tsp | 37 +- .../open-rpc/calling-ai-hold/main.tsp | 55 +++ .../@typespec/openapi3/openapi.yaml | 292 +++++++++++++ .../open-rpc/calling-ai-message/main.tsp | 55 +++ .../@typespec/openapi3/openapi.yaml | 312 ++++++++++++++ .../open-rpc/calling-ai-unhold/main.tsp | 55 +++ .../@typespec/openapi3/openapi.yaml | 292 +++++++++++++ .../calling-api/open-rpc/calling-end/main.tsp | 55 +++ .../@typespec/openapi3/openapi.yaml | 300 ++++++++++++++ .../calling-api/open-rpc/dial/main.tsp | 55 +++ .../@typespec/openapi3/openapi.yaml | 382 ++++++++++++++++++ .../calling-api/open-rpc/update/main.tsp | 55 +++ .../@typespec/openapi3/openapi.yaml | 342 ++++++++++++++++ .../@typespec/openapi3/openapi.yaml | 59 +-- .../docusaurus-plugin-openapi-docs.ts | 46 ++- .../sidebarsConfig/main/rest-api-sidebar.ts | 40 +- website/provisioning/nginx/redirects.map | 10 +- 18 files changed, 2366 insertions(+), 79 deletions(-) create mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/main.tsp create mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/tsp-output/@typespec/openapi3/openapi.yaml create mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/main.tsp create mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/tsp-output/@typespec/openapi3/openapi.yaml create mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/main.tsp create mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/tsp-output/@typespec/openapi3/openapi.yaml create mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-end/main.tsp create mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-end/tsp-output/@typespec/openapi3/openapi.yaml create mode 100644 specs/signalwire-rest/calling-api/open-rpc/dial/main.tsp create mode 100644 specs/signalwire-rest/calling-api/open-rpc/dial/tsp-output/@typespec/openapi3/openapi.yaml create mode 100644 specs/signalwire-rest/calling-api/open-rpc/update/main.tsp create mode 100644 specs/signalwire-rest/calling-api/open-rpc/update/tsp-output/@typespec/openapi3/openapi.yaml 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/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; From c137365da5101073fe4965c5e424a0a52455161c Mon Sep 17 00:00:00 2001 From: Devon White Date: Mon, 3 Nov 2025 08:10:13 -0500 Subject: [PATCH 2/6] Fix broken links --- website/docs/main/home/calling/voice/sip/byoc/index.mdx | 2 +- .../docs/main/home/calling/voice/sip/sip-endpoints/index.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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. From 3c0deede0d6396486505d7b4203bdff4f862d5c7 Mon Sep 17 00:00:00 2001 From: Devon White Date: Mon, 3 Nov 2025 08:27:14 -0500 Subject: [PATCH 3/6] Fix broken links --- .../calling/fax/getting-started/first-steps-with-fax/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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. From 82d517fa0cec8675f23afa266608a95a87f648f0 Mon Sep 17 00:00:00 2001 From: Devon White Date: Thu, 6 Nov 2025 10:31:57 -0500 Subject: [PATCH 4/6] Update Calling API --- specs/package.json | 1 - .../calling-api/calls/main.tsp | 51 ++- .../calling-api/calls/models/examples.tsp | 54 ++- .../calling-api/calls/models/requests.tsp | 29 +- .../open-rpc/calling-ai-hold/main.tsp | 55 --- .../@typespec/openapi3/openapi.yaml | 292 ------------- .../open-rpc/calling-ai-message/main.tsp | 55 --- .../@typespec/openapi3/openapi.yaml | 312 -------------- .../open-rpc/calling-ai-unhold/main.tsp | 55 --- .../@typespec/openapi3/openapi.yaml | 292 ------------- .../calling-api/open-rpc/calling-end/main.tsp | 55 --- .../@typespec/openapi3/openapi.yaml | 300 -------------- .../calling-api/open-rpc/dial/main.tsp | 55 --- .../@typespec/openapi3/openapi.yaml | 382 ------------------ .../calling-api/open-rpc/update/main.tsp | 55 --- .../@typespec/openapi3/openapi.yaml | 342 ---------------- .../@typespec/openapi3/openapi.yaml | 143 ++++--- .../docusaurus-plugin-openapi-docs.ts | 44 +- .../sidebarsConfig/main/rest-api-sidebar.ts | 40 +- website/provisioning/nginx/redirects.map | 10 +- 20 files changed, 178 insertions(+), 2444 deletions(-) delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/main.tsp delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/tsp-output/@typespec/openapi3/openapi.yaml delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/main.tsp delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/tsp-output/@typespec/openapi3/openapi.yaml delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/main.tsp delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/tsp-output/@typespec/openapi3/openapi.yaml delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-end/main.tsp delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/calling-end/tsp-output/@typespec/openapi3/openapi.yaml delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/dial/main.tsp delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/dial/tsp-output/@typespec/openapi3/openapi.yaml delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/update/main.tsp delete mode 100644 specs/signalwire-rest/calling-api/open-rpc/update/tsp-output/@typespec/openapi3/openapi.yaml diff --git a/specs/package.json b/specs/package.json index 3e3d8b7f9..34755763b 100644 --- a/specs/package.json +++ b/specs/package.json @@ -9,7 +9,6 @@ "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/main.tsp b/specs/signalwire-rest/calling-api/calls/main.tsp index c4ed754f2..5fc220015 100644 --- a/specs/signalwire-rest/calling-api/calls/main.tsp +++ b/specs/signalwire-rest/calling-api/calls/main.tsp @@ -1,10 +1,12 @@ import "@typespec/http"; +import "@typespec/openapi"; import "../../types"; import "./models/requests.tsp"; import "./models/responses.tsp"; import "./models/examples.tsp"; using TypeSpec.Http; +using TypeSpec.OpenAPI; using Types.StatusCodes; @route("/calls") @@ -12,20 +14,33 @@ namespace CallingAPI.Calls { @tag("Calls") @friendlyName("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(@body request: CallCreateRequest): - | { - @statusCode statusCode: 201; - @body call: CallResponse; - } - | StatusCode401 - | StatusCode404 - | CallCreate422Error - | StatusCode500; - - @summary("Update a Call") - @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`.") + @summary("Send Call Commands") + @doc(""" + Unified OpenRPC-style endpoint for executing call methods through command-based dispatch. + Send a request with the appropriate `command` field to invoke the desired call operation. + This endpoint provides a single interface for all call-related methods including creation, updates, termination, and AI conversation control. + """) + @opExample( + #{ parameters: dialCallExample }, + #{ + title: "Create new call", + description: "Initiate a new outbound call with the dial command", + } + ) + @opExample( + #{ parameters: updateCallExample }, + #{ + title: "Update active call", + description: "Modify an existing call's parameters in real-time", + } + ) + @opExample( + #{ parameters: hangupCallExample }, + #{ + title: "End call", + description: "Terminate an active call immediately", + } + ) @opExample( #{ parameters: holdCallExample }, #{ @@ -47,16 +62,16 @@ namespace CallingAPI.Calls { 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): + @post + @operationId("call-commands") + callCommand(@body request: CallRequest): | { @statusCode statusCode: 200; @body call: CallResponse; } | StatusCode401 | StatusCode404 - | CallUpdate422Error + | CallCreate422Error | StatusCode500; } } diff --git a/specs/signalwire-rest/calling-api/calls/models/examples.tsp b/specs/signalwire-rest/calling-api/calls/models/examples.tsp index 346df7e39..b85051f25 100644 --- a/specs/signalwire-rest/calling-api/calls/models/examples.tsp +++ b/specs/signalwire-rest/calling-api/calls/models/examples.tsp @@ -5,41 +5,63 @@ */ const callId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"; -// Hangup Call Examples +// Call command examples +const dialCallExample = #{ + request: #{ + command: "dial", + params: #{ + from: "+15551234567", + to: "+15559876543", + url: "https://example.com/swml", + caller_id: "+15551234567", + status_url: "https://example.com/status_callback", + status_events: #["answered", "ended"], + }, + }, +}; + +const updateCallExample = #{ + request: #{ + command: "update", + params: #{ + id: callId, + url: "https://example.com/swml", + fallback_url: "https://example.com/fallback", + }, + }, +}; + const hangupCallExample = #{ request: #{ - id: callId, command: "calling.end", + id: callId, params: #{ reason: "hangup" }, }, }; const holdCallExample = #{ - request: #{ id: callId, command: "calling.ai_hold", params: #{} }, + request: #{ + command: "calling.ai_hold", + id: callId, + params: #{}, + }, }; const unholdCallExample = #{ - request: #{ id: callId, command: "calling.ai_unhold", params: #{} }, + request: #{ + command: "calling.ai_unhold", + id: callId, + params: #{}, + }, }; const aiMessageExample = #{ request: #{ - id: callId, command: "calling.ai_message", + id: callId, 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", - }, - }, -}; diff --git a/specs/signalwire-rest/calling-api/calls/models/requests.tsp b/specs/signalwire-rest/calling-api/calls/models/requests.tsp index a861576ee..da7672459 100644 --- a/specs/signalwire-rest/calling-api/calls/models/requests.tsp +++ b/specs/signalwire-rest/calling-api/calls/models/requests.tsp @@ -200,10 +200,27 @@ model CallUpdateCurrentCallRequest { params: CallUpdateParamsAlias; } -union CallUpdateRequest { - CallUpdateCurrentCallRequest, - CallHangupRequest, - CallHoldRequest, - CallUnholdRequest, - CallAIMessageRequest, +@discriminated(#{discriminatorPropertyName: "command", envelope: "none"}) +@doc(""" +Call request union for OpenRPC-style method dispatch. Use the `command` field to specify which call method to invoke: + +- **`dial`** - Create and initiate a new outbound call to a destination. Returns immediately with call details while the call is being established in the background. + +- **`update`** - Modify an active call's properties in real-time. Update call parameters such as routing, recording settings, or other call-specific configurations. + +- **`calling.end`** - Terminate an active call immediately. Disconnects all parties and ends the call session. Cannot be reversed once executed. + +- **`calling.ai_hold`** - Place an AI-powered call on hold. Pauses the AI conversation and typically plays hold music or a message to the caller. The AI agent becomes inactive until unhold. + +- **`calling.ai_unhold`** - Resume an AI call from hold state. Reactivates the AI agent and continues the conversation from where it was paused. + +- **`calling.ai_message`** - Inject a message into an active AI conversation. Allows you to dynamically add context, instructions, or system messages to guide the AI agent's behavior during the call. +""") +union CallRequest { + dial: CallCreateRequest, + update: CallUpdateCurrentCallRequest, + `calling.end`: CallHangupRequest, + `calling.ai_hold`: CallHoldRequest, + `calling.ai_unhold`: CallUnholdRequest, + `calling.ai_message`: 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 deleted file mode 100644 index c7e628134..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/main.tsp +++ /dev/null @@ -1,55 +0,0 @@ -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 deleted file mode 100644 index fae20806c..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/tsp-output/@typespec/openapi3/openapi.yaml +++ /dev/null @@ -1,292 +0,0 @@ -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 deleted file mode 100644 index 23264790d..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/main.tsp +++ /dev/null @@ -1,55 +0,0 @@ -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 deleted file mode 100644 index 79390a2e1..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-message/tsp-output/@typespec/openapi3/openapi.yaml +++ /dev/null @@ -1,312 +0,0 @@ -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 deleted file mode 100644 index fbe047bb1..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/main.tsp +++ /dev/null @@ -1,55 +0,0 @@ -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 deleted file mode 100644 index 9ad461063..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/calling-ai-unhold/tsp-output/@typespec/openapi3/openapi.yaml +++ /dev/null @@ -1,292 +0,0 @@ -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 deleted file mode 100644 index d59011913..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/calling-end/main.tsp +++ /dev/null @@ -1,55 +0,0 @@ -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 deleted file mode 100644 index 15b7e5029..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/calling-end/tsp-output/@typespec/openapi3/openapi.yaml +++ /dev/null @@ -1,300 +0,0 @@ -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 deleted file mode 100644 index 524af9efc..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/dial/main.tsp +++ /dev/null @@ -1,55 +0,0 @@ -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 deleted file mode 100644 index 0d8eeeb59..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/dial/tsp-output/@typespec/openapi3/openapi.yaml +++ /dev/null @@ -1,382 +0,0 @@ -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 deleted file mode 100644 index 560fb2682..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/update/main.tsp +++ /dev/null @@ -1,55 +0,0 @@ -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 deleted file mode 100644 index df145034d..000000000 --- a/specs/signalwire-rest/calling-api/open-rpc/update/tsp-output/@typespec/openapi3/openapi.yaml +++ /dev/null @@ -1,342 +0,0 @@ -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 2cbc281a6..f8ab25fcc 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 @@ -23,53 +23,12 @@ tags: paths: /calls: post: - operationId: Calls_create - 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' - put: - operationId: Calls_update - summary: Update a Call - description: To update an existing call, you send a `PUT` request to the Call resource with a payload including a `command` and additional nested `params`. + operationId: call-commands + summary: Send Call Commands + description: |- + Unified OpenRPC-style endpoint for executing call methods through command-based dispatch. + Send a request with the appropriate `command` field to invoke the desired call operation. + This endpoint provides a single interface for all call-related methods including creation, updates, termination, and AI conversation control. parameters: [] responses: '200': @@ -95,7 +54,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CallUpdate422Error' + $ref: '#/components/schemas/CallCreate422Error' '500': description: Server error content: @@ -109,7 +68,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CallUpdateRequest' + $ref: '#/components/schemas/CallRequest' examples: Inject AI message: summary: Inject AI message @@ -134,6 +93,37 @@ paths: id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 command: calling.ai_hold params: {} + End call: + summary: End call + description: Terminate an active call immediately + value: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + command: calling.end + params: + reason: hangup + Update active call: + summary: Update active call + description: Modify an existing call's parameters in real-time + value: + command: update + params: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + url: https://example.com/swml + fallback_url: https://example.com/fallback + Create new call: + summary: Create new call + description: Initiate a new outbound call with the dial command + value: + command: dial + params: + from: '+15551234567' + to: '+15559876543' + url: https://example.com/swml + caller_id: '+15551234567' + status_url: https://example.com/status_callback + status_events: + - answered + - ended security: - BasicAuth: [] components: @@ -364,6 +354,38 @@ components: type: object description: An object of parameters that will be utilized by the active command. title: Hold call + CallRequest: + type: object + oneOf: + - $ref: '#/components/schemas/CallCreateRequest' + - $ref: '#/components/schemas/CallUpdateCurrentCallRequest' + - $ref: '#/components/schemas/CallHangupRequest' + - $ref: '#/components/schemas/CallHoldRequest' + - $ref: '#/components/schemas/CallUnholdRequest' + - $ref: '#/components/schemas/CallAIMessageRequest' + discriminator: + propertyName: command + mapping: + dial: '#/components/schemas/CallCreateRequest' + update: '#/components/schemas/CallUpdateCurrentCallRequest' + calling.end: '#/components/schemas/CallHangupRequest' + calling.ai_hold: '#/components/schemas/CallHoldRequest' + calling.ai_unhold: '#/components/schemas/CallUnholdRequest' + calling.ai_message: '#/components/schemas/CallAIMessageRequest' + description: |- + Call request union for OpenRPC-style method dispatch. Use the `command` field to specify which call method to invoke: + + - **`dial`** - Create and initiate a new outbound call to a destination. Returns immediately with call details while the call is being established in the background. + + - **`update`** - Modify an active call's properties in real-time. Update call parameters such as routing, recording settings, or other call-specific configurations. + + - **`calling.end`** - Terminate an active call immediately. Disconnects all parties and ends the call session. Cannot be reversed once executed. + + - **`calling.ai_hold`** - Place an AI-powered call on hold. Pauses the AI conversation and typically plays hold music or a message to the caller. The AI agent becomes inactive until unhold. + + - **`calling.ai_unhold`** - Resume an AI call from hold state. Reactivates the AI agent and continues the conversation from where it was paused. + + - **`calling.ai_message`** - Inject a message into an active AI conversation. Allows you to dynamically add context, instructions, or system messages to guide the AI agent's behavior during the call. CallResponse: type: object required: @@ -488,22 +510,6 @@ components: 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 CallUpdateCurrentCallRequest: type: object required: @@ -580,13 +586,6 @@ components: Either `url` or `swml` must be included for a new call. example: https://example.com/swml title: Update call (URL) - CallUpdateRequest: - anyOf: - - $ref: '#/components/schemas/CallUpdateCurrentCallRequest' - - $ref: '#/components/schemas/CallHangupRequest' - - $ref: '#/components/schemas/CallHoldRequest' - - $ref: '#/components/schemas/CallUnholdRequest' - - $ref: '#/components/schemas/CallAIMessageRequest' ChargeDetails: type: object required: diff --git a/website/config/pluginsConfig/docusaurus-plugin-openapi-docs.ts b/website/config/pluginsConfig/docusaurus-plugin-openapi-docs.ts index 70357b296..9d1145c2c 100644 --- a/website/config/pluginsConfig/docusaurus-plugin-openapi-docs.ts +++ b/website/config/pluginsConfig/docusaurus-plugin-openapi-docs.ts @@ -23,44 +23,14 @@ export const openapiPlugin: PluginConfig = [ 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 + signalwireCallingApi: { + specPath: "../specs/signalwire-rest/calling-api/tsp-output/@typespec/openapi3/openapi.yaml", + outputDir: "docs/main/rest/signalwire-rest/endpoints/calling", 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 + sidebarOptions: { + categoryLinkSource: "tag", + groupPathsBy: "tag", + }, }, 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 50c2d9a26..106297881 100644 --- a/website/config/sidebarsConfig/main/rest-api-sidebar.ts +++ b/website/config/sidebarsConfig/main/rest-api-sidebar.ts @@ -74,45 +74,7 @@ const apiSidebar: SidebarsConfig = { }, type: "category", label: "Calling", - // 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", - }, - ], + items: require("../../../docs/main/rest/signalwire-rest/endpoints/calling/sidebar"), }, { link: { diff --git a/website/provisioning/nginx/redirects.map b/website/provisioning/nginx/redirects.map index 9820c60bb..c4e9649b4 100644 --- a/website/provisioning/nginx/redirects.map +++ b/website/provisioning/nginx/redirects.map @@ -1671,8 +1671,8 @@ /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; +# Rework Calling API Specs - 11/6/25 +/rest/signalwire-rest/endpoints/calling/calls-create /rest/signalwire-rest/endpoints/calling/call-commands; +/rest/signalwire-rest/endpoints/calling/calls-create/ /rest/signalwire-rest/endpoints/calling/call-commands; +/rest/signalwire-rest/endpoints/calling/calls-update /rest/signalwire-rest/endpoints/calling/call-commands; +/rest/signalwire-rest/endpoints/calling/calls-update/ /rest/signalwire-rest/endpoints/calling/call-commands; From 54ab663d78b37a1ccdf16112a73f363939ce66eb Mon Sep 17 00:00:00 2001 From: Devon White Date: Thu, 6 Nov 2025 10:45:08 -0500 Subject: [PATCH 5/6] Fix spec build process --- specs/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/package.json b/specs/package.json index 34755763b..56935c197 100644 --- a/specs/package.json +++ b/specs/package.json @@ -5,7 +5,7 @@ "scripts": { "build": "yarn build:api", "build:all": "yarn build:api && yarn build:schema", - "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: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:schema": "yarn build:swml", "build:swml": "cd ./swml && tsp compile . && cd ../", "build:calling-api": "cd ./signalwire-rest/calling-api && tsp compile . && cd ../../", From b7abb1b8e0b3c64f4b54527bd4ecc934b9b390e3 Mon Sep 17 00:00:00 2001 From: Devon White Date: Thu, 6 Nov 2025 11:02:22 -0500 Subject: [PATCH 6/6] Fix broken links --- .../calling/fax/getting-started/first-steps-with-fax/index.mdx | 2 +- website/docs/main/home/calling/voice/sip/byoc/index.mdx | 2 +- .../docs/main/home/calling/voice/sip/sip-endpoints/index.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) 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 0a970f339..43180b994 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/create-call). +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/call-commands). 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 5444566be..8b7c52b82 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/create-call) 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/call-commands) 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 c80e16bf3..9eead329a 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/create-call) to your SIP endpoint. + - SignalWire REST API to [create a call](/rest/signalwire-rest/endpoints/calling/call-commands) to your SIP endpoint. - Compatibility REST API to [create a call](/rest/compatibility-api/endpoints/create-a-call) to your SIP endpoint.