diff --git a/documentation/API_documentation/FlowsBYON-CallHandling.wsd b/documentation/API_documentation/FlowsBYON-CallHandling.wsd new file mode 100644 index 0000000..f4bf26a --- /dev/null +++ b/documentation/API_documentation/FlowsBYON-CallHandling.wsd @@ -0,0 +1,331 @@ +@startuml BYON Callhandling 0.1.2 + +title "BYON WEB RTC FLOW - Call handling v0.1.2" +autonumber "[0]" + + + +participant "Web\nClient" as WebClient +participant "WebRTC\ngateway" as WebRTC_GW +participant "IMS\nNetwork" as IMS_Network +participant "Remote\nendpoint" as RemoteEndpoint + +' --- Notification Channel + +activate WebClient #LightGray +note right WebClient + It is a precondition to have a valid session with a + valid notification channel for a complete set of + features. + + Valid notification channels are: + - webSocketsdata (channelURL) + - PNSChannelData (registrationToken) + - Webhooks (resourceURL) + +end note + +' --------------------------------------------------------- +' CALL ORIGINATION - WebRTC device initiaties voice session +' --------------------------------------------------------- + +group CALL ORIGINATION + +[-> WebClient: User creates a call + +WebClient -> WebRTC_GW : **POST /vvoip/{apiVersion}/sessions** \n\ + Headers:\n\ + - authorization\n\ + - transactionId\n\ + - clientId\n\ + Body:\n\ + - originatorAddress \n\ + - receiverAddress \n\ + - status \n\ + - offer : sdp_webrtc_offer +activate WebClient + +note right of WebClient +Local or no media provided as initial request +end note + + +WebRTC_GW -> IMS_Network: **SIP INVITE** \n\ +From: originatorAddress \n\ +To: receiverAddress \n\ +sdp_inital_offer + +IMS_Network -> RemoteEndpoint: **SIP INVITE** \n\ +From: originatorAddress \n\ +To: receiverAddress \n\ +sdp_inital_offer + +RemoteEndpoint -> IMS_Network: 100 Trying +IMS_Network -> WebRTC_GW: 100 Trying +WebRTC_GW -> WebClient: **201 Created session** \n\ + - originatorAddress \n\ + - receiverAddress \n\ + - status : "Initial" \n\ + - vvoipSessionId: {vvoipSessionId} + +...Inactivity timer applies... + +RemoteEndpoint -> IMS_Network: **183 Session progress** \n\ +sdp_initial_response +IMS_Network -> WebRTC_GW: **183 Session progress** \n\ +sdp_initial_response +WebRTC_GW --> WebClient: JSON vvoipsession status \n\ + - status: **InProgress** \n\ + - offer: sdp_webrtc_offer \n\ + - answer: sdp_webrtc_answer + +note right of WebRTC_GW +Server asume ACK or notifcation +service confirmation and continues +end note +WebRTC_GW ->IMS_Network: PRACK \n selectedCodec \n localQoS +IMS_Network -> RemoteEndpoint: PRACK \n selectedCodec \n localQoS +RemoteEndpoint -> IMS_Network: 200 OK (PRACK) +IMS_Network -> WebRTC_GW: 200 OK (PRACK) + +group Late media ICE discovery +WebClient <[#purple]-> WebRTC_GW: DTLS Handshake +WebClient <[#purple]-> WebRTC_GW: ICE Connectivity Check +WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ + Headers:\n\ + - authorization\n\ + - transactionId\n\ + - clientId\n\ + Body: \n\ + - status: **In Progress** \n\ + - offer: sdp_webrtc_offer_late \n\ + - answer: sdp_webrtc_answer + +WebRTC_GW ->IMS_Network: UPDATE \n localQoS \n sendrecv +IMS_Network -> RemoteEndpoint: UPDATE \n localQoS \n sendrecv +RemoteEndpoint -> IMS_Network: 200 OK (UDPATE) +IMS_Network -> WebRTC_GW: 200 OK (UPDATE) + +WebClient <- WebRTC_GW: **200** Updated the session status +end + +RemoteEndpoint ->IMS_Network: 180 Ringing +IMS_Network -> WebRTC_GW: 180 Ringing +WebRTC_GW --> WebClient: JSON vvoipsession status\n\ + - status: **Ringing** \n\ + - offer: sdp_webrtc_offer_late \n\ + - answer: sdp_webrtc_answer + +note right of WebRTC_GW + ACK from user endpoint not required + since the WebRTC_GW does nothing with + this confirmation. +end note + +...Ringing timer applies... + +RemoteEndpoint -> IMS_Network: 200 OK (INVITE) +IMS_Network -> WebRTC_GW: 200 OK (INVITE) +WebRTC_GW --> WebClient: JSON vvoipsession status\n\ + - status: **Connected** \n\ + - offer: sdp_webrtc_offer_late \n\ + - answer: sdp_webrtc_answer +WebRTC_GW -> IMS_Network: ACK (200 Ok) +IMS_Network -> RemoteEndpoint: ACK (200 Ok) + +WebClient <--> WebRTC_GW <>: DTLS-SRTP +WebRTC_GW <--> RemoteEndpoint <>: RTP/SRTP + +...Session timer applies... + +[-> WebClient: Hangup +WebClient -> WebRTC_GW: **DELETE /vvoip/{apiVersion}/sessions/{vvoipSessionId}**\n\ + Headers:\n\ + - authorization\n\ + - transactionId\n\ + - clientId +WebRTC_GW -> IMS_Network: BYE +IMS_Network -> RemoteEndpoint: BYE + +RemoteEndpoint -> IMS_Network: 200 OK (BYE) +IMS_Network -> WebRTC_GW: 200 OK (BYE) +WebClient <- WebRTC_GW: **200** Session deleted + +deactivate WebClient +deactivate WebClient + +end + +' ------------------------------------------------------- +' CALL TERMINATION - WebRTC device receives voice session +' ------------------------------------------------------- + +group CALL TERMINATION + +[-> WebClient: Launch app +activate WebClient #LightGray +note right WebClient + It is a precondition to have a valid session with a + valid notification channel for a complete set of + features. + + Valid notification channels are: + - webSocketsdata (channelURL) + - PNSChannelData (registrationToken) + - Webhooks (resourceURL) + +end note +WebClient <-> WebRTC_GW: **POST /racm/{apiVersion}/session** +WebClient <-> WebRTC_GW: **POST /notificationchannel/{apiVersion}/channels** +WebClient <-> WebRTC_GW <>: Notification channel established + +... + +RemoteEndpoint -> IMS_Network: **SIP INVITE** \n\ +From: originatorAddress \n\ +To: receiverAddress \n\ +sdp_inital_offer + +IMS_Network -> RemoteEndpoint: 100 Trying + +IMS_Network -> WebRTC_GW: **SIP INVITE** \n\ +From: originatorAddress \n\ +To: receiverAddress \n\ +sdp_inital_offer + +WebRTC_GW -> IMS_Network: 100 Trying + +WebRTC_GW --> WebClient: JSON vvoipsession status\n\ + - status: **Initial** \n\ + - offer: sdp_webrtc_offer \n\ + - vvoipSessionId: vvoipSessionId +activate WebClient +note left of WebClient +Now call starts to be +processed on the user +device. +end note + +' Retrieve call information +WebClient -> WebRTC_GW: **GET /vvoip/{apiVersion}/sessions/{vvoipSessionId}**\n\ + Headers:\n\ + - authorization\n\ + - transactionId\n\ + - clientId +WebClient <- WebRTC_GW: **200 OK** \n\ + Body: \n\ + - status: **Initial** \n\ + - offer: sdp_webrtc_offer +note right WebRTC_GW + Event notification only wakes + the device. All session info + is gathered from the server. +end note + +' Initial WebClient setup +WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ + Body: \n\ + - status: **In Progress** \n\ + - offer: sdp_webrtc_offer \n\ + - answer: sdp_webrtc_answer +note right of WebClient +Local or no media provided as initial answer +end note +WebRTC_GW -> IMS_Network: **183 SessionInProgress** \n\ +sdp_initial_response +WebRTC_GW -> WebClient: 200 Updated +IMS_Network -> RemoteEndpoint: **183 SessionInProgress** \n\ +sdp_initial_response +RemoteEndpoint -> IMS_Network: PRACK \n selectedCodec \n localQoS +IMS_Network -> WebRTC_GW: PRACK \n selectedCodec \n localQoS +WebRTC_GW -> IMS_Network: 200 OK (PRACK) +IMS_Network -> RemoteEndpoint: 200 OK (PRACK) + +' WebClient Media discovery +group Late Media ICE discovery +WebClient <[#purple]-> WebRTC_GW: DTLS Handshake +WebClient <[#purple]-> WebRTC_GW: ICE Connectivity Check +WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ + Headers:\n\ + - authorization\n\ + - transactionId\n\ + - clientId \n\ + Body: \n\ + - status: **In Progress** \n\ + - offer: sdp_webrtc_offer \n\ + - answer: sdp_webrtc_answer_late + + WebRTC_GW ->IMS_Network: UPDATE \n localQoS \n sendrecv + IMS_Network -> RemoteEndpoint: UPDATE \n localQoS \n sendrecv +RemoteEndpoint -> IMS_Network: 200 OK (UDPATE) +IMS_Network -> WebRTC_GW: 200 OK (UPDATE) + +WebRTC_GW -> WebClient: 200 Updated + +end + +[<- WebClient : Ringing +WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ + Headers:\n\ + - authorization\n\ + - transactionId\n\ + - clientId \n\ + Body: \n\ + - status: **Ringing** \n\ + - offer: sdp_webrtc_offer \n\ + - answer: sdp_webrtc_answer_late +WebRTC_GW -> WebClient: 200 Updated +WebRTC_GW -> IMS_Network: 180 Ringing +IMS_Network -> RemoteEndpoint: 180 Ringing + +[-> WebClient : Answer] +WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ + Headers:\n\ + - authorization\n\ + - transactionId\n\ + - clientId \n\ + Body: \n\ + - status: **Connected** \n\ + - offer: sdp_webrtc_offer \n\ + - answer: sdp_webrtc_answer_late +WebRTC_GW -> WebClient: 200 Updated + +WebRTC_GW -> IMS_Network: 200 OK +IMS_Network -> RemoteEndpoint: 200 Ok +RemoteEndpoint -> IMS_Network: ACK +IMS_Network -> WebRTC_GW: ACK +WebRTC_GW --> WebClient: JSON vvoipsession status\n\ + - status: **Connected** \n\ + - offer: sdp_webrtc_offer \n\ + - answer: sdp_webrtc_answer_late + +WebClient <--> WebRTC_GW <>: DTLS-SRTP +WebRTC_GW <--> RemoteEndpoint <>: RTP/SRTP + +RemoteEndpoint -> IMS_Network: BYE +IMS_Network -> WebRTC_GW: BYE +WebRTC_GW --> WebClient: JSON vvoipsession status\n\ + - status: **Released** \n\ + - offer: sdp_webrtc_offer \n\ + - answer: sdp_webrtc_answer_late + +deactivate WebClient +WebRTC_GW -> IMS_Network: 200 OK (BYE) +IMS_Network -> RemoteEndpoint: 200 OK (BYE) + +end + +@enduml diff --git a/documentation/API_documentation/FlowsBYON-NotificationChannel.wsd b/documentation/API_documentation/FlowsBYON-NotificationChannel.wsd new file mode 100644 index 0000000..06c90ae --- /dev/null +++ b/documentation/API_documentation/FlowsBYON-NotificationChannel.wsd @@ -0,0 +1,79 @@ +@startuml BYON NotificationChannel 0.1.2 + +title "BYON WEB RTC FLOW - Notification channel 0.1.2" +autonumber "[0]" + + + +'participant "Notification\nclient" as WebClient +participant "Web\nClient" as WebClient +participant OAuth #LightGreen +participant "WebRTC\ngateway" as WebRTC_GW +participant "IMS\nNetwork" as IMS_Network +participant "Remote\nendpoint" as RemoteEndpoint + +' --- Notification Channel +group Notification Channel +note right WebClient + Create notification channel for incoming updates. + + Valir notification channels are: + - "WebSockets" + - Requires channelURL + - "PNSChannel" + - Requires regsitrationToken + - "Webhook" + - Requires notificationUrl and notificationAuthToken + + Check details about each noticiation channel + requirements on the API documentation + +end note + +activate WebClient #LightGray + +WebClient -> OAuth: Authentication/refresh Token +OAuth -> WebClient: Access/refresh Token + +WebClient -> WebRTC_GW: **POST /notificationchannel/{apiVersion}/channels** \n\ + Headers:\n\ + - authorization\n\ + - transactionId\n\ + - clientId\n\ + Body:\n\ + - channelType\n\ + - channelData/channelURL\n\ + +WebRTC_GW <-> OAuth: Validate Auth-token + +WebRTC_GW -> WebClient: **201 Created**\n\ + Body:\n\ + - channelType\n\ + - channelData/channelURL\n\ + - channelId + +activate WebClient #LightGreen + +WebClient <-> WebRTC_GW <>: Notification channel established +note left WebRTC_GW + It is possible to include any other + optional parameters during the notification + channel creation, depending on the WebRTC + GW notification available functionalities. +end note +end + +@enduml diff --git a/documentation/API_documentation/FlowsBYON-RACM_Service.wsd b/documentation/API_documentation/FlowsBYON-RACM_Service.wsd new file mode 100644 index 0000000..df9a4c7 --- /dev/null +++ b/documentation/API_documentation/FlowsBYON-RACM_Service.wsd @@ -0,0 +1,121 @@ +@startuml BYON Registration 0.1.2 + +title "BYON WEB RTC FLOW - Registration - 0.1.2" +autonumber "[0]" + + +participant WebClient +participant OAuth #LightGreen +participant "WebRTC\ngateway" as WebRTC_GW +participant "IMS\nNetwork" as IMS_Network +participant "Remote\nendpoint" as RemoteEndpoint + +' --- USER AUTHENTICATION and REGISTRATION +group USER AUTHENTICATION and REGISTRATION + +[-> WebClient: Launch app +activate WebClient #LightGray + +WebClient -> OAuth: Authentication/refresh Token +OAuth -> WebClient: Access/refresh Token +WebClient -> WebRTC_GW: **POST /racm/{apiVersion}/sessions**\n\ + Headers: \n\ + - authorization \n\ + - transactionId \n\ + Body: \n\ + - deviceId \n\ + - channelId + +note right WebClient + **Note** channelId is an optional argument + only provided when an independent external + notification is created prior to the RACM + session. Check API doc about it. +end note + +WebRTC_GW <-> OAuth: Validate Auth-token +WebRTC_GW -> IMS_Network: **SIP REGISTER**\nFrom: IMPU\nTo:IMPU\nContact: WebRTC_GW +IMS_Network -> WebRTC_GW: 100 Trying +IMS_Network -> WebRTC_GW: 200 OK +WebRTC_GW -> WebClient: **200 OK**\n\ + Body:\n\ + - clientid\n\ + - regInfo/msisdn\n\ + - regInfo/regStatus\n\ + - racmSessionId +note over WebClient + Registrations will be valid while + auth-token is still valid. +end note + +' --- Refreshing of registration +group REGISTRATION REFRESH + note over WebRTC_GW + Periodically refresh REGISTER + while Auth-Token is still valid + end note + WebRTC_GW -> IMS_Network: SIP RE-REGISTER + IMS_Network -> WebRTC_GW: 200 OK + +else +note over WebClient + When auth-token is about to + expire, it is need to refresh + and update WebRTC GW. + Use **racmSessionId** from 200OK + response body to POST racm/ + endpoint (session update) +end note +WebClient -> WebRTC_GW: **PUT /racm/{apiVersion}/sessions/{racmSessionId}** \n\ + Headers: \n\ + - authorization \n\ + - transactionId \n\ + - clientId + +note over WebRTC_GW + Auth-token refresh and check +end note +WebRTC_GW -> IMS_Network: SIP RE-REGISTER +IMS_Network -> WebRTC_GW: 200 OK +WebRTC_GW -> WebClient: **204 No content** +end +end + +note right WebClient + Notification channel required + to receive sessions and to + wakeup user's device +end note + +WebClient <-> WebRTC_GW: **POST /notificationchannel/{apiVersion}/channels** +WebClient <-> WebRTC_GW <>: Notification channel established + +' --- DE-REGISTRATION +group DE-REGISTRATION + +[-> WebClient: Closes session + +note over WebClient + Graceful logout +end note +WebClient -> WebRTC_GW: **DELETE /racm/{apiVersion}/sessions/{racmSessionId}** \n\ + Headers: \n\ + - authorization \n\ + - transactionId \n\ + - clientID +WebRTC_GW -> IMS_Network: SIP DE-REGISTER +IMS_Network -> WebRTC_GW: 200 OK +WebRTC_GW -> WebClient: **204 No content** + note right: Clean up session context + +deactivate WebClient + +note over WebClient + Non-graceful logout will let the + auth token to expire, leading to + a SIP DE-REGISTRATION on the + WebRTC gateway +end note +end + +@enduml diff --git a/documentation/API_documentation/webrtc voice api.md b/documentation/API_documentation/webrtc voice api.md index 3dae72f..e448b46 100644 --- a/documentation/API_documentation/webrtc voice api.md +++ b/documentation/API_documentation/webrtc voice api.md @@ -101,3 +101,29 @@ Several exceptions might occur during the API operations, | PUT /session/{sessionId}/status | Modify a Voice session | This modification request is to modify the call object attributes such as media properties included in the SDP (e.g. call placed on hold). | | DELETE /session/{sessionId} | Delete a Voice session | When the call is terminated from the client's end, the corresponding Voice session object is deleted, which will trigger the WebRTC GW to initiate a Call release into the MNO's IMS network. | | | | When the call is released from the network's end, the call release notification is sent over the websocket notification channel, which will result in deleting of the Voice session object. | + +### Event status enumeration + +There are defined a series of status for the call. These status are used by the session endpoint for PUT actions and also used by the event notification channel. + +Status are: + +| Status | SIP Response | Description | +| ------ | ------------ | ----------- | +`Initial` | n/a | Initial status of transaction +`InProgress` | 183 Session progress | Updated info about a session +`Ringing` | 180 Ringing | Destination user agent is alerting the user +`Proceding` | n/a | Call progressing +`Connected` | 200 OK | Session in place +`Terminated` | n/a | The call is being terminated, but not defined the reason. It needs to add a "reason" +`Hold` | n/a | Status when a call on hold +`Resume` | n/a | Status for a call that is resumed +`SessionCancelled` | n/a | 487 Resquest terminated or CANCEL+200OK +`Declined` | 603 Decline | The destination does not want to participate +`Failed` | 412 / 430 | Call terminated and failed without 200 OK +`Waiting` | 182 Queued | Call pending to be processed +`NoAnswer` | 408 Request Timeout | No answer before timer expires +`NotReachable` | 404 Not found | Destination requested not found +`Busy` | 486 Busy here | Callee is busy + +Ref. for status mapping: https://www.gsma.com/newsroom/wp-content/uploads//NG.114-v1.0-3.pdf \ No newline at end of file diff --git a/documentation/README b/documentation/README new file mode 100644 index 0000000..aca4f53 --- /dev/null +++ b/documentation/README @@ -0,0 +1,10 @@ +This folder include documentation about how to use the API SPECS defined on the code/API_definitions folder. + +* Check [BYON API Specs](../code/API_definitions/) for REST API OpenAPI specs. +* Check [API documentation](API_documentation/) folder for the activity diagrams that depict a detailed inetraction between apps, WebRTC GW and IMS network. + * Check [WebRTC voice API](API_documentation/webrtc%20voice%20api.md/) document for introduction to the API. + +This folder includes also + +* Original meeting minutes. Find updated meeting minutes here: https://wiki.camaraproject.org/display/CAM/WebRTC+Meeting+Minutes +* Other supporting documents \ No newline at end of file