From 7a4e2d71920eaca7017987258436b0bac63a9919 Mon Sep 17 00:00:00 2001 From: Yading Fang Date: Sat, 7 Feb 2026 01:36:48 +0800 Subject: [PATCH 1/5] doc: update README terminology and supported features --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f2fb2ad..255cc6e 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,10 @@ Sandbox API Repository to describe, develop, document, and test the ClickToDial ## Scope * Service APIs for “Click-To-Dial” (see APIBacklog.md) -* It provides the customer with the ability to: - * establish web-based communication by clicking an object (e.g., button, image or text) to request an immediate connection with another person in real-time either by phone call, Voice-over-Internet-Protocol (VoIP), or text +* It provides the API consumer with the ability to: + * establish a voice call between a caller and callee + * terminate an active call + * retrieve the recording of a call (if available) * Describe, develop, document and test the APIs * Started: September 2023 From 59e236a42c0b90599a5fae7d84628424938b9669 Mon Sep 17 00:00:00 2001 From: Yading Fang Date: Sat, 7 Feb 2026 01:47:51 +0800 Subject: [PATCH 2/5] doc: remove application-level introduction from API guidelines --- documentation/API_documentation/click-to-dial_API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API_documentation/click-to-dial_API.md b/documentation/API_documentation/click-to-dial_API.md index b09d638..83b5f6f 100644 --- a/documentation/API_documentation/click-to-dial_API.md +++ b/documentation/API_documentation/click-to-dial_API.md @@ -4,7 +4,7 @@ The Click to Dial API allows users to initiate and manage calls via an enterpris ## 1\. Introduction - The API displays the enterprise business number to both users during a call, masking both the caller and callee's real numbers to preserve privacy. Real-time feedback and notifications are supported via HTTP callbacks. Enterprise members share a pool of minutes, with the enterprise bearing unified payment, eliminating issues such as exceeding limits or wasting leftover package resources, thus reducing costs and increasing efficiency for the enterprise. + ## 2\. Quick Start From 997175302c73380ebe8b42b13881b03e434b3d9f Mon Sep 17 00:00:00 2001 From: Yading Fang Date: Sat, 7 Feb 2026 11:39:41 +0800 Subject: [PATCH 3/5] docs: align documentation with CloudEvent subject removal and API standards - Remove CloudEvent subject property from required attributes in API docs - Remove application-level descriptions (masked numbers, privacy) from User Story - Update examples to match CAMARA Commonalities standard - Align with PR-B schema changes where subject was removed from YAML --- documentation/API_documentation/click-to-dial_API.md | 6 +++--- documentation/API_documentation/click-to-dial_User_Story.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation/API_documentation/click-to-dial_API.md b/documentation/API_documentation/click-to-dial_API.md index 83b5f6f..3c43d0b 100644 --- a/documentation/API_documentation/click-to-dial_API.md +++ b/documentation/API_documentation/click-to-dial_API.md @@ -206,10 +206,10 @@ Note: Additional common CAMARA error responses may be defined in the `CAMARA_com ## CloudEvent delivery notes - Providers MUST send status notifications as CloudEvents in structured mode. The HTTP header must be `Content-Type: application/cloudevents+json`. -- The CloudEvent MUST include the attributes: `id`, `source`, `type`, `specversion`, `time`, and `subject` (subject should identify the resource, e.g. `/calls/{callId}`). +- The CloudEvent MUST include the attributes: `id`, `source`, `type`, `specversion`, and `time`. - The CloudEvent attribute `datacontenttype` MUST be `application/json` for the `data` payload. -The CloudEvent `data` payload for Click-to-Dial `EventCTDStatusChanged` includes `callId`, `caller`, `callee`, `timestamp` and `status` (where `status` is an object with `state` and optional `reason`). Providers MUST set the CloudEvent `subject` to the affected resource (for example `/calls/{callId}`) and set `datacontenttype` to `application/json`. +The CloudEvent `data` payload for Click-to-Dial `EventCTDStatusChanged` includes `callId`, `caller`, `callee`, `timestamp` and `status` (where `status` is an object with `state` and optional `reason`). Providers MUST set `datacontenttype` to `application/json`. Example CloudEvent (structured mode) — `CALL_STATUS_CHANGED_EXAMPLE` from the OpenAPI spec: @@ -217,7 +217,7 @@ Example CloudEvent (structured mode) — `CALL_STATUS_CHANGED_EXAMPLE` from the { "id": "83a0d986-0866-4f38-b8c0-fc65bfcda452", "source": "https://api.example.com/click-to-dial", - "subject": "/calls/123e4567-e89b-12d3-a456-426614174000", + "specversion": "1.0", "datacontenttype": "application/json", "type": "org.camaraproject.click-to-dial.v0.status-changed", diff --git a/documentation/API_documentation/click-to-dial_User_Story.md b/documentation/API_documentation/click-to-dial_User_Story.md index 51cd512..24343ee 100644 --- a/documentation/API_documentation/click-to-dial_User_Story.md +++ b/documentation/API_documentation/click-to-dial_User_Story.md @@ -2,7 +2,7 @@ | **Item** | **Details** | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Summary** | As an application developer for enterprise clients, I want to allow our corporate customers to initiate Click-to-Dial call sessions via the provider API so that two parties (caller and callee) are connected by masked numbers and can converse while the platform protects their privacy. The API should support call creation, termination, optional recording, and asynchronous status notifications. | +| **Summary** | As an application developer for enterprise clients, I want to allow our corporate customers to initiate Click-to-Dial call sessions via the provider API so that two parties (caller and callee) can be connected via a voice call. The API should support call creation, termination, optional recording, and asynchronous status notifications. | | **Roles, Actors and Scope** | **Roles:** Customer / User; **Actors:** Application developers, integration engineers, CSP (service provider); **Scope:** Create and remove CTD session resources (calls), receive status notifications and retrieve recordings when available. | | **Pre-conditions** | The client application has been onboarded and is authorized to call the API (has a valid access token with required scopes); the client knows the `apiRoot` and can send HTTP requests; if event delivery is required, the client provides a reachable `sink` URL and optional `sinkCredential`. | | **Activities / Steps** | Start: Client calls `POST /calls` with `caller`, `callee` and optional `sink`/`sinkCredential`. Flow: Provider places calls to both parties and manages the session; Provider delivers status notifications as CloudEvents to the configured `sink`. End: Client calls `DELETE /calls/{callId}` or session ends normally (call disconnected). | @@ -43,7 +43,7 @@ - CloudEvents and notifications - Providers MUST deliver status notifications as CloudEvents in structured mode (`Content-Type: application/cloudevents+json`). - - The CloudEvent MUST include `id`, `source`, `type`, `specversion`, `time`, `datacontenttype` and `subject` (subject should identify the resource, e.g. `/calls/{callId}`). `datacontenttype` for our events is `application/json`. + - The CloudEvent MUST include `id`, `source`, `type`, `specversion`, `time`, and `datacontenttype`. `datacontenttype` for our events is `application/json`. - The event `data` payload for `EventCTDStatusChanged` contains `callId`, `caller`, `callee`, `timestamp` and `status` (an object): ```json @@ -60,6 +60,6 @@ 1. Client POSTs to `/calls` with `caller`, `callee`, optional `sink`/`sinkCredential`. 2. Provider returns `201 Created` with call details including `callId`. -3. Provider sends CloudEvents to `sink` as the call progresses; each event's `subject` is `/calls/{callId}`. +3. Provider sends CloudEvents to `sink` as the call progresses with call status updates. 4. When the call ends, provider sends a final `disconnected` state event including `callDuration` and, if recording was enabled, `recordingResult`. 5. Client can `GET /calls/{callId}/recording` to download the recording resource if available. From 6f3fcf6578815a6cbbdecb65e96130800f7dba44 Mon Sep 17 00:00:00 2001 From: Yading Fang Date: Sat, 7 Feb 2026 11:48:16 +0800 Subject: [PATCH 4/5] docs: populate introduction section in API documentation --- documentation/API_documentation/click-to-dial_API.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/documentation/API_documentation/click-to-dial_API.md b/documentation/API_documentation/click-to-dial_API.md index 3c43d0b..9e4e4fb 100644 --- a/documentation/API_documentation/click-to-dial_API.md +++ b/documentation/API_documentation/click-to-dial_API.md @@ -2,7 +2,9 @@ The Click to Dial API allows users to initiate and manage calls via an enterprise platform or application. The API processes call requests, sets up the call, and provides optional notifications and call recording features. -## 1\. Introduction +## 1. Introduction + +The Click to Dial API provides a standardized interface to initiate and manage voice call sessions between two parties. It allows API consumers to create a call session, retrieve call status and details, terminate an active call, and retrieve call recordings (if enabled). From b32e3dd5688c6b24a56dc9a2c5638c8d25e4dbcc Mon Sep 17 00:00:00 2001 From: Yading Fang Date: Tue, 10 Feb 2026 11:02:43 +0800 Subject: [PATCH 5/5] docs: standardize API terminology and remove inapplicable error codes --- README.md | 2 +- code/API_definitions/click-to-dial.yaml | 2 +- documentation/API_documentation/click-to-dial_API.md | 4 +--- documentation/API_documentation/click-to-dial_User_Story.md | 4 ++-- 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 255cc6e..7f3d547 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Sandbox API Repository to describe, develop, document, and test the ClickToDial * API Repository [Click To Dial](https://lf-camaraproject.atlassian.net/wiki/x/3DHe) ## Scope -* Service APIs for “Click-To-Dial” (see APIBacklog.md) +* Service APIs for “Click-To-Dial” * It provides the API consumer with the ability to: * establish a voice call between a caller and callee * terminate an active call diff --git a/code/API_definitions/click-to-dial.yaml b/code/API_definitions/click-to-dial.yaml index 9988707..6b396dc 100644 --- a/code/API_definitions/click-to-dial.yaml +++ b/code/API_definitions/click-to-dial.yaml @@ -3,7 +3,7 @@ openapi: 3.0.3 info: title: Click to Dial Service description: | - The Click to Dial API allows users to initiate and manage calls via an enterprise platform or application. The API processes call requests, sets up the call, and provides optional notifications and call recording features. For specific details, please refer to [click-to-dial_API.md](/documentation/API_documentation/click-to-dial_API.md) + The Click to Dial API allows API consumers to initiate and manage voice calls between two parties. The API processes call requests, sets up the call, and provides optional status notifications and call recording features. For specific details, please refer to [click-to-dial_API.md](/documentation/API_documentation/click-to-dial_API.md) # API functionality diff --git a/documentation/API_documentation/click-to-dial_API.md b/documentation/API_documentation/click-to-dial_API.md index 9e4e4fb..c0462ec 100644 --- a/documentation/API_documentation/click-to-dial_API.md +++ b/documentation/API_documentation/click-to-dial_API.md @@ -1,6 +1,6 @@ # Overview -The Click to Dial API allows users to initiate and manage calls via an enterprise platform or application. The API processes call requests, sets up the call, and provides optional notifications and call recording features. +The Click to Dial API allows API consumers to initiate and manage voice calls between two parties. The API processes call requests, sets up the call, and provides optional status notifications and call recording features. ## 1. Introduction @@ -190,8 +190,6 @@ When a request is syntactically correct but semantically invalid, the API return | `RECORDING_NOT_SUPPORTED` | Recording is not supported for this call. | | `CALLER_NOT_AVAILABLE` | Caller number is currently not reachable or not allowed to start a call. | | `CALLEE_NOT_AVAILABLE` | Callee number is currently not reachable or not allowed to receive a call. | -| `INSUFFICIENT_BALANCE` | The account does not have sufficient balance or quota to start this call. | -| `RESTRICTED_DESTINATION` | The destination number is restricted and cannot be called. | Example 422 response: diff --git a/documentation/API_documentation/click-to-dial_User_Story.md b/documentation/API_documentation/click-to-dial_User_Story.md index 24343ee..f26e03e 100644 --- a/documentation/API_documentation/click-to-dial_User_Story.md +++ b/documentation/API_documentation/click-to-dial_User_Story.md @@ -2,8 +2,8 @@ | **Item** | **Details** | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Summary** | As an application developer for enterprise clients, I want to allow our corporate customers to initiate Click-to-Dial call sessions via the provider API so that two parties (caller and callee) can be connected via a voice call. The API should support call creation, termination, optional recording, and asynchronous status notifications. | -| **Roles, Actors and Scope** | **Roles:** Customer / User; **Actors:** Application developers, integration engineers, CSP (service provider); **Scope:** Create and remove CTD session resources (calls), receive status notifications and retrieve recordings when available. | +| **Summary** | As an application developer, I want to allow API consumers to initiate Click-to-Dial call sessions via the provider API so that two parties (caller and callee) can be connected via a voice call. The API should support call creation, termination, optional recording, and asynchronous status notifications. | +| **Roles, Actors and Scope** | **Roles:** API consumer; **Actors:** Application developers, integration engineers, CSP (service provider); **Scope:** Create and remove CTD session resources (calls), receive status notifications and retrieve recordings when available. | | **Pre-conditions** | The client application has been onboarded and is authorized to call the API (has a valid access token with required scopes); the client knows the `apiRoot` and can send HTTP requests; if event delivery is required, the client provides a reachable `sink` URL and optional `sinkCredential`. | | **Activities / Steps** | Start: Client calls `POST /calls` with `caller`, `callee` and optional `sink`/`sinkCredential`. Flow: Provider places calls to both parties and manages the session; Provider delivers status notifications as CloudEvents to the configured `sink`. End: Client calls `DELETE /calls/{callId}` or session ends normally (call disconnected). | | **Post-conditions** | Call session resource exists with a `callId` and lifecycle `status`; if `sink` was provided, the provider sends CloudEvents (structured mode) to the `sink` with updates about call state changes; when recording is enabled and the call completes, a recording resource may be available at `GET /calls/{callId}/recording`. |