openapi: 3.0.3

info:

title: WebRTC Events

description: |-

# Introduction

This API provide REST API for a client, browser or native application, to

receive events about updates of an active session or new sessions requests

(incoming calls) or registration termination.

Any device can subscribe to media session events for accessible active media sessions using the

`sessionId` to identify the media session to track. Using a valid

`registrationId` it can subscribe to new media sessions events (new calls).

This allows the device applications to update the UI while media sessions

are progressing and also, allows the device to receive new session request,

generating incoming call scenarios for non-SIM devices.

A classic use case is the negotiation of a live media session (call), that

requires multiple asynchronous events from server side. Other classic

example, is to notify that a subscriber is not logged into the network

anymore and requires refresh, for example, when the IMS expires the

device registration.

In addition, this API, allows to an external service to create "notification

channels" for other systems that does no support the async event mechanisms.

For instance, a classic browser using websockets to receive server-side

events.

**Use cases to cover:**

- Functional:

- A push notification service based on an external webhook

- A browser that requires a WS to receive events from the server side.

- This will require to create a dedicated endpoint using another

network API or external system.

- Observability:

- A monitoring system that wants to monitor registration status of

devices

- A call audit application that requires to remotely monitor call status

# Relevant terms and definitions

- **BYON**: Bring Your Own Number. A commercial name for the functionality

to use your network credentials and phone number identity to non-SIM

devices using media sessions.

- **media session**: An exchange of media between devices.

Typical example of session is a "single one-to-one call".

- **mediaSessionId**: Unique identifier of a Voice or Video **session** using

webrtc-call-handling API. Retrieved using the `webrtc-call-handling` API

- **registration**: A device status in which the device is properly

identified and recognized as reachable by the server side of the network.

- **registrationId**: Unique identifier of an device **registration**.

Retrieved using the `webrtc-registration` API

# API functionality

The CAMARA subscription model is detailed in the CAMARA API design guideline

document and follows CloudEvents specification.

This API allows to create an explicit notification channel for two types of

events. It is mandatory in the subscription to provide the event type for

which the client would like to subscribe.

Following event types are managed for this API:

- `org.camaraproject.webrtc-events.v0.session-status`

- Events triggered for any media session related event (e.g. far end new

media endpoints)

- `org.camaraproject.webrtc-events.v0.session-invitation`

- Events triggered when a new session is requested (e.g. incoming call

received)

- `org.camaraproject.webrtc-events.v0.registration-ends`

- Events triggered when a webrtc registration is terminated (e.g. webrtc registration expired)

Note: Additionally to these list, ``org.camaraproject.webrtc-events.v0.subscription-ended``

notification `type` is sent when the subscription ends.

This notification does not require dedicated subscription.

It is used when:

- the subscription expire time has been reached (optionally set by the

requester)

- the maximum number of subscription events has been reached (optionally

set by the requester)

- the subscription was deleted by the requester

- the Access Token `sinkCredential` expiration time has been reached

(optionally set by the requester)

- the API server has to stop sending notification prematurely

## 1. Session events (session-status)

Find more information at the Schema description.

A `org.camaraproject.webrtc-events.v0.session-status` event includes

session information updates. With the same schema that is used with the

WebRTC Call Handling API, when retrieving information from the

`GET /webrtc-call-handling/session/{mediaSessionId}` endpoint.

In general lines, it is emitted each time that an event happens within the

subscribed session. This might happen when SDP updates are included for any

party or when the call is finished due an ordered cleanup or a service

outage. Any other any relevant internal event could be transmitted through

