From afd5d993781b3c35a81ab277807fc61f2d64c980 Mon Sep 17 00:00:00 2001 From: Santiago Troncoso Date: Mon, 16 Feb 2026 17:19:24 +0100 Subject: [PATCH 1/4] fix: Update order on webrtc-call-handling description --- code/API_definitions/webrtc-call-handling.yaml | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/webrtc-call-handling.yaml b/code/API_definitions/webrtc-call-handling.yaml index a009b50..5743318 100644 --- a/code/API_definitions/webrtc-call-handling.yaml +++ b/code/API_definitions/webrtc-call-handling.yaml @@ -185,6 +185,15 @@ info: in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. + # Emergency Calling + + - Introduces a new `callType` attribute with values `REGULAR` or `EMERGENCY`. + - When `callType` is `EMERGENCY`, the client **MAY** include `locationDetails` + describing the caller's location. + - `locationDetails` follows PIDF-LO concepts (3GPP TS 24.229, RFC 4119, RFC 5139, + RFC 5491) with either a circle or ellipsoid shape. + - If `callType` is omitted, it defaults to `REGULAR`. + # Additional CAMARA error responses The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error @@ -198,14 +207,6 @@ info: As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. - # Emergency Calling - - Introduces a new `callType` attribute with values `REGULAR` or `EMERGENCY`. - - When `callType` is `EMERGENCY`, the client **MAY** include `locationDetails` - describing the caller's location. - - `locationDetails` follows PIDF-LO concepts (3GPP TS 24.229, RFC 4119, RFC 5139, - RFC 5491) with either a circle or ellipsoid shape. - - If `callType` is omitted, it defaults to `REGULAR`. - license: name: Apache 2.0 url: 'https://www.apache.org/licenses/LICENSE-2.0.html' From 420d1e668826d08eef1e7a44c571acc3cbc342da Mon Sep 17 00:00:00 2001 From: Santiago Troncoso Date: Mon, 16 Feb 2026 17:30:35 +0100 Subject: [PATCH 2/4] feat: Located calls. Call-handling and Events location objects for caller and callee --- .../API_definitions/webrtc-call-handling.yaml | 88 ++++++--- code/API_definitions/webrtc-events.yaml | 167 ++++++++++++++++++ 2 files changed, 229 insertions(+), 26 deletions(-) diff --git a/code/API_definitions/webrtc-call-handling.yaml b/code/API_definitions/webrtc-call-handling.yaml index 5743318..e3e5d92 100644 --- a/code/API_definitions/webrtc-call-handling.yaml +++ b/code/API_definitions/webrtc-call-handling.yaml @@ -167,6 +167,44 @@ info: } ``` + # Additional CAMARA error responses + The list of error codes in this API specification is not exhaustive. + Therefore the API specification may not document some non-mandatory error + statuses as indicated in `CAMARA API Design Guide`. + + Please refer to the `CAMARA_common.yaml` of the Commonalities Release + associated to this API version for a complete list of error responses. The + applicable Commonalities Release can be identified in the `API Readiness + Checklist` document associated to this API version. + + As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible + error response if it is explicitly documented in the API. + + # Located calls + + As part of the extended, or contextual information of calls, a location can + be provided as part of the call information. A regular call **MAY** provide + an `originatorLocationDetails` object in order to help the receiver to + locate the geographic position of the device calling. In aim of security, + routing or any other use case provided by the network. + + As each party can share its own location, there are two separated objects + `originatorLocationDetails` and `receiverLocationDetails`, both serving + the same purpose and implementing the `locationDetails` schema. + + The `locationDetails` schema follows PIDF-LO concepts (3GPP TS 24.229, + RFC 4119, RFC 5139, RFC 5491) with either a circle or ellipsoid shape. + + # Emergency Calling + + - Introduces a new `callType` attribute with values `REGULAR` or `EMERGENCY`. + - When `callType` is `EMERGENCY`, the client **MAY** include + `originatorLocationDetails` describing the caller's location. + - `originatorLocationDetails` implements the `locationDetails` schema. + This schema follows PIDF-LO concepts (3GPP TS 24.229, RFC 4119, RFC 5139, + RFC 5491) with either a circle or ellipsoid shape. + - If `callType` is omitted, it defaults to `REGULAR`. + # Authorization and authentication The "Camara Security and Interoperability Profile" provides details of how an @@ -185,28 +223,6 @@ info: in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. - # Emergency Calling - - - Introduces a new `callType` attribute with values `REGULAR` or `EMERGENCY`. - - When `callType` is `EMERGENCY`, the client **MAY** include `locationDetails` - describing the caller's location. - - `locationDetails` follows PIDF-LO concepts (3GPP TS 24.229, RFC 4119, RFC 5139, - RFC 5491) with either a circle or ellipsoid shape. - - If `callType` is omitted, it defaults to `REGULAR`. - - # Additional CAMARA error responses - The list of error codes in this API specification is not exhaustive. - Therefore the API specification may not document some non-mandatory error - statuses as indicated in `CAMARA API Design Guide`. - - Please refer to the `CAMARA_common.yaml` of the Commonalities Release - associated to this API version for a complete list of error responses. The - applicable Commonalities Release can be identified in the `API Readiness - Checklist` document associated to this API version. - - As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible - error response if it is explicitly documented in the API. - license: name: Apache 2.0 url: 'https://www.apache.org/licenses/LICENSE-2.0.html' @@ -250,6 +266,8 @@ paths: $ref: '#/components/examples/exampleMediaSessionRequest' EmergencyMediaSessionRequest: $ref: '#/components/examples/exampleEmergencyMediaSessionRequest' + LocatedMediaSessionRequest: + $ref: '#/components/examples/exampleLocatedMediaSessionRequest' responses: '201': description: Created @@ -587,11 +605,8 @@ components: description: 'The method used to obtain the location information. * **GPS:** Global Positioning System (highly accurate) - * **DBH:** Device-Based Hybrid - * **DBH_HELO:** Device-Based Hybrid using Apple Hybridized Emergency Location - * **Other:** Other methods (e.g., landmarks, IP Based etc.) ' @@ -784,7 +799,7 @@ components: type: offer sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n" callType: EMERGENCY - locationDetails: + originatorLocationDetails: shape: Circle coordinates: latitude: 47.6062 @@ -795,6 +810,27 @@ components: pdf: normal value: 92 timestamp: '2025-10-06T19:31:25Z' + exampleLocatedMediaSessionRequest: + summary: Regular call initiation with location details + value: + originatorAddress: 'tel:+17085852753' + originatorName: Alice + receiverAddress: tel:+17085854000 + receiverName: Bob + offer: + type: offer + sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n" + originatorLocationDetails: + shape: Circle + coordinates: + latitude: 47.5124 + longitude: -122.4176 + radius: 27 + method: GPS + confidence: + pdf: normal + value: 97 + timestamp: '2025-10-06T19:31:25Z' responses: Generic400: description: Bad Request diff --git a/code/API_definitions/webrtc-events.yaml b/code/API_definitions/webrtc-events.yaml index 8205c52..fb3bfcb 100644 --- a/code/API_definitions/webrtc-events.yaml +++ b/code/API_definitions/webrtc-events.yaml @@ -142,6 +142,21 @@ info: a unique SessionId, to create a dedicated subscription and receive events about the session itself and its status progressing inside the network. + **Located calls** + + The CAMARA WebRTC API provides an standardization way to locate caller + origin. If provided by the network, it helps to contextualize the calls + in aim of enhanced security, routing or any other use case. The located + calls include a `originatorLocationDetails` object on the `session-invitation` + event that could be parsed and used by the API consumer. + + As each party can share its own location, there are two separated objects + `originatorLocationDetails` and `receiverLocationDetails`, both serving + the same purpose and implementing the `locationDetails` schema. + + The `locationDetails` schema follows PIDF-LO concepts (3GPP TS 24.229, + RFC 4119, RFC 5139, RFC 5491) with either a circle or ellipsoid shape. + ## 3. Subscription ends (subscription-ended) A `org.camaraproject.webrtc-events.v0.subscription-ended` event indicates that @@ -265,6 +280,8 @@ paths: examples: NEW_SESSION_INCOMING (session-invitation): $ref: "#/components/examples/NEW_SESSION_INCOMING" + NEW_LOCATED_SESSION_INCOMING (session-invitation): + $ref: "#/components/examples/NEW_LOCATED_SESSION_INCOMING" SESSION_UPDATE (session-status): $ref: "#/components/examples/SESSION_UPDATE" REGISTRATION_EXPIRED (registration-ends): @@ -891,6 +908,10 @@ components: sequenceNumber: type: integer description: The sequence number of the notification sent to client + originatorLocationDetails: + $ref: '#/components/schemas/LocationDetails + receiverLocationDetails: + $ref: '#/components/schemas/LocationDetails MediaSessionStatusUpdate: allOf: @@ -1030,6 +1051,116 @@ components: description: The HTTP method to use for sending the message. enum: - POST + LocationDetails: + type: object + description: Details about the caller's location and related information. This + object adheres to 3GPP TS 24.229, RFC 4119, RFC 5139, and RFC 5491 for PIDF-LO + compatibility. + properties: + shape: + type: string + enum: + - Circle + - Ellipsoid + description: The shape representing the caller's location (Circle or Ellipsoid). + coordinates: + oneOf: + - $ref: '#/components/schemas/CircleCoordinates' + - $ref: '#/components/schemas/EllipsoidCoordinates' + description: The coordinates of the caller's location, specific to the chosen + shape. + method: + type: string + enum: + - GPS + - DBH + - DBH_HELO + - Other + description: 'The method used to obtain the location information. + + * **GPS:** Global Positioning System (highly accurate) + * **DBH:** Device-Based Hybrid + * **DBH_HELO:** Device-Based Hybrid using Apple Hybridized Emergency Location + * **Other:** Other methods (e.g., landmarks, IP Based etc.) + + ' + confidence: + type: object + description: The confidence level of the location information. + properties: + pdf: + type: string + enum: + - normal + - uniform + description: The probability density function (PDF) associated with the + confidence value. + value: + type: number + minimum: 0 + maximum: 100 + description: The confidence value (percentage). + timestamp: + type: string + format: date-time + description: The timestamp (in ISO 8601 format) indicating when the location + information was Calculated. \nThis is crucial for emergency services to + assess the timeliness of the data. if not provided current timestamp will + be used by default" + CircleCoordinates: + type: object + required: + - latitude + - longitude + - radius + properties: + latitude: + type: number + format: float + description: Latitude of the center point in decimal degrees (WGS84). + longitude: + type: number + format: float + description: Longitude of the center point in decimal degrees (WGS84). + radius: + type: number + format: float + description: Radius of the circle in meters, indicating the uncertainty. + EllipsoidCoordinates: + type: object + required: + - latitude + - longitude + - zAxis + - semiMajorAxis + - semiMinorAxis + - verticalAxis + - orientation + properties: + latitude: + type: number + format: float + description: Latitude in the WGS 84 geocentric coordinate system. + longitude: + type: number + format: float + description: Longitude in the WGS 84 geocentric coordinate system. + zAxis: + type: number + format: float + description: Altitude (optional) in the WGS 84 geocentric coordinate system. + semiMajorAxis: + type: number + description: Length of the semi-major axis of the ellipsoid in meters. + semiMinorAxis: + type: number + description: Length of the semi-minor axis of the ellipsoid in meters. + verticalAxis: + type: number + description: Length of the vertical axis of the ellipsoid in meters. + orientation: + type: number + description: Orientation of the ellipsoid in degrees. responses: CreateSubscriptionBadRequest400: @@ -1505,6 +1636,42 @@ components: mediaSessionId: "0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EF" reason: "New subscriber incoming call" sequenceNumber: 1 + NEW_LOCATED_SESSION_INCOMING: + description: |- + Example of located `session-invitation` event. + + An extended example of `session-invitation` that includes location + details within the `LocationDetails` object + value: + id: "VzYQCOClM6Kc7Xmyq7mP58Jx" + source: https://notificationServer.opentelco.com + type: org.camaraproject.webrtc-events.v0.session-invitation + specversion: "1.0" + datacontenttype: application/json + time: 2024-11-05T05:40:23.682Z + data: + subscriptionId: "qs15-h556-rt89-1298" + originatorAddress: "tel:+11234567899" + originatorName: "Alice" + receiverAddress: "tel:+11234998765" + receiverName: "Bob" + status: "Initial" + offer: + sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0" + mediaSessionId: "0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EF" + reason: "New subscriber incoming call" + sequenceNumber: 1 + locationDetails: + shape: Circle + coordinates: + latitude: 47.6062 + longitude: -122.3321 + radius: 35 + method: GPS + confidence: + pdf: normal + value: 92 + timestamp: '2024-11-05T05:35:12.254Z' REGISTRATION_ENDS: description: |- Example of `registration-ends` events. From 9a6cf9a57ecac450b38152fe35050dc8b2ba0443 Mon Sep 17 00:00:00 2001 From: Santiago Troncoso Date: Tue, 24 Feb 2026 11:28:59 +0100 Subject: [PATCH 3/4] fix: LocationDetails reference fix --- code/API_definitions/webrtc-events.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/webrtc-events.yaml b/code/API_definitions/webrtc-events.yaml index fb3bfcb..be79c1c 100644 --- a/code/API_definitions/webrtc-events.yaml +++ b/code/API_definitions/webrtc-events.yaml @@ -909,9 +909,9 @@ components: type: integer description: The sequence number of the notification sent to client originatorLocationDetails: - $ref: '#/components/schemas/LocationDetails + $ref: '#/components/schemas/LocationDetails' receiverLocationDetails: - $ref: '#/components/schemas/LocationDetails + $ref: '#/components/schemas/LocationDetails' MediaSessionStatusUpdate: allOf: From 18a0df152c18006aa66cf7e74739e0de61627d8d Mon Sep 17 00:00:00 2001 From: Santiago Troncoso Date: Tue, 24 Feb 2026 11:45:37 +0100 Subject: [PATCH 4/4] fix: Update originatorLocation on callhandling and regular examples --- code/API_definitions/webrtc-call-handling.yaml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/webrtc-call-handling.yaml b/code/API_definitions/webrtc-call-handling.yaml index e3e5d92..28b3df3 100644 --- a/code/API_definitions/webrtc-call-handling.yaml +++ b/code/API_definitions/webrtc-call-handling.yaml @@ -262,8 +262,8 @@ paths: schema: $ref: '#/components/schemas/MediaSessionInformation' examples: - Media session request: - $ref: '#/components/examples/exampleMediaSessionRequest' + RegularMediaSessionRequest: + $ref: '#/components/examples/exampleRegularMediaSessionRequest' EmergencyMediaSessionRequest: $ref: '#/components/examples/exampleEmergencyMediaSessionRequest' LocatedMediaSessionRequest: @@ -517,7 +517,7 @@ components: enum: - REGULAR - EMERGENCY - locationDetails: + originatorLocationDetails: $ref: '#/components/schemas/LocationDetails' WrtcSDPDescriptor: type: object @@ -688,7 +688,8 @@ components: type: number description: Orientation of the ellipsoid in degrees. examples: - exampleMediaSessionRequest: + exampleRegularMediaSessionRequest: + summary: Regular call initiation with media information value: originatorAddress: tel:+17085852753 originatorName: tel:+17085852753