diff --git a/README.md b/README.md index f2fb2ad..7f3d547 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,11 @@ 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) -* 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 +* 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 + * retrieve the recording of a call (if available) * Describe, develop, document and test the APIs * Started: September 2023 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 b09d638..c0462ec 100644 --- a/documentation/API_documentation/click-to-dial_API.md +++ b/documentation/API_documentation/click-to-dial_API.md @@ -1,10 +1,12 @@ # 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 + +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). -## 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 @@ -188,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: @@ -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..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) 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. | -| **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`. | @@ -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.