this channel (eg.: Any SIP response is potentially a

session-status event.

Regarding the SDP descriptions for offer and answer:

- The offer, which MUST be present in a request from the application to the

server to create a session. Note that the offer can be absent in a session

created by the server as part of an offerless INVITE [RFC3261].

- For the answer. This type represents an answer in WebRTC Signaling. This

element is not present in case there is no answer yet, or the session

invitation has been declined by the Terminating Participant. This element

MUST NOT be present in a request from the application to the server to

create a session.

## 2. New session request (session-invitation)

Find more information at the Schema description.

A `org.camaraproject.webrtc-events.v0.session-invitation` event

includes information about new requested sessions (incoming calls), it

requires a valid registration on the network.

This event is triggered each time that the endpoint is requested to join

an incoming new session. This is done, usually, to indicate that a new

media "call" is incoming. In practical terms, this is a new media

session that requests the endpoint presence. The event include all

functional information required to join the session (media info, caller).

When a new session is requested, it will include context information:

identification of the caller and other possible carrier data to

contextualize (call subject, branding info, etc). It will also include

a unique SessionId, to create a dedicated subscription and receive events

about the session itself and its status progressing inside the network.

## 3. Subscription ends (subscription-ended)

A `org.camaraproject.webrtc-events.v0.subscription-ended` event indicates that

the endpoint will no longer be notified when a new event occurs. From

the developer's point of view, receiving the subscription-ended event should

signal the need to check the event subscription status and attempt to refresh

it in order to continue receiving new event notifications.

## 4. Registration ends (`registration-ends`)

A `org.camaraproject.webrtc-events.v0.registration-ends` event indicates that a previously active registration has ended and is no longer valid.

From a developer's point of view, reception of the `registration-ends` event should be treated as a signal to renew the WebRTC registration in order to continue receiving or initiating calls for the registered phone number.

# Authorization and authentication

The "Camara Security and Interoperability Profile" provides details of how an

API consumer requests an access token. Please refer to Identity and Consent

Management (https://github.com/camaraproject/IdentityAndConsentManagement/)

for the released version of the profile.

The specific authorization flows to be used will be agreed upon during the

onboarding process, happening between the API consumer and the API provider,

taking into account the declared purpose for accessing the API, whilst also

being subject to the prevailing legal framework dictated by local legislation.

In cases where personal data is processed by the API and users can exercise

their rights through mechanisms such as opt-in and/or opt-out, the use of

three-legged access tokens is mandatory. This ensures that the API remains

in compliance with privacy regulations, upholding the principles of

transparency and user-centric privacy-by-design.

# 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

version: 0.2.0

x-camara-commonalities: 0.6

externalDocs:

description: Product documentation at CAMARA

url: https://github.com/camaraproject/WebRTC

servers:

- url: "{apiRoot}/webrtc-events/v0.2"

variables:

apiRoot:

default: http://localhost:9091

description: API root

tags:

- name: Webrtc-events Subscription

description: |-

Operations to manage event subscriptions for WebRTC Event APIs.

Directly related with webrtc-call-handling and webrtc-registration.

paths:

/subscriptions:

post:

tags:

- Webrtc-events Subscription

summary: "Create a webrtc-events event subscription"

description: |-

Create a webrtc-events event subscription. For the corresponding type:

- `org.camaraproject.webrtc-events.v0.session-invitation`: new calls event

- `org.camaraproject.webrtc-events.v0.session-status`: updates on specific call

- `org.camaraproject.webrtc-events.v0.registration-ends`: registration termination event

To subscribe and receive notifications about new calls, a

`session-invitation` subscription is required using the `registrationId`

obtained from webrtc-registration API.

Once you create a new media session or receive an

new call event, you can subscribe to `session-status` to receive

updates about the media session in progress using the

`mediaSessionId` unique identifier.

operationId: createNotificationChannelSubscription

parameters:

- $ref: "#/components/parameters/x-correlator"

security:

- openId:

- webrtc-events:org.camaraproject.webrtc-events.v0.session-status:create

- webrtc-events:org.camaraproject.webrtc-events.v0.session-invitation:create

- webrtc-events:org.camaraproject.webrtc-events.v0.registration-ends:create

requestBody:

content:

application/json:

schema:

$ref: "#/components/schemas/SubscriptionRequest"

examples:

INVITE_SUBSCRIPTION (session-invitation):

$ref: "#/components/examples/INVITE_SUBSCRIPTION"

SESSION_SUBSCRIPTION (session-status):

$ref: "#/components/examples/SESSION_SUBSCRIPTION"

REGISTRATION_ENDS_SUBSCRIPTION (registration-ends):

$ref: "#/components/examples/REGISTRATION_ENDS_SUBSCRIPTION"

required: true

callbacks:

notifications:

"{$request.body#/sink}":

post:

summary: "notifications callback"

description: |-

Important: this endpoint is to be implemented by the API

consumer. The webrtc-events server will call this endpoint

whenever a webrtc-events event occurs. `operationId` value will

have to be replaced accordingly with WG API specific semantic.

operationId: createNotificationChannelSubscription

parameters:

- $ref: "#/components/parameters/x-correlator"

requestBody:

required: true

content:

application/cloudevents+json:

schema:

$ref: "#/components/schemas/CloudEvent"

examples:

NEW_SESSION_INCOMING (session-invitation):

$ref: "#/components/examples/NEW_SESSION_INCOMING"

SESSION_UPDATE (session-status):

$ref: "#/components/examples/SESSION_UPDATE"

REGISTRATION_EXPIRED (registration-ends):

$ref: "#/components/examples/REGISTRATION_ENDS"

SUBSCRIPTION_ENDED (subscription-ended):

$ref: "#/components/examples/SUBSCRIPTION_ENDED"

responses:

"204":

description: Successful notification

headers:

x-correlator:

$ref: "#/components/headers/x-correlator"

"400":

$ref: "#/components/responses/Generic400"

"401":

$ref: "#/components/responses/Generic401"

"403":

$ref: "#/components/responses/Generic403"

"410":

$ref: "#/components/responses/Generic410"

"429":

$ref: "#/components/responses/Generic429"

security:

- {}

- notificationsBearerAuth: []

responses:

"201":

description: Created

headers:

x-correlator:

$ref: "#/components/headers/x-correlator"

content:

application/json:

schema:

$ref: "#/components/schemas/Subscription"

"202":

description: Request accepted to be processed. It applies for async creation process.

headers:

x-correlator:

$ref: "#/components/headers/x-correlator"

content:

application/json:

schema:

$ref: "#/components/schemas/SubscriptionAsync"

"400":

$ref: "#/components/responses/CreateSubscriptionBadRequest400"

"401":

$ref: "#/components/responses/Generic401"

"403":

$ref: "#/components/responses/SubscriptionPermissionDenied403"

"409":

$ref: "#/components/responses/Generic409"

"422":

$ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422"

"429":

$ref: "#/components/responses/Generic429"

get:

tags:

- Webrtc-events Subscription

summary: "Retrieve a list of webrtc-events event subscription"

description:

Retrieve **a list** of webrtc-events subscription(s) with detailed

information. Including configuration data and current status.

operationId: retrieveNotificationChannelSubscriptionList

parameters:

- $ref: "#/components/parameters/x-correlator"

security:

- openId:

- webrtc-events:read

responses:

"200":

description: List of event subscription details

headers:

x-correlator:

$ref: "#/components/headers/x-correlator"

content:

application/json:

schema:

type: array

minItems: 0

items:

$ref: '#/components/schemas/Subscription'

"400":

$ref: "#/components/responses/Generic400"

"401":

$ref: "#/components/responses/Generic401"

"403":

$ref: "#/components/responses/Generic403"

/subscriptions/{subscriptionId}:

get:

tags:

- Webrtc-events Subscription

summary: "Retrieve a webrtc-events event subscription"

description: |

Retrieve webrtc-events subscription detailed information for a given

subscription. Including configuration data and current status.

operationId: retrieveNotificationChannelSubscription

security:

- openId:

- webrtc-events:read

parameters:

- $ref: "#/components/parameters/SubscriptionId"

- $ref: "#/components/parameters/x-correlator"

responses:

"200":

description: OK

headers:

x-correlator:

$ref: "#/components/headers/x-correlator"

content:

application/json:

schema:

$ref: "#/components/schemas/Subscription"

"400":

$ref: "#/components/responses/SubscriptionIdRequired400"

"401":

$ref: "#/components/responses/Generic401"

"403":

$ref: "#/components/responses/Generic403"

"404":

$ref: "#/components/responses/Generic404"

delete:

tags:

- Webrtc-events Subscription

summary: "Delete a webrtc-events event subscription"

operationId: deleteNotificationChannelSubscription

description: |

API endpoint to delete a given webrtc-events subscription. Action done

to stop receiving notifications about this event subscription.

security:

- openId:

- webrtc-events:delete

parameters:

- $ref: "#/components/parameters/SubscriptionId"

- $ref: "#/components/parameters/x-correlator"

responses:

"204":

description: webrtc-events subscription deleted

headers:

x-correlator:

$ref: "#/components/headers/x-correlator"

"202":

description: Request accepted to be processed. It applies for async deletion process.

headers:

x-correlator:

$ref: "#/components/headers/x-correlator"

content:

application/json:

schema:

$ref: "#/components/schemas/SubscriptionAsync"

"400":

$ref: "#/components/responses/SubscriptionIdRequired400"

"401":

$ref: "#/components/responses/Generic401"

"403":

$ref: "#/components/responses/Generic403"

"404":

$ref: "#/components/responses/Generic404"

components:

securitySchemes:

openId:

type: openIdConnect

openIdConnectUrl: https://example.com/.well-known/openid-configuration

notificationsBearerAuth:

type: http

scheme: bearer

bearerFormat: "{$request.body#/sinkCredential.credentialType}"

parameters:

SubscriptionId:

name: subscriptionId

in: path

description: Subscription identifier that was obtained from the create event subscription operation

required: true

schema:

$ref: "#/components/schemas/SubscriptionId"

x-correlator:

name: x-correlator

in: header

description: Correlation id for the different services

schema:

$ref: "#/components/schemas/XCorrelator"

headers:

x-correlator:

description: Correlation id for the different services

schema:

$ref: "#/components/schemas/XCorrelator"

schemas:

XCorrelator:

type: string

pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$

example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"

ErrorInfo:

type: object

required:

- status

- code

- message

properties:

status:

type: integer

description: HTTP response status code

code:

type: string

description: A human-readable code to describe the error

message:

type: string

description: A human-readable description of what the event represents

SubscriptionRequest:

description: The request for creating a event-type event subscription

type: object

required:

- sink

- protocol

- config

- types

properties:

protocol:

$ref: "#/components/schemas/Protocol"

sink:

type: string

format: uri

pattern: ^https:\/\/.+$

description: The address to which events shall be delivered using the selected protocol.

example: "https://endpoint.example.com/sink"

sinkCredential:

$ref: "#/components/schemas/SinkCredential"

types:

description: |-

Camara Event types eligible to be delivered by this subscription.

Note: the maximum number of event types per subscription will be decided at API project level

type: array

minItems: 1

maxItems: 1

items:

$ref: "#/components/schemas/SubscriptionEventType"

config:

$ref: "#/components/schemas/Config"

discriminator:

propertyName: protocol

mapping:

HTTP: "#/components/schemas/HTTPSubscriptionRequest"

Config:

description: |-

Implementation-specific configuration parameters needed by the subscription manager for acquiring

events. `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` are predefined for CAMARA

specifications.

WebRTC specific event type attributes are included into `WebrtcSubscriptionDetail` schema.

Note: if a request is performed for several event type, all subscribed event will use same `config`

parameters.

type: object

required:

- subscriptionDetail

properties:

subscriptionDetail:

$ref: "#/components/schemas/WebrtcSubscriptionDetail"

subscriptionExpireTime:

type: string

format: date-time

example: 2023-01-17T13:18:23.682Z

description: |-

The subscription expiration time (in date-time format) requested by the API consumer.

It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.

subscriptionMaxEvents:

type: integer

description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. Up to API project decision to keep it.

minimum: 1

example: 5

initialEvent:

type: boolean

description: |-

Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request.

Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered

Up to API project decision to keep it.

Protocol:

type: string

enum: ["HTTP"]

description: Identifier of a delivery protocol. Only HTTP is allowed for now

example: "HTTP"

SinkCredential:

description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target.

type: object

properties:

credentialType:

type: string

enum:

- ACCESSTOKEN

description: |

The type of the credential.

Note: Type of the credential - MUST be set to ACCESSTOKEN for now

discriminator:

propertyName: credentialType

mapping:

ACCESSTOKEN: "#/components/schemas/AccessTokenCredential"

required:

- credentialType

AccessTokenCredential:

type: object

description: An access token credential.

allOf:

- $ref: "#/components/schemas/SinkCredential"

- type: object

properties:

accessToken:

description: REQUIRED. An access token is a previously acquired token granting access to the target resource.

type: string

accessTokenExpiresUtc:

type: string

format: date-time

description: |

REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired.

In the case of an ACCESS_TOKEN_EXPIRED termination reason, implementation should notify the client before the expiration date.

If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match.

It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.

example: "2023-07-03T12:27:08.312Z"

accessTokenType:

description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).

type: string

enum:

- bearer

required:

- accessToken

- accessTokenExpiresUtc

- accessTokenType

WebrtcSubscriptionDetail:

description: |-

The detail of the requested event subscription.

- org.camaraproject.webrtc-events.v0.session-invitation requires a

valid `registrationId` obtained via registration endpoint.

- org.camaraproject.webrtc-events.v0.session-status requires both, a

valid `registrationId` obtained via registration endpoint and a valid

`sessionId` obtained via session-invitation event or via CallHandling

API

type: object

required:

- registrationId

properties:

deviceId:

type: string

format: uuid

description: |-

The device-id of the client in UUID format. A unique identifier for

the physical device where a registration is initiated. Generated

by the WebRTC application, and consistent within the same device.

sessionId:

type: string

example: 0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EFAAF209EE52FD0BECC5B7CDE645F50DE7D

description: |-

The media session ID created by the network.

The sessionID will identify a unique session between the network and the device client.

It will be included on the events generated.

registrationId:

$ref: "#/components/schemas/RegistrationId"

SubscriptionEventType:

type: string

description: |-

event-type - Event triggered when an event-type event occurred

- `org.camaraproject.webrtc-events.v0.session-status`

- Events triggered for any media session related event (e.g. far end new media endpoints)

- `org.camaraproject.webrtc-events.v0.session-invitation`

- Events triggered for any media endpoint registration event (e.g. incoming session)

- `org.camaraproject.webrtc-events.v0.registration-ends`

- Events triggered for registration termination (e.g. incoming session)

`subscription-ended` is not supported for subscription. It is sent by default

enum:

- org.camaraproject.webrtc-events.v0.session-status

- org.camaraproject.webrtc-events.v0.session-invitation

- org.camaraproject.webrtc-events.v0.registration-ends

Subscription:

description: Represents a event-type subscription.

type: object

required:

- sink

- protocol

- config

- types

- id

properties:

protocol:

$ref: "#/components/schemas/Protocol"

sink:

type: string

format: uri

pattern: ^https:\/\/.+$

description: The address to which events shall be delivered using the selected protocol.

example: "https://endpoint.example.com/sink"

types:

description: |-

Camara Event types eligible to be delivered by this subscription.

Note: the maximum number of event types per subscription will be decided at API project level

type: array

minItems: 1

maxItems: 1

items:

$ref: "#/components/schemas/SubscriptionEventType"

config:

$ref: '#/components/schemas/Config'

id:

$ref: '#/components/schemas/SubscriptionId'

startsAt:

type: string

format: date-time

description: |

Date when the event subscription will begin/began

It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.

example: "2023-07-03T12:27:08.312Z"

expiresAt:

type: string

format: date-time

description: |

Date when the event subscription will expire. Only provided when `subscriptionExpireTime` is indicated by API client or Telco Operator has specific policy about that.

It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.

example: "2023-07-03T12:27:08.312Z"

status:

type: string

description: |-

Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details:

- `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet.

- `ACTIVE`: Subscription creation process is completed. Subscription is fully operative.

- `INACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.

- `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event.

- `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its meta-information is kept).

