camaraproject · stroncoso-quobis · Jan 13, 2026 · Oct 10, 2025 · Dec 16, 2025 · Dec 16, 2025
@@ -0,0 +1,34 @@
+# WebRTC API call flows
+
+## 1. General
+
+This document provides example call flows and messages based on WebRTC API user story for implementers of a WebRTC Gateway that exposes WebRTC APIs and interworks with telco network.
+
+## 2. Actors
+
+The involved actors in the call flows are as follows:
+
+- **Device Application**：A native application or web application running on the user’s device.
+
+- **Application Server**: Acts as a WebRTC API Invoker.
+
+- **Auth Server**: Performs auth for API usage in accordance with the CAMARA ICM specification.
+
+- **WebRTC Gateway**: Acts as a WebRTC API provider, and also interworks with telco network.
+
+- **Telco Network**： Acts as signalling (SIP) & media servers.
+
+- **Remote Endpoint**：The peer in the call using the WebRTC API.
+
+
+## 3. List of call flow examples
+
+The following links provide call flow diagrams and message examples.
+
+- 3.1. [Subscription for WebRTC events](./subscription_for_webrtc_events.md)
+- 3.2. WebRTC registration
+- 3.3. Call orignation and disconnection (TBD)
+- 3.4. Call termination and disconnection (TBD)
+
+The message examples illustrate the fields necessary for implementing a WebRTC Gateway, including all defined optional fields where applicable.  
+Although the API specification defines fields for [API-design-guidline](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md) consistency, those not applicable in the WebRTC API are excluded from the message examples.
@@ -0,0 +1,266 @@
+# 3.1. Subscription for WebRTC events
+
+This part of the call flow covers subscribing, unsubscribing, and updating subscriptions for WebRTC events.
+
+## 3.1.1. Event Subscriptions
+### 3.1.1.1. Sequence
+
+![fig1](./subscription_for_webrtc_events_fig-1.png)
+
+### 3.1.1.2. Example messages
+#### [3] GET /authorize
+```
+GET /authorize?response_type=code
+    &client_id=asp-webrtc-app-001
+    &redirect_uri=https%3A%2F%2Fasp.example.com%2Fcallback
+    &scope=openid%20webrtc-events%3Aorg.camaraproject.webrtc-events.v0.session-invitation%3Acreate%20webrtc-events%3Aorg.camaraproject.webrtc-events.v0.session-status%3Acreate%20webrtc-events%3Aorg.camaraproject.webrtc-events.v0.registration-ends%3Acreate
+    &state=af0ifjsldkj
+    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
+    &code_challenge_method=S256 HTTP/1.1
+Host: auth.operator.com
+```
+
+#### [4] 302 Found
+```
+HTTP/1.1 302 Found
+Location: https://asp.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj
+```
+
+#### [6] POST /token
+```
+POST /token HTTP/1.1
+Host: auth.operator.com
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code
+&code=SplxlOBeZQQYbYS6WxSbIA
+&redirect_uri=https%3A%2F%2Fasp.example.com%2Fcallback
+&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
+```
+
+#### [7] 200 OK
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+Cache-Control: no-store
+
+{
+  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGgub3BlcmF0b3IuY29tIiwic3ViIjoiKzEyMzQ1Njc4OTAiLCJhdWQiOiJhc3Atd2VicnRjLWFwcC0wMDEiLCJleHAiOjE3MzQyNzI2MDAsImlhdCI6MTczNDI2OTAwMCwic2NvcGUiOiJvcGVuaWQgd2VicnRjLWV2ZW50czpvcmcuY2FtYXJhcHJvamVjdC53ZWJydGMtZXZlbnRzLnYwLnNlc3Npb24taW52aXRhdGlvbjpjcmVhdGUgd2VicnRjLWV2ZW50czpvcmcuY2FtYXJhcHJvamVjdC53ZWJydGMtZXZlbnRzLnYwLnNlc3Npb24tc3RhdHVzOmNyZWF0ZSB3ZWJydGMtZXZlbnRzOm9yZy5jYW1hcmFwcm9qZWN0LndlYnJ0Yy1ldmVudHMudjAucmVnaXN0cmF0aW9uLWVuZHM6Y3JlYXRlIn0.signature",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
+  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGgub3BlcmF0b3IuY29tIiwic3ViIjoiYWJjZDEyMzQiLCJhdWQiOiJhc3Atd2VicnRjLWFwcC0wMDEiLCJleHAiOjE3MzQyNzI2MDAsImlhdCI6MTczNDI2OTAwMCwibm9uY2UiOiJuLTBTNl9XekEyTWoifQ.signature"
+}
+```
+
+#### [8] POST /webrtc-events-suscription/{apiVersion}/subscriptions
+```
+POST /webrtc-events/v0.2/subscriptions HTTP/1.1
+Host: api.example.com
+Content-Type: application/json
+Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+x-correlator: b4333c46-49c0-4f62-80d7-f0ef930f1c46
+
+{
+  "protocol": "HTTP",
+  "sink": "https://asp.example.com/webhooks/webrtc",
+  "sinkCredential": {
+    "credentialType": "ACCESSTOKEN",
+    "accessToken": "eyJ2ZXIiOiIxLjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.abc123",
+    "accessTokenExpiresUtc": "2025-12-20T23:59:59.999Z",
+    "accessTokenType": "bearer"
+  },
+  "types": [
+    "org.camaraproject.webrtc-events.v0.session-invitation",
+    "org.camaraproject.webrtc-events.v0.session-status",
+    "org.camaraproject.webrtc-events.v0.registration-ends"
+  ],
+  "config": {
+    "subscriptionDetail": {
+      "deviceId": "7d444840-9dc0-11d1-b245-5ffdce74fad2"
+    },
+    "subscriptionExpireTime": "2025-12-31T23:59:59.999Z"
+  }
+}
+```
+
+> **ISSUE** (NotAddressed)
+> 
+> Related Issue: #NN
+>
+> Related PR: #NN
+>
+> Per the updated CAMARA-API-Event-Subscription-and-Notification-Guide.md, event subscriptions (`session-invitation`, `session-status`, `registration-ends`) are consolidated into a single request using the types array to reduce transactions. 
+>
+> This consolidated subscription pattern should be reflected in the webrtc-events.yaml examples.
+
+> **ISSUE** (NotAddressed)
+> 
+> Related Issue: #NN
+>
+> Related PR: #NN
+>
+> The following fields (derived from CAMARA-API-Event-Subscription-and-Notification-Guide) are omitted as they are not applicable to WebRTC events:
+> - `subscriptionMaxEvents`: The number of events generated by the WebRTC API cannot be predicted in typical use cases. For resource lifecycle management, `subscriptionExpireTime` is the recommended approach.
+> - `initialEvent`: None of the WebRTC events (`session-status`, `session-invitation`, `registration-ends`) are triggered at the event subscription.  
+>
+> Informational descriptions for above fields need to be added in webrtc-events.yaml.
+
+> **ISSUE** (NotAddressed)
+> 
+> Related Issue: #NN
+>
+> Related PR: #NN
+>
+> The webrtc-events.yaml states that `HTTPSubscriptionRequest` and `HTTPSubscriptionResponse` schemas are applied when the `proto` field value is "HTTP", but the current examples do not reflect those schemas.
+>
+> It should be clarified whether to:
+> - Update the examples to conform to the specification, or
+> - Remove the schemas above.
+
+#### [11] 201 Created
+```
+HTTP/1.1 201 Created
+Content-Type: application/json
+x-correlator: b4333c46-49c0-4f62-80d7-f0ef930f1c46
+
+{
+  "protocol": "HTTP",
+  "sink": "https://notificationServer.example.com/webhooks/webrtc",
+  "types": [
+    "org.camaraproject.webrtc-events.v0.session-invitation",
+    "org.camaraproject.webrtc-events.v0.session-status",
+    "org.camaraproject.webrtc-events.v0.registration-ends"
+  ],
+  "config": {
+    "subscriptionDetail": {
+      "deviceId": "7d444840-9dc0-11d1-b245-5ffdce74fad2"
+    },
+    "subscriptionExpireTime": "2025-12-31T23:59:59.999Z"
+  },
+  "id": "sub-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "startsAt": "2025-12-15T10:30:00.000Z",
+  "expiresAt": "2025-12-31T23:59:59.999Z",
+  "status": "ACTIVE"
+}
+```
+
+## 3.1.2. Refresh event subscriptions
+### 3.1.2.1. Sequence
+
+![fig1](./subscription_for_webrtc_events_fig-2.png)
+
+### 3.1.2.2. Example messages
+#### [18] PUT /webrtc-events-suscription/{apiVersion}/subscriptions/{subscriptionId}
+```
+PUT /webrtc-events/v0.2/subscriptions/sub-a1b2c3d4-e5f6-7890-abcd-ef1234567890 HTTP/1.1
+Host: api.example.com
+Content-Type: application/json
+Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+x-correlator: f8e7d6c5-b4a3-2190-fedc-ba0987654321
+
+{
+  "sinkCredential": {
+    "credentialType": "ACCESSTOKEN",
+    "accessToken": "eyJ2ZXIiOiIxLjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.xyz789",
+    "accessTokenExpiresUtc": "2026-01-20T23:59:59.999Z",
+    "accessTokenType": "bearer"
+  },
+  "config": {
+    "subscriptionDetail": {
+      "deviceId": "7d444840-9dc0-11d1-b245-5ffdce74fad2"
+    },
+    "subscriptionExpireTime": "2026-01-31T23:59:59.999Z"
+  }
+}
+```
+> **ISSUE** (NotAddressed)
+> 
+> Related Issue: #NN
+>
+> Related PR: #NN
+>
+> When a `session-status` event subscription expires, signaling for ongoing calls becomes unavailable. Since media modifications may be initiated by the Remote Endpoint, clients MUST refresh the subscription using PUT before `expiresAt` or `sinkCredential.accessTokenExpiresUtc` is reached, if they have ongoing media sessions.
+>
+> The `PUT` method for subscription refresh must be added to the webrtc-events.yaml.
+
+#### [21] 200 OK
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+x-correlator: f8e7d6c5-b4a3-2190-fedc-ba0987654321
+
+{
+  "protocol": "HTTP",
+  "sink": "https://asp.example.com/webhooks/webrtc",
+  "types": [
+    "org.camaraproject.webrtc-events.v0.session-invitation",
+    "org.camaraproject.webrtc-events.v0.session-status",
+    "org.camaraproject.webrtc-events.v0.registration-ends"
+  ],
+  "config": {
+    "subscriptionDetail": {
+      "deviceId": "7d444840-9dc0-11d1-b245-5ffdce74fad2"
+    },
+    "subscriptionExpireTime": "2026-01-31T23:59:59.999Z"
+  },
+  "id": "sub-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "startsAt": "2025-12-15T10:30:00.000Z",
+  "expiresAt": "2026-01-31T23:59:59.999Z",
+  "status": "ACTIVE"
+}
+```
+
+## 3.1.3. Unsubscribe from events
+### 3.1.3.1. Sequence
+
+![fig3](./subscription_for_webrtc_events_fig-3.png)
+
+### 3.1.3.2. Example messages
+#### [29] DELETE /webrtc-events/{apiVersion}/subscriptions/{subscriptionId}
+```
+DELETE /webrtc-events/v0.2/subscriptions/sub-a1b2c3d4-e5f6-7890-abcd-ef1234567890 HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+x-correlator: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+```
+
+#### [32] 202 Accepted
+```
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+x-correlator: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+
+{
+  "id": "sub-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+}
+```
+
+#### [33] POST {sink} (callback)
+```
+POST /webhooks/webrtc HTTP/1.1
+Host: asp.example.com
+Content-Type: application/cloudevents+json
+Authorization: Bearer eyJ2ZXIiOiIxLjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.xyz789
+x-correlator: b2c3d4e5-f6a7-8901-bcde-f23456789012
+
+{
+  "id": "evt-9a8b7c6d-5e4f-3210-fedc-ba9876543210",
+  "source": "https://api.example.com/webrtc-events/v0.2",
+  "type": "org.camaraproject.webrtc-events.v0.subscription-ended",
+  "specversion": "1.0",
+  "datacontenttype": "application/json",
+  "time": "2025-12-15T14:30:00.000Z",
+  "data": {
+    "subscriptionId": "sub-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "terminationReason": "SUBSCRIPTION_DELETED",
+    "terminationDescription": "Subscription deleted by client request"
+  }
+}
+```
+
+#### [35] 204 No Content (callback response)
+```
+HTTP/1.1 204 No Content
+x-correlator: b2c3d4e5-f6a7-8901-bcde-f23456789012
+```
@@ -0,0 +1,61 @@
+@startuml
+
+
+!pragma teoz true
+autonumber 1 "<font color=blue><b>[0]"
+
+<style>
+.box {
+  Margin 40
+}
+.audio{
+  arrow {
+    LineColor red
+    LineThickness 5
+  }
+}
+</style>
+
+box Device 
+  participant "Device\nApplication" as DA
+end box
+
+box Application Service Provider
+  participant "Application\nServer" as AS
+end box
+
+box "Operator Network" #EEEEEE
+  participant "Auth\nServer" as AUTH
+  participant "WebRTC\nGateway" as WG
+  participant "Telco\nNetwork" as TN
+end box
+
+box Device
+  participant "Remote\nendpoint" as RE
+end box
+
+
+'activate AS #LightSteelBlue
+
+DA -> AS: Accessing ASP entry point\n(incl. AuthN&AuthZ)
+DA <-- AS: Activate Device Application
+activate DA
+
+
+== Subscription for session-invitation, session-status, registration-ends ==
+
+AS -> AUTH: GET /authorize
+AS <-- AUTH: 302 Found\n(redirecting user agent)
+DA <[#gray]-> AUTH: End user consent (e.g., ICM Auth Code Flow)
+AS -> AUTH: POST /token
+AS <-- AUTH: 200 OK
+
+AS -[#red]> WG: **POST /webrtc-events-suscription/{apiVersion}/subscriptions**
+
+AUTH <- WG: POST /token/introspection
+AUTH --> WG: 200 OK
+
+AS <[#red]-- WG: **201 Created**
+activate WG #LightSteelBlue
+
+@enduml