Clarify ClickToDial lifecycle and callback documentation

[YadingFang]

What type of PR is this?

• documentation

What this PR does / why we need it:

This PR improves the API documentation and clarifies the call lifecycle, callback behavior, and recording availability for the ClickToDial 0.2.0-rc Sync26 target in the camaraproject/ClickToDial repository:

1. Call Lifecycle & Aggregate State:
   • Clarified that the ClickToDial API exposes an aggregate provider-managed call session state rather than separate independent caller/callee leg APIs.
   • Detailed the lifecycle states: initiating, callingCaller, callingCallee, connected, disconnected, and failed.
2. Callback & Event Delivery:
   • Clarified that status notification callbacks are delivered as CloudEvents in structured mode (Content-Type: application/cloudevents+json).
   • Replaced the stale schema name EventCTDStatusChanged with CallStatusChangedEvent.
   • Documented that sinkCredential with type ACCESSTOKEN is mapped to the Authorization header as Bearer <accessToken> during event delivery.
   • Clarified that transient delivery failures may be retried and do not roll back successfully created call sessions.
   • Advised consumers to use GET /calls/{callId} to reconcile call state.
3. Recording Availability:
   • Clarified that call recordings can only be retrieved via GET /calls/{callId}/recording if recording was enabled during call creation, is supported by the provider, the call has completed, and a recording was generated.
   • Clarified that if no recording is available, the API returns the documented 404 Not Found response with the NOT_FOUND error code.
   • Documented how the recordingResult in the final callback event helps indicate recording generation success/failure.
4. Use Cases & Acceptance Criteria:
   • Added three detailed use cases with steps and acceptance criteria to the User Story document:
     • Create ClickToDial call with status notifications.
     • Terminate an active ClickToDial call.
     • Retrieve recording after a completed recorded call.
5. Non-normative API spec descriptions:
   • Updated the descriptions of key fields/endpoints in click-to-dial.yaml to match these documentation updates.

Which issue(s) this PR fixes:

Not applicable.

Special notes for reviewers:

The changes are documentation-focused and do not modify the API schemas, required fields, path structure, scopes, or error code enums.

[camara-validation]

CAMARA Validation — PASS

0 errors, 0 warnings, 0 hints | Profile: standard

View full results

[Wojiaozhenghao]

ok