enum:

- ACTIVATION_REQUESTED

- ACTIVE

- EXPIRED

- INACTIVE

- DELETED

discriminator:

propertyName: protocol

mapping:

HTTP: '#/components/schemas/HTTPSubscriptionResponse'

SubscriptionAsync:

description: Response for a event-type subscription request managed asynchronously (Creation or Deletion)

type: object

properties:

id:

$ref: "#/components/schemas/SubscriptionId"

SubscriptionId:

type: string

description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification).

example: qs15-h556-rt89-1298

RegistrationId:

type: string

description: The unique identifier of the WebRTC registration.

example: ln3C-ttOSk-ObcQ7A0-tYO1LXqy

CloudEvent:

description: The notification callback

required:

- id

- source

- specversion

- type

- time

properties:

id:

type: string

description: identifier of this event, that must be unique in the source context.

source:

$ref: "#/components/schemas/Source"

type:

type: string

description: |-

event-type that describes type of notification

specversion:

type: string

description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version)

enum:

- "1.0"

datacontenttype:

type: string

description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs'

enum:

- application/json

data:

type: object

description: |-

Event details payload. Depending of the event type, it will will include one of the data structures defined on this specification. Along with the subscription-ended, that is an authomatic event.

Check the introduction documentation and the other CAMARA WebRTC APIs for extra info about data structures included on the events.

