From 14b67fd8f8a28019160123e5d223684917068f3c Mon Sep 17 00:00:00 2001 From: ajkamen Date: Wed, 27 May 2026 10:47:33 -0700 Subject: [PATCH 01/13] docs: add remote HTTP services guide Document external HTTP service and auth configuration APIs with reference entries. --- docs/integration/remote-http-services.md | 77 + mkdocs.yml | 1 + specs/engage-voice_openapi3.json | 2658 +++++++++++++++++++++- 3 files changed, 2665 insertions(+), 71 deletions(-) create mode 100644 docs/integration/remote-http-services.md diff --git a/docs/integration/remote-http-services.md b/docs/integration/remote-http-services.md new file mode 100644 index 0000000..9590549 --- /dev/null +++ b/docs/integration/remote-http-services.md @@ -0,0 +1,77 @@ +# Remote HTTP Service APIs + +The Remote HTTP Service APIs let you configure outbound HTTP integrations used by RingCX routing and scripting flows. Use them to maintain service groups, services, service inputs, activation state, and external authentication configurations from code. + +## Strategic Overview + +Remote HTTP services define reusable external endpoints that RingCX can call from IVR, scripting, or integration workflows. They are useful when the same CRM, middleware, or data-enrichment service must be configured consistently across many queues, scripts, or sub-accounts. + +### Key Use Cases + +* **Integration Provisioning:** Create service definitions during customer onboarding. +* **Credential Rotation:** Update OAuth or external auth configurations without rebuilding scripts. +* **Environment Promotion:** Clone or update service definitions as configurations move from test to production. +* **Operational Control:** Activate or deactivate a remote service during outages or endpoint migrations. + +### Required Permissions & Scopes + +Your application needs the `ReadAccounts` OAuth scope. The authenticating user must have platform permissions to read and update remote HTTP service groups, HTTP services, service inputs, and external auth configurations. + +## Manage Service Groups + +Service groups organize related remote HTTP services. + +| Operation | Method and Path | API Reference | +| --- | --- | --- | +| List groups | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceGroupList) | +| Create group | `POST /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createHttpServiceGroup) | +| List groups with services | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/withChildren` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceGroupListWithChildren) | +| Get group | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceGroup) | +| Update group | `PUT /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/updateHttpServiceGroup) | + +## Manage HTTP Services + +HTTP service records describe the external endpoint and how RingCX calls it. + +| Operation | Method and Path | API Reference | +| --- | --- | --- | +| List services | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceList) | +| Create service | `POST /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createHttpService) | +| Get service | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpService) | +| Update service | `PUT /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/updateHttpService) | +| Clone service | `POST /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/clone` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/cloneHttpService) | +| Set active state | `PUT /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/setIsActive` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/setHttpServiceIsActive) | + +## Configure Service Inputs + +Inputs define the values RingCX passes into the remote service request. Keep these in sync with the service contract expected by your external endpoint. + +| Operation | Method and Path | API Reference | +| --- | --- | --- | +| List inputs | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceInputList) | +| Create input | `POST /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createHttpServiceInput) | +| Get input | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs/{inputId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceInput) | +| Delete input | `DELETE /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs/{inputId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/deleteHttpServiceInput) | + +## External Auth Configurations + +External auth configurations store reusable authentication settings for remote services. Use these APIs when integrations require OAuth or other reusable credentials. + +| Operation | Method and Path | API Reference | +| --- | --- | --- | +| List auth configs | `GET /voice/api/cx/admin/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/external/authConfigs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getAccountAuthConfigs) | +| Create auth config | `POST /voice/api/cx/admin/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/external/authConfigs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createAccountAuthConfig) | +| Update auth config | `PUT /voice/api/cx/admin/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/external/authConfigs/{configId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/updateAccountAuthConfig) | +| Delete auth config | `DELETE /voice/api/cx/admin/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/external/authConfigs/{configId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/deleteAccountAuthConfig) | + +## Recommended Workflow + +1. Create or select a service group. +2. Create the remote HTTP service with the external endpoint details. +3. Add service inputs that map RingCX values into the outbound request. +4. Attach or update external auth configuration when the service requires credentials. +5. Activate the service after validation. +6. Clone the service when creating a similar integration for another environment or workflow. + +!!! important + Treat remote service changes like production integration changes. Validate the external endpoint, authentication, and expected response shape before activating the service in a live routing flow. diff --git a/mkdocs.yml b/mkdocs.yml index e455d6b..ee21856 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -105,6 +105,7 @@ nav: - 'Overview': integration/index.md - 'Reports': integration/reports-orig.md - 'Administration': integration/admin.md + - 'Remote HTTP Services': integration/remote-http-services.md - 'Routing': integration/agent-avail.md - 'SDKs': sdks.md - 'Embeddable': embeddable.md diff --git a/specs/engage-voice_openapi3.json b/specs/engage-voice_openapi3.json index 4d0eb35..48029bd 100644 --- a/specs/engage-voice_openapi3.json +++ b/specs/engage-voice_openapi3.json @@ -14446,34 +14446,91 @@ "WEMDialogSegmentMetaData": { "type": "object", "properties": { - "subAccountId": { "type": "string" }, - "dialogId": { "type": "string" }, - "interactionId": { "type": "string" }, - "channelId": { "type": "string" }, - "channelType": { "type": "string" }, - "channelClass": { "type": "string" }, - "channelEndpointAddress": { "type": "string" }, - "contactEndpointAddress": { "type": "string" }, - "dialogOrigination": { "type": "string" }, - "dialogStartTimeMs": { "type": "string", "format": "date-time" }, - "dialogEndTimeMs": { "type": "string", "format": "date-time" }, - "dialogDurationMs": { "type": "integer" }, - "segmentId": { "type": "string" }, - "segmentType": { "type": "string" }, - "segmentParticipantId": { "type": "string" }, - "segmentParticipantRcExtensionId": { "type": "string" }, - "segmentStartTimeMs": { "type": "string", "format": "date-time" }, - "segmentEndTimeMs": { "type": "string", "format": "date-time" }, - "segmentDurationMs": { "type": "integer" }, - "segmentAgentGroupId": { "type": "string" }, - "systemDisposition": { "type": "string", "nullable": true }, - "agentDisposition": { "type": "string" }, - "agentNotes": { "type": "string" }, - "hasRecording": { "type": "boolean" }, - "hasTranscript": { "type": "boolean" }, + "subAccountId": { + "type": "string" + }, + "dialogId": { + "type": "string" + }, + "interactionId": { + "type": "string" + }, + "channelId": { + "type": "string" + }, + "channelType": { + "type": "string" + }, + "channelClass": { + "type": "string" + }, + "channelEndpointAddress": { + "type": "string" + }, + "contactEndpointAddress": { + "type": "string" + }, + "dialogOrigination": { + "type": "string" + }, + "dialogStartTimeMs": { + "type": "string", + "format": "date-time" + }, + "dialogEndTimeMs": { + "type": "string", + "format": "date-time" + }, + "dialogDurationMs": { + "type": "integer" + }, + "segmentId": { + "type": "string" + }, + "segmentType": { + "type": "string" + }, + "segmentParticipantId": { + "type": "string" + }, + "segmentParticipantRcExtensionId": { + "type": "string" + }, + "segmentStartTimeMs": { + "type": "string", + "format": "date-time" + }, + "segmentEndTimeMs": { + "type": "string", + "format": "date-time" + }, + "segmentDurationMs": { + "type": "integer" + }, + "segmentAgentGroupId": { + "type": "string" + }, + "systemDisposition": { + "type": "string", + "nullable": true + }, + "agentDisposition": { + "type": "string" + }, + "agentNotes": { + "type": "string" + }, + "hasRecording": { + "type": "boolean" + }, + "hasTranscript": { + "type": "boolean" + }, "segmentEvents": { "type": "array", - "items": { "$ref": "#/components/schemas/InteractionSegmentEvent" }, + "items": { + "$ref": "#/components/schemas/InteractionSegmentEvent" + }, "nullable": true } } @@ -14522,60 +14579,185 @@ "AggregatedAgentStats": { "type": "object", "properties": { - "interval": { "type": "integer", "format": "int32" }, - "dateTimeFrom": { "type": "string" }, - "agentId": { "type": "integer", "format": "int32" }, - "agentName": { "type": "string" }, - "availDur": { "type": "integer", "format": "int32" }, - "totWorkDur": { "type": "integer", "format": "int32" }, - "pauseDur": { "type": "integer", "format": "int32" }, - "waitDur": { "type": "integer", "format": "int32" }, - "adminDur": { "type": "integer", "format": "int32" }, - "directOutIxnCnt": { "type": "integer", "format": "int32" }, - "directOutIxnDur": { "type": "integer", "format": "int32" }, - "directInIxnCnt": { "type": "integer", "format": "int32" }, - "directInIxnDur": { "type": "integer", "format": "int32" } + "interval": { + "type": "integer", + "format": "int32" + }, + "dateTimeFrom": { + "type": "string" + }, + "agentId": { + "type": "integer", + "format": "int32" + }, + "agentName": { + "type": "string" + }, + "availDur": { + "type": "integer", + "format": "int32" + }, + "totWorkDur": { + "type": "integer", + "format": "int32" + }, + "pauseDur": { + "type": "integer", + "format": "int32" + }, + "waitDur": { + "type": "integer", + "format": "int32" + }, + "adminDur": { + "type": "integer", + "format": "int32" + }, + "directOutIxnCnt": { + "type": "integer", + "format": "int32" + }, + "directOutIxnDur": { + "type": "integer", + "format": "int32" + }, + "directInIxnCnt": { + "type": "integer", + "format": "int32" + }, + "directInIxnDur": { + "type": "integer", + "format": "int32" + } } }, "AggregatedQueueStats": { "type": "object", "properties": { - "dateTimeFrom": { "type": "string" }, - "interval": { "type": "integer", "format": "int32" }, - "queue": { "type": "integer", "format": "int32" }, - "queueName": { "type": "string" }, - "offdDirectIxnCnt": { "type": "integer", "format": "int32" }, - "answIxnCnt": { "type": "integer", "format": "int32" }, - "abandIxnCnt": { "type": "integer", "format": "int32" }, - "abandShortIxnCnt": { "type": "integer", "format": "int32" }, - "abandWithinSlCnt": { "type": "integer", "format": "int32" }, - "ansServicelevelCnt": { "type": "integer", "format": "int32" }, - "completedContacts": { "type": "integer", "format": "int32" }, - "queuedAndAnswIxnDur": { "type": "integer", "format": "int32" }, - "queuedAndAbandIxnDur": { "type": "integer", "format": "int32" }, - "queuedAnswLongestQueDur": { "type": "integer", "format": "int32" }, - "queuedAbandLongestQueDur": { "type": "integer", "format": "int32" }, - "talkingIxnDur": { "type": "integer", "format": "int32" }, - "wrapUpDur": { "type": "integer", "format": "int32" }, - "waitDur": { "type": "integer", "format": "int32" }, - "segmentHoldTime": { "type": "integer", "format": "int32" }, - "overflowInIxnCnt": { "type": "integer", "format": "int32" }, - "overflowOutIxnCnt": { "type": "integer", "format": "int32" } + "dateTimeFrom": { + "type": "string" + }, + "interval": { + "type": "integer", + "format": "int32" + }, + "queue": { + "type": "integer", + "format": "int32" + }, + "queueName": { + "type": "string" + }, + "offdDirectIxnCnt": { + "type": "integer", + "format": "int32" + }, + "answIxnCnt": { + "type": "integer", + "format": "int32" + }, + "abandIxnCnt": { + "type": "integer", + "format": "int32" + }, + "abandShortIxnCnt": { + "type": "integer", + "format": "int32" + }, + "abandWithinSlCnt": { + "type": "integer", + "format": "int32" + }, + "ansServicelevelCnt": { + "type": "integer", + "format": "int32" + }, + "completedContacts": { + "type": "integer", + "format": "int32" + }, + "queuedAndAnswIxnDur": { + "type": "integer", + "format": "int32" + }, + "queuedAndAbandIxnDur": { + "type": "integer", + "format": "int32" + }, + "queuedAnswLongestQueDur": { + "type": "integer", + "format": "int32" + }, + "queuedAbandLongestQueDur": { + "type": "integer", + "format": "int32" + }, + "talkingIxnDur": { + "type": "integer", + "format": "int32" + }, + "wrapUpDur": { + "type": "integer", + "format": "int32" + }, + "waitDur": { + "type": "integer", + "format": "int32" + }, + "segmentHoldTime": { + "type": "integer", + "format": "int32" + }, + "overflowInIxnCnt": { + "type": "integer", + "format": "int32" + }, + "overflowOutIxnCnt": { + "type": "integer", + "format": "int32" + } } }, "ExtendedAggregatedQueueStats": { "type": "object", "properties": { - "interval": { "type": "integer", "format": "int32" }, - "dateTimeFrom": { "type": "string" }, - "agentId": { "type": "integer", "format": "int32" }, - "agentName": { "type": "string" }, - "queue": { "type": "integer", "format": "int32" }, - "queueName": { "type": "string" }, - "talkingIxnDur": { "type": "integer", "format": "int32" }, - "wrapUpDur": { "type": "integer", "format": "int32" }, - "answIxnCnt": { "type": "integer", "format": "int32" }, - "transferOutIxnCnt": { "type": "integer", "format": "int32" } + "interval": { + "type": "integer", + "format": "int32" + }, + "dateTimeFrom": { + "type": "string" + }, + "agentId": { + "type": "integer", + "format": "int32" + }, + "agentName": { + "type": "string" + }, + "queue": { + "type": "integer", + "format": "int32" + }, + "queueName": { + "type": "string" + }, + "talkingIxnDur": { + "type": "integer", + "format": "int32" + }, + "wrapUpDur": { + "type": "integer", + "format": "int32" + }, + "answIxnCnt": { + "type": "integer", + "format": "int32" + }, + "transferOutIxnCnt": { + "type": "integer", + "format": "int32" + } } }, "CXQueueWithAgents": { @@ -26529,6 +26711,2340 @@ } } } + }, + "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "getExternalAuthConfigsList", + "description": "", + "operationId": "getExternalAuthConfigsList", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "page", + "in": "query", + "description": "page", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "maxRows", + "in": "query", + "description": "maxRows", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigList" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/oauth/info": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "getExternalAccountAuthConfigOauthInfo", + "description": "", + "operationId": "getExternalAccountAuthConfigOauthInfo", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "oauthProvider", + "in": "query", + "description": "oauthProvider", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigOAuthUrl" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "getExternalAuthConfigById", + "description": "", + "operationId": "getExternalAuthConfigById", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetExternalAuthConfigById200Response" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "deleteExternalAuthConfigById", + "description": "", + "operationId": "deleteExternalAuthConfigById", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/apiKey": { + "post": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "createExternalAccountAuthConfigApiKey", + "description": "", + "operationId": "createExternalAccountAuthConfigApiKey", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigApiKey" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigApiKey" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "patch": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "patchExternalAuthConfigApiKey", + "description": "", + "operationId": "patchExternalAuthConfigApiKey", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigApiKey" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigApiKey" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/basic": { + "post": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "createExternalAccountAuthConfigBasic", + "description": "", + "operationId": "createExternalAccountAuthConfigBasic", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigBasic" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigBasic" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "patch": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "patchExternalAuthConfigBasic", + "description": "", + "operationId": "patchExternalAuthConfigBasic", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigBasic" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigBasic" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/customAuth": { + "post": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "createExternalAccountAuthConfigCustomAuth", + "description": "", + "operationId": "createExternalAccountAuthConfigCustomAuth", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigCustomAuth" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigCustomAuth" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "patch": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "patchExternalAuthConfigCustomAuth", + "description": "", + "operationId": "patchExternalAuthConfigCustomAuth", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigCustomAuth" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigCustomAuth" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/jwt": { + "post": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "createExternalAccountAuthConfigJwt", + "description": "", + "operationId": "createExternalAccountAuthConfigJwt", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigJwt" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigJwt" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "patch": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "patchExternalAuthConfigJwt", + "description": "", + "operationId": "patchExternalAuthConfigJwt", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigJwt" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigJwt" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/oauth": { + "post": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "createExternalAccountAuthConfigOAuth", + "description": "", + "operationId": "createExternalAccountAuthConfigOAuth", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigOAuth" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigOAuth" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "patch": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "patchExternalAuthConfigOAuth", + "description": "", + "operationId": "patchExternalAuthConfigOAuth", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "authConfigId", + "in": "path", + "description": "authConfigId", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigOAuth" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthConfigOAuth" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a listing of remote http service groups for an account", + "description": "Permissions: READ on Account", + "operationId": "getRemoteHttpServiceGroupListByAccount", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "page", + "in": "query", + "description": "page", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "maxRows", + "in": "query", + "description": "maxRows", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RemoteHttpServiceGroup" + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "post": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Creates a remote http service group for an account", + "description": "Permissions: CREATE on Account", + "operationId": "createHTTPServiceGroup", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpServiceGroup" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpServiceGroup" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/withChildren": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a listing of remote http service groups with related data", + "description": "Permissions: READ on Account", + "operationId": "getRemoteHttpServiceGroupListByAccountWithChildren", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "includePermissions", + "in": "query", + "description": "includePermissions", + "required": false, + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RemoteHttpServiceGroup" + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a remote http service group for an account", + "description": "Permissions: READ on HTTP Service Group", + "operationId": "getRemoteHttpServiceGroup", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpServiceGroup" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "put": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Updates a remote http service group", + "description": "Permissions: UPDATE on HTTP Service Group", + "operationId": "updateHTTPServiceGroup", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpServiceGroup" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpServiceGroup" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a listing of remote http services", + "description": "Permissions: READ on Web Service Group", + "operationId": "getRemoteHttpServiceList", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "page", + "in": "query", + "description": "page", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "maxRows", + "in": "query", + "description": "maxRows", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RemoteHttpService" + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "post": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a remote http service", + "description": "Permissions: CREATE on Web Service Group", + "operationId": "createRemoteHttpService", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpService" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpService" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a remote http service", + "description": "Permissions: READ on Web Service", + "operationId": "getRemoteHttpService", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpService" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "put": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a remote http service", + "description": "Permissions: UPDATE on Web Service", + "operationId": "updateRemoteHttpService", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpService" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpService" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/clone": { + "post": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Clones a remote http service", + "description": "Permissions: READ on Web Service (Permission Override), CREATE on Web Service Group", + "operationId": "cloneRemoteHttpService", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "newName", + "in": "query", + "description": "newName", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpService" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a listing of remote http service inputs for an account", + "description": "Permissions: READ on HTTP Service", + "operationId": "getRemoteHttpServiceInputList", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RemoteHttpServiceInput" + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "post": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a remote http service input for an account", + "description": "Permissions: UPDATE on HTTP Service", + "operationId": "saveRemoteHttpServiceInputs", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RemoteHttpServiceInput" + } + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RemoteHttpServiceInput" + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs/{inputId}": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a remote http service input for an account", + "description": "Permissions: READ on HTTP Service", + "operationId": "getRemoteHttpServiceInput", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "inputId", + "in": "path", + "description": "inputId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteHttpServiceInput" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a remote http service input for an account", + "description": "Permissions: UPDATE on HTTP Service", + "operationId": "deleteRemoteHttpServiceInput", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "inputId", + "in": "path", + "description": "inputId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "boolean" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/setIsActive": { + "put": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Set remote HTTP service active state", + "description": "Permissions: UPDATE on Web Service", + "operationId": "setRemoteHttpServiceIsEnabled", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "pattern": "[0-9]+" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ActiveStateBoolean" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "boolean" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v2/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a listing of remote http services", + "description": "Permissions: READ on Web Service Group", + "operationId": "getRemoteHttpServiceListUsingGET", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "page", + "in": "query", + "description": "page", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "maxRows", + "in": "query", + "description": "maxRows", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExternalHttpService" + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "post": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "createRemoteHttpServiceUsingPOST", + "description": "", + "operationId": "createRemoteHttpServiceUsingPOST", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalHttpService" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalHttpService" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/v2/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}": { + "get": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "Returns a remote http service", + "description": "Permissions: READ on Web Service", + "operationId": "getRemoteHttpServiceUsingGET", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalHttpService" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "put": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "updateRemoteHttpServiceUsingPUT", + "description": "", + "operationId": "updateRemoteHttpServiceUsingPUT", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalHttpService" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalHttpService" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "tags": [ + "Remote HTTP Services" + ], + "summary": "deleteRemoteHttpServiceUsingDELETE", + "description": "", + "operationId": "deleteRemoteHttpServiceUsingDELETE", + "parameters": [ + { + "name": "accountId", + "in": "path", + "description": "accountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "serviceGroupId", + "in": "path", + "description": "serviceGroupId", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "serviceId", + "in": "path", + "description": "serviceId", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "default": { + "description": "successful operation" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } } }, "servers": [ @@ -26697,4 +29213,4 @@ ] } ] -} \ No newline at end of file +} From 87e8035b7c8c23a95722b758f5703d34a0abc458 Mon Sep 17 00:00:00 2001 From: ajkamen Date: Wed, 27 May 2026 10:49:16 -0700 Subject: [PATCH 02/13] docs: fix remote HTTP auth references Point external auth guidance at the published admin auth config endpoints used by the generated reference spec. Co-authored-by: Cursor --- docs/integration/remote-http-services.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/integration/remote-http-services.md b/docs/integration/remote-http-services.md index 9590549..cf69aaa 100644 --- a/docs/integration/remote-http-services.md +++ b/docs/integration/remote-http-services.md @@ -59,10 +59,12 @@ External auth configurations store reusable authentication settings for remote s | Operation | Method and Path | API Reference | | --- | --- | --- | -| List auth configs | `GET /voice/api/cx/admin/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/external/authConfigs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getAccountAuthConfigs) | -| Create auth config | `POST /voice/api/cx/admin/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/external/authConfigs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createAccountAuthConfig) | -| Update auth config | `PUT /voice/api/cx/admin/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/external/authConfigs/{configId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/updateAccountAuthConfig) | -| Delete auth config | `DELETE /voice/api/cx/admin/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/external/authConfigs/{configId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/deleteAccountAuthConfig) | +| List auth configs | `GET /voice/api/v1/admin/accounts/{accountId}/external/authConfigs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getExternalAuthConfigsList) | +| Get auth config | `GET /voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getExternalAuthConfigById) | +| Delete auth config | `DELETE /voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/deleteExternalAuthConfigById) | +| Create API key auth | `POST /voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/apiKey` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createExternalAccountAuthConfigApiKey) | +| Create basic auth | `POST /voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/basic` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createExternalAccountAuthConfigBasic) | +| Create OAuth auth | `POST /voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/oauth` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createExternalAccountAuthConfigOAuth) | ## Recommended Workflow From 185d43523e2ad6a7835ed78524c9328c5f6eb595 Mon Sep 17 00:00:00 2001 From: ajkamen Date: Wed, 27 May 2026 10:49:25 -0700 Subject: [PATCH 03/13] docs: align remote-http-services-api reference links --- specs/engage-voice_openapi3.json | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/specs/engage-voice_openapi3.json b/specs/engage-voice_openapi3.json index 48029bd..ac84c16 100644 --- a/specs/engage-voice_openapi3.json +++ b/specs/engage-voice_openapi3.json @@ -27621,7 +27621,7 @@ ], "summary": "Returns a listing of remote http service groups for an account", "description": "Permissions: READ on Account", - "operationId": "getRemoteHttpServiceGroupListByAccount", + "operationId": "getHttpServiceGroupList", "parameters": [ { "name": "accountId", @@ -27690,7 +27690,7 @@ ], "summary": "Creates a remote http service group for an account", "description": "Permissions: CREATE on Account", - "operationId": "createHTTPServiceGroup", + "operationId": "createHttpServiceGroup", "parameters": [ { "name": "accountId", @@ -27748,7 +27748,7 @@ ], "summary": "Returns a listing of remote http service groups with related data", "description": "Permissions: READ on Account", - "operationId": "getRemoteHttpServiceGroupListByAccountWithChildren", + "operationId": "getHttpServiceGroupListWithChildren", "parameters": [ { "name": "accountId", @@ -27809,7 +27809,7 @@ ], "summary": "Returns a remote http service group for an account", "description": "Permissions: READ on HTTP Service Group", - "operationId": "getRemoteHttpServiceGroup", + "operationId": "getHttpServiceGroup", "parameters": [ { "name": "accountId", @@ -27866,7 +27866,7 @@ ], "summary": "Updates a remote http service group", "description": "Permissions: UPDATE on HTTP Service Group", - "operationId": "updateHTTPServiceGroup", + "operationId": "updateHttpServiceGroup", "parameters": [ { "name": "accountId", @@ -27935,7 +27935,7 @@ ], "summary": "Returns a listing of remote http services", "description": "Permissions: READ on Web Service Group", - "operationId": "getRemoteHttpServiceList", + "operationId": "getHttpServiceList", "parameters": [ { "name": "accountId", @@ -28015,7 +28015,7 @@ ], "summary": "Returns a remote http service", "description": "Permissions: CREATE on Web Service Group", - "operationId": "createRemoteHttpService", + "operationId": "createHttpService", "parameters": [ { "name": "accountId", @@ -28084,7 +28084,7 @@ ], "summary": "Returns a remote http service", "description": "Permissions: READ on Web Service", - "operationId": "getRemoteHttpService", + "operationId": "getHttpService", "parameters": [ { "name": "accountId", @@ -28152,7 +28152,7 @@ ], "summary": "Returns a remote http service", "description": "Permissions: UPDATE on Web Service", - "operationId": "updateRemoteHttpService", + "operationId": "updateHttpService", "parameters": [ { "name": "accountId", @@ -28232,7 +28232,7 @@ ], "summary": "Clones a remote http service", "description": "Permissions: READ on Web Service (Permission Override), CREATE on Web Service Group", - "operationId": "cloneRemoteHttpService", + "operationId": "cloneHttpService", "parameters": [ { "name": "accountId", @@ -28311,7 +28311,7 @@ ], "summary": "Returns a listing of remote http service inputs for an account", "description": "Permissions: READ on HTTP Service", - "operationId": "getRemoteHttpServiceInputList", + "operationId": "getHttpServiceInputList", "parameters": [ { "name": "accountId", @@ -28382,7 +28382,7 @@ ], "summary": "Returns a remote http service input for an account", "description": "Permissions: UPDATE on HTTP Service", - "operationId": "saveRemoteHttpServiceInputs", + "operationId": "createHttpServiceInput", "parameters": [ { "name": "accountId", @@ -28468,7 +28468,7 @@ ], "summary": "Returns a remote http service input for an account", "description": "Permissions: READ on HTTP Service", - "operationId": "getRemoteHttpServiceInput", + "operationId": "getHttpServiceInput", "parameters": [ { "name": "accountId", @@ -28547,7 +28547,7 @@ ], "summary": "Returns a remote http service input for an account", "description": "Permissions: UPDATE on HTTP Service", - "operationId": "deleteRemoteHttpServiceInput", + "operationId": "deleteHttpServiceInput", "parameters": [ { "name": "accountId", @@ -28628,7 +28628,7 @@ ], "summary": "Set remote HTTP service active state", "description": "Permissions: UPDATE on Web Service", - "operationId": "setRemoteHttpServiceIsEnabled", + "operationId": "setHttpServiceIsActive", "parameters": [ { "name": "accountId", From f4db76735f4be4ad8222ed86f4889fbfc15f720e Mon Sep 17 00:00:00 2001 From: ajkamen Date: Wed, 27 May 2026 11:07:48 -0700 Subject: [PATCH 04/13] docs: expand remote HTTP service guide Add workflow context, payload examples, resource notes, common errors, and provisioning sample code. Co-authored-by: Cursor --- docs/integration/remote-http-services.md | 114 +++++++++++++++++++++++ 1 file changed, 114 insertions(+) diff --git a/docs/integration/remote-http-services.md b/docs/integration/remote-http-services.md index cf69aaa..801af31 100644 --- a/docs/integration/remote-http-services.md +++ b/docs/integration/remote-http-services.md @@ -6,6 +6,8 @@ The Remote HTTP Service APIs let you configure outbound HTTP integrations used b Remote HTTP services define reusable external endpoints that RingCX can call from IVR, scripting, or integration workflows. They are useful when the same CRM, middleware, or data-enrichment service must be configured consistently across many queues, scripts, or sub-accounts. +IVR WWW nodes, scripting nodes, and other workflow steps reference these service definitions so the workflow does not need to duplicate endpoint URLs, headers, credentials, and input mappings. + ### Key Use Cases * **Integration Provisioning:** Create service definitions during customer onboarding. @@ -77,3 +79,115 @@ External auth configurations store reusable authentication settings for remote s !!! important Treat remote service changes like production integration changes. Validate the external endpoint, authentication, and expected response shape before activating the service in a live routing flow. + +## Request Examples + +### Create a Service Group + +`POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups` + +```json +{ + "groupName": "CRM enrichment", + "description": "Services used by inbound IVR and scripts", + "active": true +} +``` + +### Create an HTTP Service + +`POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices` + +```json +{ + "serviceName": "Lookup customer by ANI", + "description": "Returns CRM profile data for the caller", + "url": "https://api.example.com/customers/lookup", + "method": "POST", + "contentType": "application/json", + "active": false +} +``` + +### Create a Service Input + +`POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs` + +```json +{ + "inputName": "ani", + "source": "CALL", + "required": true, + "description": "Caller phone number passed to the CRM lookup" +} +``` + +### Create API Key Auth + +`POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/apiKey` + +```json +{ + "name": "CRM API key", + "apiKey": "secret-value", + "headerName": "X-API-Key" +} +``` + +## Resource Notes + +| Resource | Key Fields | Notes | +| --- | --- | --- | +| Service group | `serviceGroupId`, `groupName`, `description`, `active` | Logical container for related services. | +| HTTP service | `serviceId`, `serviceName`, `url`, `method`, `contentType`, `active` | Defines the external endpoint RingCX workflows call. | +| Service input | `inputId`, `inputName`, `source`, `required` | Maps RingCX runtime values into the request. | +| Auth config | `authConfigId`, `authType`, `name` | Stores reusable credentials for outbound calls. | + +## Common Errors + +| Status | Cause | Resolution | +| --- | --- | --- | +| `400 Bad Request` | Malformed URL, method, auth payload, or input mapping. | Validate service definitions before activating them. | +| `403 Forbidden` | User lacks integration configuration permissions. | Grant remote service and external auth permissions in the Admin portal. | +| `404 Not Found` | Service group, service, input, or auth config is not under the account. | Re-list parent resources and use IDs from the same account. | +| `409 Conflict` | Service is inactive, duplicated, or referenced by a workflow that prevents deletion. | Clone/update safely and activate only after validation. | + +## Sample Implementation (Python) + +```python +import requests + +BASE_URL = "https://ringcx.ringcentral.com/voice/api" + +def provision_remote_service(token, account_id): + headers = {"Authorization": f"Bearer {token}"} + group = requests.post( + f"{BASE_URL}/v1/admin/accounts/{account_id}/httpServiceGroups", + headers=headers, + json={"groupName": "CRM enrichment", "active": True}, + ) + group.raise_for_status() + group_id = group.json()["serviceGroupId"] + + service = requests.post( + f"{BASE_URL}/v1/admin/accounts/{account_id}/httpServiceGroups/{group_id}/httpServices", + headers=headers, + json={ + "serviceName": "Lookup customer by ANI", + "url": "https://api.example.com/customers/lookup", + "method": "POST", + "contentType": "application/json", + "active": False, + }, + ) + service.raise_for_status() + service_id = service.json()["serviceId"] + + input_response = requests.post( + f"{BASE_URL}/v1/admin/accounts/{account_id}/httpServiceGroups/{group_id}/httpServices/{service_id}/inputs", + headers=headers, + json={"inputName": "ani", "source": "CALL", "required": True}, + ) + input_response.raise_for_status() + return {"group": group.json(), "service": service.json(), "input": input_response.json()} +``` From f2e96152824a0c118ccb20f6b82f19b272f04325 Mon Sep 17 00:00:00 2001 From: ajkamen Date: Wed, 27 May 2026 11:20:21 -0700 Subject: [PATCH 05/13] docs: polish remote HTTP services guide Add two-part permissions, authorization errors, full endpoint URLs, rate-limit guidance, auth examples, and a response example. Co-authored-by: Cursor --- docs/integration/remote-http-services.md | 106 ++++++++++++++++++----- 1 file changed, 84 insertions(+), 22 deletions(-) diff --git a/docs/integration/remote-http-services.md b/docs/integration/remote-http-services.md index 801af31..52275ae 100644 --- a/docs/integration/remote-http-services.md +++ b/docs/integration/remote-http-services.md @@ -17,7 +17,25 @@ IVR WWW nodes, scripting nodes, and other workflow steps reference these service ### Required Permissions & Scopes -Your application needs the `ReadAccounts` OAuth scope. The authenticating user must have platform permissions to read and update remote HTTP service groups, HTTP services, service inputs, and external auth configurations. +#### 1. Configure OAuth Scopes + +To authenticate, your application must be configured with the following permission in the [Developer Portal](https://developers.ringcentral.com/my-account.html#/applications): + +* **`ReadAccounts`**: Required to validate account context and access RingCX integration configuration APIs. + +#### 2. Enable RingCX Admin Access + +In the RingCX Admin portal, the authenticating user must have permission to read and update remote HTTP service groups, HTTP services, service inputs, and external auth configurations. + +!!! warning "Common Authorization Errors" + If the OAuth token is valid but the RingCX user lacks integration configuration access, the API returns an error similar to: + ```json + { + "errorCode": "access.denied.exception", + "generalMessage": "You do not have permission to access this resource", + "timestamp": 1611847650696 + } + ``` ## Manage Service Groups @@ -25,11 +43,11 @@ Service groups organize related remote HTTP services. | Operation | Method and Path | API Reference | | --- | --- | --- | -| List groups | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceGroupList) | -| Create group | `POST /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createHttpServiceGroup) | -| List groups with services | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/withChildren` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceGroupListWithChildren) | -| Get group | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceGroup) | -| Update group | `PUT /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/updateHttpServiceGroup) | +| List groups | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceGroupList) | +| Create group | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createHttpServiceGroup) | +| List groups with services | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/withChildren` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceGroupListWithChildren) | +| Get group | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceGroup) | +| Update group | `PUT https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/updateHttpServiceGroup) | ## Manage HTTP Services @@ -37,12 +55,12 @@ HTTP service records describe the external endpoint and how RingCX calls it. | Operation | Method and Path | API Reference | | --- | --- | --- | -| List services | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceList) | -| Create service | `POST /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createHttpService) | -| Get service | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpService) | -| Update service | `PUT /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/updateHttpService) | -| Clone service | `POST /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/clone` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/cloneHttpService) | -| Set active state | `PUT /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/setIsActive` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/setHttpServiceIsActive) | +| List services | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceList) | +| Create service | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createHttpService) | +| Get service | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpService) | +| Update service | `PUT https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/updateHttpService) | +| Clone service | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/clone` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/cloneHttpService) | +| Set active state | `PUT https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/setIsActive` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/setHttpServiceIsActive) | ## Configure Service Inputs @@ -50,10 +68,10 @@ Inputs define the values RingCX passes into the remote service request. Keep the | Operation | Method and Path | API Reference | | --- | --- | --- | -| List inputs | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceInputList) | -| Create input | `POST /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createHttpServiceInput) | -| Get input | `GET /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs/{inputId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceInput) | -| Delete input | `DELETE /voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs/{inputId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/deleteHttpServiceInput) | +| List inputs | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceInputList) | +| Create input | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createHttpServiceInput) | +| Get input | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs/{inputId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getHttpServiceInput) | +| Delete input | `DELETE https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs/{inputId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/deleteHttpServiceInput) | ## External Auth Configurations @@ -61,12 +79,12 @@ External auth configurations store reusable authentication settings for remote s | Operation | Method and Path | API Reference | | --- | --- | --- | -| List auth configs | `GET /voice/api/v1/admin/accounts/{accountId}/external/authConfigs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getExternalAuthConfigsList) | -| Get auth config | `GET /voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getExternalAuthConfigById) | -| Delete auth config | `DELETE /voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/deleteExternalAuthConfigById) | -| Create API key auth | `POST /voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/apiKey` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createExternalAccountAuthConfigApiKey) | -| Create basic auth | `POST /voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/basic` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createExternalAccountAuthConfigBasic) | -| Create OAuth auth | `POST /voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/oauth` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createExternalAccountAuthConfigOAuth) | +| List auth configs | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getExternalAuthConfigsList) | +| Get auth config | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/getExternalAuthConfigById) | +| Delete auth config | `DELETE https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/deleteExternalAuthConfigById) | +| Create API key auth | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/apiKey` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createExternalAccountAuthConfigApiKey) | +| Create basic auth | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/basic` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createExternalAccountAuthConfigBasic) | +| Create OAuth auth | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/oauth` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Remote-HTTP-Services/createExternalAccountAuthConfigOAuth) | ## Recommended Workflow @@ -80,6 +98,9 @@ External auth configurations store reusable authentication settings for remote s !!! important Treat remote service changes like production integration changes. Validate the external endpoint, authentication, and expected response shape before activating the service in a live routing flow. +!!! important "Rate Limiting & Stability" + Remote HTTP service changes can affect live IVR and scripting flows. Batch provisioning updates, activate services only after validation, and use exponential backoff on `429 Too Many Requests` responses. + ## Request Examples ### Create a Service Group @@ -134,6 +155,47 @@ External auth configurations store reusable authentication settings for remote s } ``` +### Create Basic Auth + +`POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/basic` + +```json +{ + "name": "CRM basic auth", + "username": "ringcx-service", + "password": "secret-value" +} +``` + +### Create OAuth Auth + +`POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/oauth` + +```json +{ + "name": "CRM OAuth", + "tokenUrl": "https://auth.example.com/oauth/token", + "clientId": "ringcx-client", + "clientSecret": "secret-value", + "grantType": "client_credentials" +} +``` + +### Example HTTP Service Response + +```json +{ + "serviceId": 4567, + "serviceGroupId": 1234, + "serviceName": "Lookup customer by ANI", + "description": "Returns CRM profile data for the caller", + "url": "https://api.example.com/customers/lookup", + "method": "POST", + "contentType": "application/json", + "active": false +} +``` + ## Resource Notes | Resource | Key Fields | Notes | From 5e4760a7b4d0f111e7a2be912ec3749d8da01320 Mon Sep 17 00:00:00 2001 From: ajkamen Date: Mon, 1 Jun 2026 11:04:19 -0700 Subject: [PATCH 06/13] docs(remote-http-services): align article with swagger schemas Replace invented field names in the request/response examples, resource notes table, and Python sample so they match the real RemoteHttpServiceGroup / RemoteHttpService / RemoteHttpServiceInput / AuthConfig* definitions: - Service group: groupName + isDefault (not description/active). - HTTP service: serviceType, serviceDescription, httpServiceConfig or soapEndpoint + soap* fields, authConfigId, isEnabled, isDebug, enableMappings. - Service input: name, type, value, simpleDataType, rank. - Auth-config bodies: providerName + authType. OAuth body uses secret (not clientSecret) and CLIENT_CREDENTIALS grant type. Also rewrite the permissions section so it matches the literal "Permissions: ..." descriptions on each operation. Co-authored-by: Cursor --- docs/integration/remote-http-services.md | 111 +++++++++++++++-------- 1 file changed, 71 insertions(+), 40 deletions(-) diff --git a/docs/integration/remote-http-services.md b/docs/integration/remote-http-services.md index 52275ae..8edc8f7 100644 --- a/docs/integration/remote-http-services.md +++ b/docs/integration/remote-http-services.md @@ -25,7 +25,7 @@ To authenticate, your application must be configured with the following permissi #### 2. Enable RingCX Admin Access -In the RingCX Admin portal, the authenticating user must have permission to read and update remote HTTP service groups, HTTP services, service inputs, and external auth configurations. +The authenticating user must have RingCX permissions that match the action being performed. Each endpoint in this set declares the permission it requires (`READ on Account`, `CREATE on Account`, `READ`, `UPDATE`, `DELETE`, etc., on the Remote HTTP Service Group, HTTP Service, HTTP Service Input, or External Auth Config resource). Grant the corresponding role permissions in the **RingCX Admin Portal** under **Users & Permissions**. !!! warning "Common Authorization Errors" If the OAuth token is valid but the RingCX user lacks integration configuration access, the API returns an error similar to: @@ -110,8 +110,7 @@ External auth configurations store reusable authentication settings for remote s ```json { "groupName": "CRM enrichment", - "description": "Services used by inbound IVR and scripts", - "active": true + "isDefault": false } ``` @@ -119,14 +118,18 @@ External auth configurations store reusable authentication settings for remote s `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices` +The `serviceType` enum controls how RingCX calls the remote endpoint. For SOAP services populate `soapEndpoint` plus the SOAP-specific fields (`soapPortname`, `soapServicename`, `soapOperationname`, `soapAction`, `targetNamespace`); for HTTP services populate `httpServiceConfig` with the full HTTP request specification (URL, headers, etc.). Reusable credentials are linked through `authConfigId`. + ```json { - "serviceName": "Lookup customer by ANI", - "description": "Returns CRM profile data for the caller", - "url": "https://api.example.com/customers/lookup", - "method": "POST", - "contentType": "application/json", - "active": false + "accountId": "123456", + "serviceType": "HTTP_POST", + "serviceDescription": "Lookup customer by ANI", + "httpServiceConfig": "{\"url\":\"https://api.example.com/customers/lookup\",\"headers\":{\"Content-Type\":\"application/json\"}}", + "authConfigId": "60629848-0ddf-4757-8868-de5b76d54bb7", + "isEnabled": false, + "isDebug": false, + "enableMappings": true } ``` @@ -136,10 +139,11 @@ External auth configurations store reusable authentication settings for remote s ```json { - "inputName": "ani", - "source": "CALL", - "required": true, - "description": "Caller phone number passed to the CRM lookup" + "name": "ani", + "type": "PARAMETER", + "simpleDataType": "STRING", + "value": "", + "rank": "0" } ``` @@ -147,11 +151,14 @@ External auth configurations store reusable authentication settings for remote s `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/apiKey` +`providerName` and `apiKey` are required. `authConfigId` is supplied as a path parameter and does not need to appear in the body for create operations. + ```json { - "name": "CRM API key", - "apiKey": "secret-value", - "headerName": "X-API-Key" + "providerName": "CRM API key", + "description": "Service account key for the CRM lookup integration", + "authType": "APIKEY", + "apiKey": "secret-value" } ``` @@ -159,9 +166,13 @@ External auth configurations store reusable authentication settings for remote s `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/basic` +`providerName`, `username`, and `password` are required. + ```json { - "name": "CRM basic auth", + "providerName": "CRM basic auth", + "description": "Basic credentials for CRM lookup", + "authType": "BASIC", "username": "ringcx-service", "password": "secret-value" } @@ -171,13 +182,18 @@ External auth configurations store reusable authentication settings for remote s `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/oauth` +`providerName`, `clientId`, `secret`, `tokenUrl`, and `grantType` are required. The client secret field is named `secret` (not `clientSecret`). + ```json { - "name": "CRM OAuth", - "tokenUrl": "https://auth.example.com/oauth/token", + "providerName": "CRM OAuth", + "description": "OAuth credentials for CRM lookup", + "authType": "OAUTH", + "grantType": "CLIENT_CREDENTIALS", "clientId": "ringcx-client", - "clientSecret": "secret-value", - "grantType": "client_credentials" + "secret": "secret-value", + "tokenUrl": "https://auth.example.com/oauth/token", + "clientCredentialsSupplyIn": "BODY" } ``` @@ -186,13 +202,15 @@ External auth configurations store reusable authentication settings for remote s ```json { "serviceId": 4567, - "serviceGroupId": 1234, - "serviceName": "Lookup customer by ANI", - "description": "Returns CRM profile data for the caller", - "url": "https://api.example.com/customers/lookup", - "method": "POST", - "contentType": "application/json", - "active": false + "accountId": "123456", + "serviceType": "HTTP_POST", + "serviceDescription": "Lookup customer by ANI", + "httpServiceConfig": "{\"url\":\"https://api.example.com/customers/lookup\",\"headers\":{\"Content-Type\":\"application/json\"}}", + "authConfigId": "60629848-0ddf-4757-8868-de5b76d54bb7", + "isEnabled": false, + "isDebug": false, + "enableMappings": true, + "permissions": ["READ", "UPDATE"] } ``` @@ -200,10 +218,10 @@ External auth configurations store reusable authentication settings for remote s | Resource | Key Fields | Notes | | --- | --- | --- | -| Service group | `serviceGroupId`, `groupName`, `description`, `active` | Logical container for related services. | -| HTTP service | `serviceId`, `serviceName`, `url`, `method`, `contentType`, `active` | Defines the external endpoint RingCX workflows call. | -| Service input | `inputId`, `inputName`, `source`, `required` | Maps RingCX runtime values into the request. | -| Auth config | `authConfigId`, `authType`, `name` | Stores reusable credentials for outbound calls. | +| Service group (`RemoteHttpServiceGroup`) | `serviceGroupId`, `groupName`, `isDefault`, `services` | Logical container for related services. There is no description or active flag on the group itself. | +| HTTP service (`RemoteHttpService`) | `serviceId`, `accountId`, `serviceType`, `serviceDescription`, `soapEndpoint`/`httpServiceConfig`, `authConfigId`, `isEnabled`, `isDebug`, `enableMappings` | `serviceType` is one of `SOAP`, `HTTP_POST`, `HTTP_GET`, `HTTP`. SOAP services use `soapEndpoint` plus the `soap*` and `targetNamespace` fields; HTTP services use `httpServiceConfig`. | +| Service input (`RemoteHttpServiceInput`) | `inputId`, `name`, `type`, `value`, `simpleDataType`, `rank` | Maps RingCX runtime values into the request. | +| Auth config | `authConfigId`, `authType` (`APIKEY`/`JWT`/`BASIC`/`OAUTH`/`CUSTOM_AUTH`), `providerName`, `description` | Stores reusable credentials for outbound calls. Auth-type-specific fields live on `AuthConfigApiKey`, `AuthConfigBasic`, `AuthConfigOAuth`, `AuthConfigJwt`, and `AuthConfigCustomAuth`. | ## Common Errors @@ -217,16 +235,18 @@ External auth configurations store reusable authentication settings for remote s ## Sample Implementation (Python) ```python +import json import requests BASE_URL = "https://ringcx.ringcentral.com/voice/api" -def provision_remote_service(token, account_id): +def provision_remote_service(token, account_id, auth_config_id): headers = {"Authorization": f"Bearer {token}"} + group = requests.post( f"{BASE_URL}/v1/admin/accounts/{account_id}/httpServiceGroups", headers=headers, - json={"groupName": "CRM enrichment", "active": True}, + json={"groupName": "CRM enrichment", "isDefault": False}, ) group.raise_for_status() group_id = group.json()["serviceGroupId"] @@ -235,11 +255,16 @@ def provision_remote_service(token, account_id): f"{BASE_URL}/v1/admin/accounts/{account_id}/httpServiceGroups/{group_id}/httpServices", headers=headers, json={ - "serviceName": "Lookup customer by ANI", - "url": "https://api.example.com/customers/lookup", - "method": "POST", - "contentType": "application/json", - "active": False, + "accountId": account_id, + "serviceType": "HTTP_POST", + "serviceDescription": "Lookup customer by ANI", + "httpServiceConfig": json.dumps({ + "url": "https://api.example.com/customers/lookup", + "headers": {"Content-Type": "application/json"}, + }), + "authConfigId": auth_config_id, + "isEnabled": False, + "enableMappings": True, }, ) service.raise_for_status() @@ -248,7 +273,13 @@ def provision_remote_service(token, account_id): input_response = requests.post( f"{BASE_URL}/v1/admin/accounts/{account_id}/httpServiceGroups/{group_id}/httpServices/{service_id}/inputs", headers=headers, - json={"inputName": "ani", "source": "CALL", "required": True}, + json={ + "name": "ani", + "type": "PARAMETER", + "simpleDataType": "STRING", + "value": "", + "rank": "0", + }, ) input_response.raise_for_status() return {"group": group.json(), "service": service.json(), "input": input_response.json()} From 673d9ed909b1555188439d4303226d1bd7348f2e Mon Sep 17 00:00:00 2001 From: ajkamen Date: Mon, 1 Jun 2026 11:32:19 -0700 Subject: [PATCH 07/13] docs: merge remote HTTP input schema --- docs/integration/remote-http-services.md | 36 ++++++++++++++---------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/integration/remote-http-services.md b/docs/integration/remote-http-services.md index 8edc8f7..23dc6b4 100644 --- a/docs/integration/remote-http-services.md +++ b/docs/integration/remote-http-services.md @@ -138,15 +138,19 @@ The `serviceType` enum controls how RingCX calls the remote endpoint. For SOAP s `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs` ```json -{ - "name": "ani", - "type": "PARAMETER", - "simpleDataType": "STRING", - "value": "", - "rank": "0" -} +[ + { + "name": "ani", + "type": "PARAMETER", + "simpleDataType": "STRING", + "value": "", + "rank": "0" + } +] ``` +The service input save endpoint accepts an array of `RemoteHttpServiceInput` objects. + ### Create API Key Auth `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/apiKey` @@ -220,7 +224,7 @@ The `serviceType` enum controls how RingCX calls the remote endpoint. For SOAP s | --- | --- | --- | | Service group (`RemoteHttpServiceGroup`) | `serviceGroupId`, `groupName`, `isDefault`, `services` | Logical container for related services. There is no description or active flag on the group itself. | | HTTP service (`RemoteHttpService`) | `serviceId`, `accountId`, `serviceType`, `serviceDescription`, `soapEndpoint`/`httpServiceConfig`, `authConfigId`, `isEnabled`, `isDebug`, `enableMappings` | `serviceType` is one of `SOAP`, `HTTP_POST`, `HTTP_GET`, `HTTP`. SOAP services use `soapEndpoint` plus the `soap*` and `targetNamespace` fields; HTTP services use `httpServiceConfig`. | -| Service input (`RemoteHttpServiceInput`) | `inputId`, `name`, `type`, `value`, `simpleDataType`, `rank` | Maps RingCX runtime values into the request. | +| Service input (`RemoteHttpServiceInput`) | `inputId`, `name`, `type`, `value`, `simpleDataType`, `rank` | Maps RingCX runtime values into the request. Inputs are saved as an array. | | Auth config | `authConfigId`, `authType` (`APIKEY`/`JWT`/`BASIC`/`OAUTH`/`CUSTOM_AUTH`), `providerName`, `description` | Stores reusable credentials for outbound calls. Auth-type-specific fields live on `AuthConfigApiKey`, `AuthConfigBasic`, `AuthConfigOAuth`, `AuthConfigJwt`, and `AuthConfigCustomAuth`. | ## Common Errors @@ -273,13 +277,15 @@ def provision_remote_service(token, account_id, auth_config_id): input_response = requests.post( f"{BASE_URL}/v1/admin/accounts/{account_id}/httpServiceGroups/{group_id}/httpServices/{service_id}/inputs", headers=headers, - json={ - "name": "ani", - "type": "PARAMETER", - "simpleDataType": "STRING", - "value": "", - "rank": "0", - }, + json=[ + { + "name": "ani", + "type": "PARAMETER", + "simpleDataType": "STRING", + "value": "", + "rank": "0", + } + ], ) input_response.raise_for_status() return {"group": group.json(), "service": service.json(), "input": input_response.json()} From d3db3a6fc78486aa562d2bee9a062cbde32ce89b Mon Sep 17 00:00:00 2001 From: ajkamen Date: Wed, 10 Jun 2026 15:31:46 -0700 Subject: [PATCH 08/13] docs: organize remote HTTP API reference tags Split the branch-added remote HTTP operations into Integration subcategories for service groups, services, service inputs, and external auth configurations, and replace method-name summaries with readable sidebar labels. --- specs/engage-voice_openapi3.json | 130 +++++++++++++++++-------------- 1 file changed, 73 insertions(+), 57 deletions(-) diff --git a/specs/engage-voice_openapi3.json b/specs/engage-voice_openapi3.json index ac84c16..0cf1000 100644 --- a/specs/engage-voice_openapi3.json +++ b/specs/engage-voice_openapi3.json @@ -26715,9 +26715,9 @@ "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs": { "get": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "getExternalAuthConfigsList", + "summary": "List external auth configurations", "description": "", "operationId": "getExternalAuthConfigsList", "parameters": [ @@ -26783,9 +26783,9 @@ "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/oauth/info": { "get": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "getExternalAccountAuthConfigOauthInfo", + "summary": "Get external auth OAuth metadata", "description": "", "operationId": "getExternalAccountAuthConfigOauthInfo", "parameters": [ @@ -26840,9 +26840,9 @@ "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}": { "get": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "getExternalAuthConfigById", + "summary": "Get external auth configuration", "description": "", "operationId": "getExternalAuthConfigById", "parameters": [ @@ -26896,9 +26896,9 @@ }, "delete": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "deleteExternalAuthConfigById", + "summary": "Delete external auth configuration", "description": "", "operationId": "deleteExternalAuthConfigById", "parameters": [ @@ -26947,9 +26947,9 @@ "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/apiKey": { "post": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "createExternalAccountAuthConfigApiKey", + "summary": "Create API key external auth configuration", "description": "", "operationId": "createExternalAccountAuthConfigApiKey", "parameters": [ @@ -27013,9 +27013,9 @@ }, "patch": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "patchExternalAuthConfigApiKey", + "summary": "Update API key external auth configuration", "description": "", "operationId": "patchExternalAuthConfigApiKey", "parameters": [ @@ -27081,9 +27081,9 @@ "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/basic": { "post": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "createExternalAccountAuthConfigBasic", + "summary": "Create basic external auth configuration", "description": "", "operationId": "createExternalAccountAuthConfigBasic", "parameters": [ @@ -27147,9 +27147,9 @@ }, "patch": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "patchExternalAuthConfigBasic", + "summary": "Update basic external auth configuration", "description": "", "operationId": "patchExternalAuthConfigBasic", "parameters": [ @@ -27215,9 +27215,9 @@ "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/customAuth": { "post": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "createExternalAccountAuthConfigCustomAuth", + "summary": "Create custom external auth configuration", "description": "", "operationId": "createExternalAccountAuthConfigCustomAuth", "parameters": [ @@ -27281,9 +27281,9 @@ }, "patch": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "patchExternalAuthConfigCustomAuth", + "summary": "Update custom external auth configuration", "description": "", "operationId": "patchExternalAuthConfigCustomAuth", "parameters": [ @@ -27349,9 +27349,9 @@ "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/jwt": { "post": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "createExternalAccountAuthConfigJwt", + "summary": "Create JWT external auth configuration", "description": "", "operationId": "createExternalAccountAuthConfigJwt", "parameters": [ @@ -27415,9 +27415,9 @@ }, "patch": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "patchExternalAuthConfigJwt", + "summary": "Update JWT external auth configuration", "description": "", "operationId": "patchExternalAuthConfigJwt", "parameters": [ @@ -27483,9 +27483,9 @@ "/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/oauth": { "post": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "createExternalAccountAuthConfigOAuth", + "summary": "Create OAuth external auth configuration", "description": "", "operationId": "createExternalAccountAuthConfigOAuth", "parameters": [ @@ -27549,9 +27549,9 @@ }, "patch": { "tags": [ - "Remote HTTP Services" + "External Auth Configurations" ], - "summary": "patchExternalAuthConfigOAuth", + "summary": "Update OAuth external auth configuration", "description": "", "operationId": "patchExternalAuthConfigOAuth", "parameters": [ @@ -27617,9 +27617,9 @@ "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups": { "get": { "tags": [ - "Remote HTTP Services" + "Remote HTTP Service Groups" ], - "summary": "Returns a listing of remote http service groups for an account", + "summary": "List remote HTTP service groups", "description": "Permissions: READ on Account", "operationId": "getHttpServiceGroupList", "parameters": [ @@ -27686,9 +27686,9 @@ }, "post": { "tags": [ - "Remote HTTP Services" + "Remote HTTP Service Groups" ], - "summary": "Creates a remote http service group for an account", + "summary": "Create remote HTTP service group", "description": "Permissions: CREATE on Account", "operationId": "createHttpServiceGroup", "parameters": [ @@ -27744,9 +27744,9 @@ "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/withChildren": { "get": { "tags": [ - "Remote HTTP Services" + "Remote HTTP Service Groups" ], - "summary": "Returns a listing of remote http service groups with related data", + "summary": "List remote HTTP service groups with services", "description": "Permissions: READ on Account", "operationId": "getHttpServiceGroupListWithChildren", "parameters": [ @@ -27805,9 +27805,9 @@ "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}": { "get": { "tags": [ - "Remote HTTP Services" + "Remote HTTP Service Groups" ], - "summary": "Returns a remote http service group for an account", + "summary": "Get remote HTTP service group", "description": "Permissions: READ on HTTP Service Group", "operationId": "getHttpServiceGroup", "parameters": [ @@ -27862,9 +27862,9 @@ }, "put": { "tags": [ - "Remote HTTP Services" + "Remote HTTP Service Groups" ], - "summary": "Updates a remote http service group", + "summary": "Update remote HTTP service group", "description": "Permissions: UPDATE on HTTP Service Group", "operationId": "updateHttpServiceGroup", "parameters": [ @@ -27933,7 +27933,7 @@ "tags": [ "Remote HTTP Services" ], - "summary": "Returns a listing of remote http services", + "summary": "List remote HTTP services", "description": "Permissions: READ on Web Service Group", "operationId": "getHttpServiceList", "parameters": [ @@ -28013,7 +28013,7 @@ "tags": [ "Remote HTTP Services" ], - "summary": "Returns a remote http service", + "summary": "Create remote HTTP service", "description": "Permissions: CREATE on Web Service Group", "operationId": "createHttpService", "parameters": [ @@ -28082,7 +28082,7 @@ "tags": [ "Remote HTTP Services" ], - "summary": "Returns a remote http service", + "summary": "Get remote HTTP service", "description": "Permissions: READ on Web Service", "operationId": "getHttpService", "parameters": [ @@ -28150,7 +28150,7 @@ "tags": [ "Remote HTTP Services" ], - "summary": "Returns a remote http service", + "summary": "Update remote HTTP service", "description": "Permissions: UPDATE on Web Service", "operationId": "updateHttpService", "parameters": [ @@ -28230,7 +28230,7 @@ "tags": [ "Remote HTTP Services" ], - "summary": "Clones a remote http service", + "summary": "Clone remote HTTP service", "description": "Permissions: READ on Web Service (Permission Override), CREATE on Web Service Group", "operationId": "cloneHttpService", "parameters": [ @@ -28307,9 +28307,9 @@ "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs": { "get": { "tags": [ - "Remote HTTP Services" + "Remote HTTP Service Inputs" ], - "summary": "Returns a listing of remote http service inputs for an account", + "summary": "List remote HTTP service inputs", "description": "Permissions: READ on HTTP Service", "operationId": "getHttpServiceInputList", "parameters": [ @@ -28378,9 +28378,9 @@ }, "post": { "tags": [ - "Remote HTTP Services" + "Remote HTTP Service Inputs" ], - "summary": "Returns a remote http service input for an account", + "summary": "Create remote HTTP service input", "description": "Permissions: UPDATE on HTTP Service", "operationId": "createHttpServiceInput", "parameters": [ @@ -28464,9 +28464,9 @@ "/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs/{inputId}": { "get": { "tags": [ - "Remote HTTP Services" + "Remote HTTP Service Inputs" ], - "summary": "Returns a remote http service input for an account", + "summary": "Get remote HTTP service input", "description": "Permissions: READ on HTTP Service", "operationId": "getHttpServiceInput", "parameters": [ @@ -28543,9 +28543,9 @@ }, "delete": { "tags": [ - "Remote HTTP Services" + "Remote HTTP Service Inputs" ], - "summary": "Returns a remote http service input for an account", + "summary": "Delete remote HTTP service input", "description": "Permissions: UPDATE on HTTP Service", "operationId": "deleteHttpServiceInput", "parameters": [ @@ -28706,7 +28706,7 @@ "tags": [ "Remote HTTP Services" ], - "summary": "Returns a listing of remote http services", + "summary": "List remote HTTP services", "description": "Permissions: READ on Web Service Group", "operationId": "getRemoteHttpServiceListUsingGET", "parameters": [ @@ -28784,7 +28784,7 @@ "tags": [ "Remote HTTP Services" ], - "summary": "createRemoteHttpServiceUsingPOST", + "summary": "Create remote HTTP service", "description": "", "operationId": "createRemoteHttpServiceUsingPOST", "parameters": [ @@ -28851,7 +28851,7 @@ "tags": [ "Remote HTTP Services" ], - "summary": "Returns a remote http service", + "summary": "Get remote HTTP service", "description": "Permissions: READ on Web Service", "operationId": "getRemoteHttpServiceUsingGET", "parameters": [ @@ -28916,7 +28916,7 @@ "tags": [ "Remote HTTP Services" ], - "summary": "updateRemoteHttpServiceUsingPUT", + "summary": "Update remote HTTP service", "description": "", "operationId": "updateRemoteHttpServiceUsingPUT", "parameters": [ @@ -28991,7 +28991,7 @@ "tags": [ "Remote HTTP Services" ], - "summary": "deleteRemoteHttpServiceUsingDELETE", + "summary": "Delete remote HTTP service", "description": "", "operationId": "deleteRemoteHttpServiceUsingDELETE", "parameters": [ @@ -29124,6 +29124,18 @@ }, { "name": "Users" + }, + { + "name": "Remote HTTP Service Groups" + }, + { + "name": "Remote HTTP Services" + }, + { + "name": "Remote HTTP Service Inputs" + }, + { + "name": "External Auth Configurations" } ], "x-tag-groups": [ @@ -29209,7 +29221,11 @@ "Integration Agent Controller", "Integration Agent Group Controller", "Integration Gate Group Controller", - "Public Integration API" + "Public Integration API", + "Remote HTTP Service Groups", + "Remote HTTP Services", + "Remote HTTP Service Inputs", + "External Auth Configurations" ] } ] From a8ca02a90ac4d4e66d6e31b2acd1b7c47d5741ef Mon Sep 17 00:00:00 2001 From: ajkamen Date: Tue, 30 Jun 2026 10:52:31 -0700 Subject: [PATCH 09/13] Fix remote HTTP service OpenAPI lint issues --- specs/engage-voice_openapi3.json | 590 ++++++++++++++++++++++++++++++- 1 file changed, 586 insertions(+), 4 deletions(-) diff --git a/specs/engage-voice_openapi3.json b/specs/engage-voice_openapi3.json index 0cf1000..4d9d655 100644 --- a/specs/engage-voice_openapi3.json +++ b/specs/engage-voice_openapi3.json @@ -3677,6 +3677,14 @@ "title": "ApplicationContext", "type": "object" }, + "ActiveStateBoolean": { + "properties": { + "isActive": { + "type": "boolean" + } + }, + "type": "object" + }, "AssignedDnis": { "properties": { "cloudRouteProfile": { @@ -3759,6 +3767,318 @@ }, "type": "object" }, + "AuthConfigApiKey": { + "required": [ + "apiKey", + "providerName" + ], + "properties": { + "apiKey": { + "type": "string" + }, + "authConfigId": { + "format": "uuid", + "type": "string" + }, + "authType": { + "enum": [ + "APIKEY", + "JWT", + "BASIC", + "OAUTH", + "CUSTOM_AUTH" + ], + "type": "string" + }, + "createdTime": { + "type": "string" + }, + "description": { + "type": "string" + }, + "providerName": { + "type": "string" + }, + "updatedTime": { + "type": "string" + } + }, + "type": "object" + }, + "AuthConfigBasic": { + "required": [ + "password", + "providerName", + "username" + ], + "properties": { + "authConfigId": { + "format": "uuid", + "type": "string" + }, + "authType": { + "enum": [ + "APIKEY", + "JWT", + "BASIC", + "OAUTH", + "CUSTOM_AUTH" + ], + "type": "string" + }, + "createdTime": { + "type": "string" + }, + "description": { + "type": "string" + }, + "password": { + "type": "string" + }, + "providerName": { + "type": "string" + }, + "updatedTime": { + "type": "string" + }, + "username": { + "type": "string" + } + }, + "type": "object" + }, + "AuthConfigCustomAuth": { + "properties": { + "allowedBaseUrl": { + "type": "string" + }, + "authConfigId": { + "format": "uuid", + "type": "string" + }, + "authType": { + "enum": [ + "APIKEY", + "JWT", + "BASIC", + "OAUTH", + "CUSTOM_AUTH" + ], + "type": "string" + }, + "createdTime": { + "type": "string" + }, + "description": { + "type": "string" + }, + "inputParams": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array" + }, + "providerName": { + "type": "string" + }, + "updatedTime": { + "type": "string" + }, + "wcgFunctionId": { + "type": "string" + } + }, + "type": "object" + }, + "AuthConfigJwt": { + "required": [ + "addTokenTo", + "algorithm", + "payload", + "providerName" + ], + "properties": { + "addTokenTo": { + "enum": [ + "REQUEST_HEADER", + "QUERY_PARAM" + ], + "type": "string" + }, + "algorithm": { + "type": "string" + }, + "authConfigId": { + "format": "uuid", + "type": "string" + }, + "authType": { + "enum": [ + "APIKEY", + "JWT", + "BASIC", + "OAUTH", + "CUSTOM_AUTH" + ], + "type": "string" + }, + "createdTime": { + "type": "string" + }, + "description": { + "type": "string" + }, + "expirationTime": { + "format": "int32", + "type": "integer" + }, + "headerPrefix": { + "type": "string" + }, + "isIncludeIssueAt": { + "type": "boolean" + }, + "isSecretEncoded": { + "type": "boolean" + }, + "jwtHeaders": { + "type": "string" + }, + "payload": { + "type": "string" + }, + "privateKey": { + "type": "string" + }, + "providerName": { + "type": "string" + }, + "queryParamName": { + "type": "string" + }, + "secret": { + "type": "string" + }, + "updatedTime": { + "type": "string" + } + }, + "type": "object" + }, + "AuthConfigList": { + "properties": { + "records": { + "items": { + "$ref": "#/components/schemas/GetExternalAuthConfigById200Response" + }, + "type": "array" + } + }, + "type": "object" + }, + "AuthConfigOAuth": { + "required": [ + "clientId", + "grantType", + "providerName", + "secret", + "tokenUrl" + ], + "properties": { + "assertion": { + "type": "string" + }, + "authConfigId": { + "format": "uuid", + "type": "string" + }, + "authType": { + "enum": [ + "APIKEY", + "JWT", + "BASIC", + "OAUTH", + "CUSTOM_AUTH" + ], + "type": "string" + }, + "clientCredentialsSupplyIn": { + "enum": [ + "BODY", + "QUERY_PARAM", + "HEADER" + ], + "type": "string" + }, + "clientId": { + "type": "string" + }, + "createdTime": { + "type": "string" + }, + "description": { + "type": "string" + }, + "grantType": { + "enum": [ + "CLIENT_CREDENTIALS", + "PASSWORD", + "REFRESH_TOKEN", + "JWT_BEARER" + ], + "type": "string" + }, + "oauthProvider": { + "enum": [ + "ADMIN_POPULATED", + "SFDC_WEBFLOW" + ], + "type": "string" + }, + "otherParameters": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array" + }, + "password": { + "type": "string" + }, + "providerName": { + "type": "string" + }, + "scope": { + "type": "string" + }, + "secret": { + "type": "string" + }, + "tokenResponse": { + "additionalProperties": true, + "type": "object" + }, + "tokenUrl": { + "type": "string" + }, + "updatedTime": { + "type": "string" + }, + "username": { + "type": "string" + } + }, + "type": "object" + }, + "AuthConfigOAuthUrl": { + "properties": { + "location": { + "type": "string" + } + }, + "type": "object" + }, "AudioFileView": { "properties": { "fileName": { @@ -11345,6 +11665,264 @@ }, "type": "object" }, + "ExternalHttpService": { + "description": "External HTTP Service", + "properties": { + "accountId": { + "format": "int32", + "type": "integer" + }, + "action": { + "type": "string" + }, + "authConfigId": { + "type": "string" + }, + "enableMappings": { + "type": "boolean" + }, + "endpoint": { + "type": "string" + }, + "httpServiceConfig": { + "properties": { + "content_type": { + "type": "string" + }, + "form_data": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array" + }, + "headers": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array" + }, + "json_data": { + "type": "string" + }, + "method": { + "enum": [ + "GET", + "POST", + "PUT", + "DELETE", + "PATCH" + ], + "type": "string" + }, + "query_params": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array" + }, + "soap_inputs": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array" + }, + "text_data": { + "type": "string" + }, + "type": { + "enum": [ + "HTTP", + "SOAP" + ], + "type": "string" + }, + "xml_data": { + "type": "string" + } + }, + "type": "object" + }, + "isDebug": { + "type": "boolean" + }, + "isEnabled": { + "type": "boolean" + }, + "operationName": { + "type": "string" + }, + "permissions": { + "items": { + "enum": [ + "CREATE", + "READ", + "UPDATE", + "DELETE", + "REPORT" + ], + "type": "string" + }, + "type": "array" + }, + "portname": { + "type": "string" + }, + "returnType": { + "type": "string" + }, + "sendAllSurveyData": { + "type": "boolean" + }, + "serviceDescription": { + "type": "string" + }, + "serviceId": { + "format": "int32", + "type": "integer" + }, + "serviceType": { + "enum": [ + "SOAP", + "HTTP_POST", + "HTTP_GET", + "HTTP" + ], + "type": "string" + }, + "servicename": { + "type": "string" + }, + "targetNamespace": { + "type": "string" + } + }, + "type": "object" + }, + "GetExternalAuthConfigById200Response": { + "properties": { + "addTokenTo": { + "enum": [ + "REQUEST_HEADER", + "QUERY_PARAM" + ], + "type": "string" + }, + "algorithm": { + "type": "string" + }, + "apiKey": { + "type": "string" + }, + "assertion": { + "type": "string" + }, + "authConfigId": { + "format": "uuid", + "type": "string" + }, + "authType": { + "enum": [ + "APIKEY", + "JWT", + "BASIC", + "OAUTH", + "CUSTOM_AUTH" + ], + "type": "string" + }, + "clientCredentialsSupplyIn": { + "enum": [ + "BODY", + "QUERY_PARAM", + "HEADER" + ], + "type": "string" + }, + "clientId": { + "type": "string" + }, + "createdTime": { + "type": "string" + }, + "description": { + "type": "string" + }, + "expirationTime": { + "format": "int32", + "type": "integer" + }, + "grantType": { + "enum": [ + "CLIENT_CREDENTIALS", + "PASSWORD", + "REFRESH_TOKEN", + "JWT_BEARER" + ], + "type": "string" + }, + "headerPrefix": { + "type": "string" + }, + "isIncludeIssueAt": { + "type": "boolean" + }, + "isSecretEncoded": { + "type": "boolean" + }, + "jwtHeaders": { + "type": "string" + }, + "oauthProvider": { + "enum": [ + "ADMIN_POPULATED", + "SFDC_WEBFLOW" + ], + "type": "string" + }, + "otherParameters": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array" + }, + "password": { + "type": "string" + }, + "payload": { + "type": "string" + }, + "privateKey": { + "type": "string" + }, + "providerName": { + "type": "string" + }, + "queryParamName": { + "type": "string" + }, + "scope": { + "type": "string" + }, + "secret": { + "type": "string" + }, + "tokenUrl": { + "type": "string" + }, + "updatedTime": { + "type": "string" + }, + "username": { + "type": "string" + } + }, + "type": "object" + }, "RemoteHttpService": { "properties": { "accountId": { @@ -29126,16 +29704,20 @@ "name": "Users" }, { - "name": "Remote HTTP Service Groups" + "name": "Remote HTTP Service Groups", + "description": "Manage groups that organize reusable remote HTTP service definitions for an account." }, { - "name": "Remote HTTP Services" + "name": "Remote HTTP Services", + "description": "Manage reusable external HTTP and SOAP service definitions used by RingCX workflows." }, { - "name": "Remote HTTP Service Inputs" + "name": "Remote HTTP Service Inputs", + "description": "Manage input mappings that pass RingCX runtime values into remote HTTP services." }, { - "name": "External Auth Configurations" + "name": "External Auth Configurations", + "description": "Manage reusable authentication configurations for outbound remote HTTP service calls." } ], "x-tag-groups": [ From 527f6661791103009bd308f5c5808d0602cbda11 Mon Sep 17 00:00:00 2001 From: ajkamen Date: Tue, 30 Jun 2026 11:00:23 -0700 Subject: [PATCH 10/13] Clean up remote HTTP service path parameter schemas --- specs/engage-voice_openapi3.json | 66 +++++++++++--------------------- 1 file changed, 22 insertions(+), 44 deletions(-) diff --git a/specs/engage-voice_openapi3.json b/specs/engage-voice_openapi3.json index 4d9d655..bdcc879 100644 --- a/specs/engage-voice_openapi3.json +++ b/specs/engage-voice_openapi3.json @@ -28406,8 +28406,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } } ], @@ -28463,8 +28462,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } } ], @@ -28532,8 +28530,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -28612,8 +28609,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } } ], @@ -28681,8 +28677,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -28692,8 +28687,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } } ], @@ -28749,8 +28743,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -28760,8 +28753,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } } ], @@ -28829,8 +28821,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -28840,8 +28831,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -28908,8 +28898,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -28919,8 +28908,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } } ], @@ -28979,8 +28967,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -28990,8 +28977,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } } ], @@ -29065,8 +29051,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -29076,8 +29061,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -29087,8 +29071,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } } ], @@ -29144,8 +29127,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -29155,8 +29137,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -29166,8 +29147,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } } ], @@ -29225,8 +29205,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } }, { @@ -29236,8 +29215,7 @@ "required": true, "schema": { "type": "integer", - "format": "int32", - "pattern": "[0-9]+" + "format": "int32" } } ], From fb2ac52367660ed7c13492429b0366194a5908ac Mon Sep 17 00:00:00 2001 From: ajkamen Date: Tue, 30 Jun 2026 13:50:37 -0700 Subject: [PATCH 11/13] Carry forward number management tag description --- specs/engage-voice_openapi3.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specs/engage-voice_openapi3.json b/specs/engage-voice_openapi3.json index 7ccb0af..2d9a9b9 100644 --- a/specs/engage-voice_openapi3.json +++ b/specs/engage-voice_openapi3.json @@ -40330,7 +40330,8 @@ "name": "RingCentral Auth" }, { - "name": "Number Management" + "name": "Number Management", + "description": "Manage DNIS pools, tracking numbers, and related phone-number assignment utilities." }, { "name": "Users" From b8bc516cdbb5b6cb7726dce57058654e8131e32e Mon Sep 17 00:00:00 2001 From: ajkamen Date: Wed, 1 Jul 2026 15:11:55 -0700 Subject: [PATCH 12/13] Restack media control docs without knowledge base --- .../workforce/call-streaming/media-control.md | 200 +++++++++++ mkdocs.yml | 1 + specs/engage-voice_openapi3.json | 340 +++++++++++++++++- 3 files changed, 540 insertions(+), 1 deletion(-) create mode 100644 docs/workforce/call-streaming/media-control.md diff --git a/docs/workforce/call-streaming/media-control.md b/docs/workforce/call-streaming/media-control.md new file mode 100644 index 0000000..258abc8 --- /dev/null +++ b/docs/workforce/call-streaming/media-control.md @@ -0,0 +1,200 @@ +# Media Control APIs + +The Media Control APIs let you start and stop audio streams for a dialog or a specific segment. Use them with call streaming integrations when media should be captured selectively instead of streamed for every eligible interaction. + +## Strategic Overview + +Call streaming profiles define where audio can be streamed. Media control endpoints let an integration decide when to start or stop streaming for a specific interaction after it has identified the dialog or segment that should be processed. + +### Key Use Cases + +* **Selective Live Analytics:** Start a stream only when a workflow determines that live analysis is needed. +* **Compliance Control:** Stop streaming before sensitive information is discussed. +* **Targeted Recording Pipelines:** Stream only selected segments to external storage or AI services. +* **Troubleshooting:** Start a temporary stream for a specific dialog during an investigation. + +### Real-Time vs. Configuration APIs + +Media control acts on live media routing. It does not create the streaming profile or historical recording after the fact. Configure call streaming first, then use these endpoints while the dialog or segment is still eligible for live streaming. + +### Required Permissions & Scopes + +#### 1. Configure OAuth Scopes + +To authenticate, your application must be configured with the following permission in the [Developer Portal](https://developers.ringcentral.com/my-account.html#/applications): + +* **`ReadAccounts`**: Required to validate account context and access RingCX integration APIs. + +#### 2. Enable RingCX Admin Access + +The account must be configured for call streaming before media-control requests can be honored. See [Call Streaming Getting Started](getting-started.md) for streaming profile setup. + +The user authenticating the app must also have access to the RingCX sub-account that owns the dialog. + +!!! warning "Common Authorization Errors" + If the application has the correct OAuth scope but the user or account is not authorized for the requested media action, the API returns an error similar to: + ```json + { + "errorCode": "access.denied.exception", + "generalMessage": "You do not have permission to access this resource", + "timestamp": 1611847650696 + } + ``` + +!!! important "Rate Limiting & Stability" + Media control requests publish start/stop events to the media-control service. Do not retry blindly after network timeouts because duplicate start events with the same `streamId` can create ambiguous state. Use a deterministic `streamId`, check your receiver logs, and retry with exponential backoff only when you know the previous request did not reach the platform. + +## Identifiers + +Media control requires interaction identifiers from another workflow. + +| Identifier | Type | Requirement | Description | +| --- | --- | --- | --- | +| `rcAccountId` | String | **Required** | RingCentral account ID. | +| `subAccountId` | String | **Required** | RingCX sub-account ID that owns the dialog. | +| `dialogId` | String | **Required** | Conversation-level identifier. Capture it from the live interaction workflow that decides to start streaming, or from interaction metadata once the interaction is available to your integration. | +| `segmentId` | String | Optional | Segment identifier when you only want to stream one segment within the dialog. Capture it from the same interaction metadata source as the dialog when segment-level routing is required. | +| `streamId` | String | **Required** | Caller-provided stream identifier. You choose this value when starting the stream and reuse it to stop the same stream. | + +!!! info + The start endpoints return `200 OK` with no response body. The `streamId` is not generated by the API; it is supplied in the start-stream request body. + +## Start a Dialog-Level Stream + +Starts a stream for the full dialog. + +`POST https://ringcx.ringcentral.com/voice/api/cx/integration/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/dialogs/{dialogId}/streams` + +**API Reference:** [Start dialog stream](https://developers.ringcentral.com/engage/voice/api-reference/Media-Control/startDialogStream) + +### Request Body + +The request body matches the `StartStreamRequestDTO` schema (with a nested `AudioStreamProperties` object). + +| Parameter | Type | Requirement | Description | +| --- | --- | --- | --- | +| `url` | String | **Required** | Destination URL that will receive the audio stream. | +| `streamId` | String | **Required** | Unique identifier you assign to this stream. Use the same value when stopping the stream. | +| `token` | String | Optional | Opaque token passed through to the media-control layer for the stream receiver. | +| `properties.encoding` | String | Optional | Requested audio encoding. The API surface treats this as free-form; use values supported by the configured streaming profile. | +| `properties.rate` | Integer (`int32`) | Optional | Requested sample rate in Hz. The API surface does not publish an enum; align it with the configured streaming profile. | +| `properties.ptime` | Integer (`int32`) | Optional | Requested packetization time in milliseconds. The API surface does not publish an enum; align it with the configured streaming profile. | + +**Example Request:** + +```json +{ + "url": "wss://media.example.com/ringcx/audio", + "streamId": "crm-case-4472-dialog", + "token": "receiver-auth-token", + "properties": { + "encoding": "PCMU", + "rate": 8000, + "ptime": 20 + } +} +``` + +### Response + +The API returns `200 OK` with an empty body after the start event is accepted for publishing. + +## Start a Segment-Level Stream + +Starts a stream for one segment within a dialog. + +`POST https://ringcx.ringcentral.com/voice/api/cx/integration/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/dialogs/{dialogId}/segments/{segmentId}/streams` + +**API Reference:** [Start segment stream](https://developers.ringcentral.com/engage/voice/api-reference/Media-Control/startSegmentStream) + +Use segment-level streaming when only one agent leg or participant segment should be sent to the receiver. + +**Example Request:** + +```json +{ + "url": "wss://media.example.com/ringcx/audio", + "streamId": "qa-review-4472-agent-segment", + "properties": { + "encoding": "PCMU", + "rate": 8000, + "ptime": 20 + } +} +``` + +## Stop a Stream + +Stop requests use the same `streamId` you supplied when starting the stream. + +| Scope | Endpoint | API Reference | +| --- | --- | --- | +| Dialog | `DELETE https://ringcx.ringcentral.com/voice/api/cx/integration/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/dialogs/{dialogId}/streams/{streamId}` | [Stop dialog stream](https://developers.ringcentral.com/engage/voice/api-reference/Media-Control/stopDialogStream) | +| Segment | `DELETE https://ringcx.ringcentral.com/voice/api/cx/integration/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/dialogs/{dialogId}/segments/{segmentId}/streams/{streamId}` | [Stop segment stream](https://developers.ringcentral.com/engage/voice/api-reference/Media-Control/stopSegmentStream) | + +### Stop Parameters + +| Parameter | Type | Requirement | Description | +| --- | --- | --- | --- | +| `rcAccountId` | String | **Required** | RingCentral account ID. | +| `subAccountId` | String | **Required** | RingCX sub-account ID. | +| `dialogId` | String | **Required** | Dialog that owns the stream. | +| `segmentId` | String | Required for segment stop | Segment that owns the stream. | +| `streamId` | String | **Required** | Stream identifier supplied when the stream was started. | + +The API returns `200 OK` with an empty body after the stop event is accepted for publishing. + +## Common Errors + +| Status | Cause | Resolution | +| --- | --- | --- | +| `400 Bad Request` | Missing `url` or `streamId`, or malformed request body. | Send both required fields and validate the JSON body. | +| `403 Forbidden` | Account/user is not authorized for media control or the sub-account mapping is invalid. | Confirm account mapping, OAuth scope, and streaming access. | +| `404 Not Found` | Dialog or segment is no longer addressable. | Start streams while the interaction is active or still eligible for media control. | +| `409 Conflict` | Duplicate or conflicting stream state. | Use deterministic `streamId` values and avoid parallel start/stop calls for the same stream. | + +## Sample Implementation (Python) + +```python +import requests + +BASE_URL = "https://ringcx.ringcentral.com/voice/api" + +def start_segment_stream(token, rc_account_id, sub_account_id, dialog_id, segment_id, stream_id): + url = ( + f"{BASE_URL}/cx/integration/v1/accounts/{rc_account_id}" + f"/sub-accounts/{sub_account_id}/dialogs/{dialog_id}" + f"/segments/{segment_id}/streams" + ) + body = { + "url": "wss://media.example.com/ringcx/audio", + "streamId": stream_id, + "properties": { + "encoding": "PCMU", + "rate": 8000, + "ptime": 20, + }, + } + response = requests.post(url, headers={"Authorization": f"Bearer {token}"}, json=body) + response.raise_for_status() + +def stop_segment_stream(token, rc_account_id, sub_account_id, dialog_id, segment_id, stream_id): + url = ( + f"{BASE_URL}/cx/integration/v1/accounts/{rc_account_id}" + f"/sub-accounts/{sub_account_id}/dialogs/{dialog_id}" + f"/segments/{segment_id}/streams/{stream_id}" + ) + response = requests.delete(url, headers={"Authorization": f"Bearer {token}"}) + response.raise_for_status() +``` + +## Recommended Workflow + +1. Configure the streaming profile as described in [Getting Started](getting-started.md). +2. Obtain the `dialogId` and, if needed, the `segmentId` for the interaction. +3. Generate a deterministic `streamId` in your system. +4. Start a dialog-level or segment-level stream with your receiver URL. +5. Stop the stream with the matching `streamId` when media capture is no longer needed. + +!!! warning + Media control changes affect live audio handling. Confirm consent, retention, and compliance requirements before starting streams automatically. diff --git a/mkdocs.yml b/mkdocs.yml index 89a6dae..4b6f8bf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -87,6 +87,7 @@ nav: - 'Creating an Event': notifications/wfm/configure-wfm.md - 'Event Payload': notifications/wfm/payload-wfm.md - 'Audio Streaming': workforce/call-streaming/getting-started.md + - 'Media Control': workforce/call-streaming/media-control.md - 'Quality Management': workforce/qm/index.md - 'Call Recordings': workforce/call-recording/index.md - 'Bots/IVAs': bots/index.md diff --git a/specs/engage-voice_openapi3.json b/specs/engage-voice_openapi3.json index 2d9a9b9..d0efc2f 100644 --- a/specs/engage-voice_openapi3.json +++ b/specs/engage-voice_openapi3.json @@ -15821,6 +15821,39 @@ } }, "type": "object" + }, + "AudioStreamProperties": { + "properties": { + "encoding": { + "type": "string" + }, + "ptime": { + "format": "int32", + "type": "integer" + }, + "rate": { + "format": "int32", + "type": "integer" + } + }, + "type": "object" + }, + "StartStreamRequestDTO": { + "properties": { + "properties": { + "$ref": "#/components/schemas/AudioStreamProperties" + }, + "streamId": { + "type": "string" + }, + "token": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "type": "object" } }, "securitySchemes": { @@ -40254,6 +40287,306 @@ } ] } + }, + "/voice/api/cx/integration/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/dialogs/{dialogId}/segments/{segmentId}/streams": { + "post": { + "tags": [ + "Media Control" + ], + "summary": "Start segment media stream", + "description": "", + "operationId": "startSegmentStream", + "parameters": [ + { + "name": "rcAccountId", + "in": "path", + "description": "rcAccountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "subAccountId", + "in": "path", + "description": "subAccountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "dialogId", + "in": "path", + "description": "dialogId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "segmentId", + "in": "path", + "description": "segmentId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StartStreamRequestDTO" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK" + }, + "default": { + "description": "successful operation" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/cx/integration/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/dialogs/{dialogId}/segments/{segmentId}/streams/{streamId}": { + "delete": { + "tags": [ + "Media Control" + ], + "summary": "Stop segment media stream", + "description": "", + "operationId": "stopSegmentStream", + "parameters": [ + { + "name": "rcAccountId", + "in": "path", + "description": "rcAccountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "subAccountId", + "in": "path", + "description": "subAccountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "dialogId", + "in": "path", + "description": "dialogId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "segmentId", + "in": "path", + "description": "segmentId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "streamId", + "in": "path", + "description": "streamId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "default": { + "description": "successful operation" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/cx/integration/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/dialogs/{dialogId}/streams": { + "post": { + "tags": [ + "Media Control" + ], + "summary": "Start dialog media stream", + "description": "", + "operationId": "startDialogStream", + "parameters": [ + { + "name": "rcAccountId", + "in": "path", + "description": "rcAccountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "subAccountId", + "in": "path", + "description": "subAccountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "dialogId", + "in": "path", + "description": "dialogId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StartStreamRequestDTO" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "OK" + }, + "default": { + "description": "successful operation" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/voice/api/cx/integration/v1/accounts/{rcAccountId}/sub-accounts/{subAccountId}/dialogs/{dialogId}/streams/{streamId}": { + "delete": { + "tags": [ + "Media Control" + ], + "summary": "Stop dialog media stream", + "description": "", + "operationId": "stopDialogStream", + "parameters": [ + { + "name": "rcAccountId", + "in": "path", + "description": "rcAccountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "subAccountId", + "in": "path", + "description": "subAccountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "dialogId", + "in": "path", + "description": "dialogId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "streamId", + "in": "path", + "description": "streamId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "default": { + "description": "successful operation" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } } }, "servers": [ @@ -40419,6 +40752,10 @@ { "name": "External Auth Configurations", "description": "Manage reusable authentication configurations for outbound remote HTTP service calls." + }, + { + "name": "Media Control", + "description": "Start and stop live audio streams for RingCX dialogs and dialog segments." } ], "x-tag-groups": [ @@ -40525,7 +40862,8 @@ "name": "Workforce", "popular": true, "tags": [ - "Audio Streaming" + "Audio Streaming", + "Media Control" ] } ] From ad3a14ec0fc05e253b8f457a798a0cda7fb27af5 Mon Sep 17 00:00:00 2001 From: ajkamen Date: Wed, 1 Jul 2026 16:44:55 -0700 Subject: [PATCH 13/13] Clarify media control dialogs and segments --- docs/workforce/call-streaming/media-control.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/workforce/call-streaming/media-control.md b/docs/workforce/call-streaming/media-control.md index 258abc8..1f21cb4 100644 --- a/docs/workforce/call-streaming/media-control.md +++ b/docs/workforce/call-streaming/media-control.md @@ -11,7 +11,7 @@ Call streaming profiles define where audio can be streamed. Media control endpoi * **Selective Live Analytics:** Start a stream only when a workflow determines that live analysis is needed. * **Compliance Control:** Stop streaming before sensitive information is discussed. * **Targeted Recording Pipelines:** Stream only selected segments to external storage or AI services. -* **Troubleshooting:** Start a temporary stream for a specific dialog during an investigation. +* **Transfer-Aware Processing:** Stream only the dialog or agent segment that needs downstream analysis, storage, or compliance handling. ### Real-Time vs. Configuration APIs @@ -48,12 +48,18 @@ The user authenticating the app must also have access to the RingCX sub-account Media control requires interaction identifiers from another workflow. +### Dialog vs. Segment + +A dialog represents the overall interaction. A segment represents one participant leg or portion of that interaction. For example, if a customer speaks with Agent 1 and is then transferred to Agent 2, both agent conversations belong to the same dialog, but each agent leg has its own segment. + +Use dialog-level streaming when the receiver needs media for the full interaction. Use segment-level streaming when the receiver only needs one specific leg, such as a single agent's portion of a transferred call. + | Identifier | Type | Requirement | Description | | --- | --- | --- | --- | | `rcAccountId` | String | **Required** | RingCentral account ID. | | `subAccountId` | String | **Required** | RingCX sub-account ID that owns the dialog. | -| `dialogId` | String | **Required** | Conversation-level identifier. Capture it from the live interaction workflow that decides to start streaming, or from interaction metadata once the interaction is available to your integration. | -| `segmentId` | String | Optional | Segment identifier when you only want to stream one segment within the dialog. Capture it from the same interaction metadata source as the dialog when segment-level routing is required. | +| `dialogId` | String | **Required** | Identifier for the overall interaction. Capture it from the live interaction workflow that decides to start streaming, or from interaction metadata once the interaction is available to your integration. | +| `segmentId` | String | Optional | Identifier for one participant leg or portion of the dialog. Capture it from the same interaction metadata source as the dialog when segment-level routing is required. | | `streamId` | String | **Required** | Caller-provided stream identifier. You choose this value when starting the stream and reuse it to stop the same stream. | !!! info