time:

$ref: "#/components/schemas/DateTime"

discriminator:

propertyName: "type"

mapping:

org.camaraproject.webrtc-events.v0.session-invitation: "#/components/schemas/EventSessionInvitation"

org.camaraproject.webrtc-events.v0.session-status: "#/components/schemas/EventSessionStatus"

org.camaraproject.webrtc-events.v0.subscription-ended: "#/components/schemas/EventSubscriptionEnded"

org.camaraproject.webrtc-events.v0.registration-ends: "#/components/schemas/EventRegistrationEnds"

Source:

type: string

format: uri-reference

minLength: 1

description: |-

Identifies the context in which an event happened - be a non-empty `URI-reference` like:

- URI with a DNS authority:

* https://github.com/cloudevents

* mailto:[email protected]

- Universally-unique URN with a UUID:

* urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66

- Application-specific identifier:

* /cloudevents/spec/pull/123

* 1-555-123-4567

example: "https://notificationSendServer12.supertelco.com"

DateTime:

type: string

format: date-time

description: |-

Timestamp of when the occurrence happened.

It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.

example: "2018-04-05T17:31:00Z"

############################################

EventSessionInvitation:

description: |-

A `org.camaraproject.webrtc-events.v0.session-invitation` event includes an specific type of session

update for new requested sessions. It is emitted when the endpoint is associated with a valid

registration and the endpoint is susbcribed to recive new incoming calls.

This event includes all the context information: caller, callee and possible carrier data to

contextualize (call subject, branding info, etc). It MUST include a mediaSessionId, to allow the

endpoint to subscribe to this new call session.

allOf:

- $ref: "#/components/schemas/CloudEvent"

- type: object

required:

- data

properties:

data:

$ref: "#/components/schemas/MediaSessionInvite"

type:

enum:

- org.camaraproject.webrtc-events.v0.session-invitation

############################################

EventSessionStatus:

description: |-

A `org.camaraproject.webrtc-events.v0.session-status` event includes the session updates provided by

the server. This will include actions form the endpoint and the server (far end).

In general terms, it is received each time that an event happens within the session, and include

all relevant info about the session update.

Most common use is for SDP updates and signaling updates regarding call status.

allOf:

- $ref: "#/components/schemas/CloudEvent"

- type: object

required:

- mediaSessionId

- status

properties:

data:

$ref: "#/components/schemas/MediaSessionStatusUpdate"

type:

enum:

- org.camaraproject.webrtc-events.v0.session-status

############################################

MediaSession:

description: |-

A prototype for media session infomration on Webrtc events. Used as event data schemas for session updates.

type: object

required:

- mediaSessionId

properties:

subscriptionId:

$ref: "#/components/schemas/SubscriptionId"

originatorAddress:

type: string

description: Sender (originator) address

pattern: '^(tel:\+[0-9]{5,15}|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,})$'

example: 'tel:+11234567899'

originatorName:

type: string

description: Friendly name of the call originator

example: 'Alice'

receiverAddress:

type: string

description: Receiver (terminator) address

pattern: '^(tel:\+[0-9]{5,15}|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,})$'

example: 'tel:+11234567899'

receiverName:

type: string

description: Friendly name of the call terminator

example: 'Bob'

status:

type: string

description: |-

Provides the status of the media session. During the session creation,

this attribute contains 'Initial' value

example: Initial

enum:

- Initial

- InProgress

- Ringing

- Proceeding

- Connected

- Terminated

- Hold

- Resume

- SessionCancelled

- Declined

- Failed

- Waiting

- NoAnswer

- NotReachable

- Busy

offer:

$ref: '#/components/schemas/WrtcSDPDescriptor'

answer:

$ref: '#/components/schemas/WrtcSDPDescriptor'

clientCorrelator:

type: string

description: A correlator that the client can use to tag this particular resource representation during a request to create a resource on the server. Note - This allows the client to recover from communication failures during resource creation and therefore avoids re-sending the message in such situations. In case the element is present, the WebRTC GW shall not alter its value, and shall provide it as part of the representation of this resource.

mediaSessionId:

type: string

description: The media session ID created by the network. The mediaSessionId shall not be included in POST requests by the client, but must be included in the notifications from the network to client.

example: '0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EF'

callObjectRef:

type: string

description: The reference to the call object

serverCorrelator:

type: string

description: A correlator that the server instructs the client to use for end to end correlation.

offerRequired:

type: boolean

description: This element shall be included and set to true, if the session updates are received without SDP offer. This element indicates clients to send the offer.

reason:

type: string

description: The description of the event that has happened within the session

sequenceNumber:

type: integer

description: The sequence number of the notification sent to client

MediaSessionStatusUpdate:

allOf:

- $ref: "#/components/schemas/MediaSession"

- type: object

description: MediaSession information emitted on a EventSessionStatus event

required:

- status

MediaSessionInvite:

allOf:

- $ref: "#/components/schemas/MediaSession"

- type: object

description: MediaSession information emitted on a EventSessionInvitation event

required:

- originatorAddress

- receiverAddress

- status

WrtcSDPDescriptor:

type: object

properties:

sdp:

type: string

description: |-

An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section

# CloudEvent and CAMARA standard

EventSubscriptionEnded:

description: event structure for event subscription ends

allOf:

- $ref: "#/components/schemas/CloudEvent"

- type: object

properties:

data:

$ref: "#/components/schemas/SubscriptionEnded"

type:

enum:

- org.camaraproject.webrtc-events.v0.subscription-ended

SubscriptionEnded:

description: Event detail structure for SUBSCRIPTION_ENDED event

type: object

required:

- subscriptionId

- terminationReason

properties:

subscriptionId:

$ref: "#/components/schemas/SubscriptionId"

terminationReason:

$ref: "#/components/schemas/TerminationReason"

terminationDescription:

type: string

TerminationReason:

type: string

description: |-

- NETWORK_TERMINATED - API server stopped sending notification

- SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached

- MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached

- ACCESS_TOKEN_EXPIRED - Access Token sinkCredential (optionally set by the requester) expiration time has been reached

- SUBSCRIPTION_DELETED - Subscription was deleted by the requester

enum:

- MAX_EVENTS_REACHED

- NETWORK_TERMINATED

- SUBSCRIPTION_EXPIRED

- ACCESS_TOKEN_EXPIRED

- SUBSCRIPTION_DELETED

# WebRTC Registration Ends event

EventRegistrationEnds:

description: event structure for event subscription ends

allOf:

- $ref: "#/components/schemas/CloudEvent"

- type: object

required:

- data

properties:

data:

$ref: "#/components/schemas/RegistrationEnds"

type:

enum:

- org.camaraproject.webrtc-events.v0.registration-ends