anynode WebRTC communication
Communication between anynode and WebRTC Client
December 18, 2025
1 Introduction
This document describes the communication between the WebRTC client and anynode. The WebRTC client can be a JavaScript application or any other client e.g. flutter. The samples in this document focus on JavaScript. The document describes authentication, registration, signaling and media exchange.
2 Transport Protocols
There is no standard for signaling in WebRTC. In general, any kind of message exchanges can be used, e.g.:
-
WebSocket
-
XHR(XMLHttpRequest)
-
HTTP Long Polling
-
Cloud messaging e.g., Google Firebase Cloud Messaging
To receive incoming calls a WebRTC Client registered to anynode requires a permanent connection. The following chapter assume that WebSocket connections are used. The signaling channel is always established from the WebRTC client and is expected to be open all the time, otherwise anynode would not be able to signal calls to the WebRTC client. However, reloading the web page would close the WebSocket connection. The implementation will ensure, that a WebSocket connection request can be assigned to an existing registration. The identifier to assign a WebSocket connection to an existing registration are assigned by anynode.
3 WebSocket
The WebSocket connection is initiated from the JavaScript by creating a “WebSocket-Instance” and pass the URL to connect to the server. The URL anynode is listening for WebSocket connections can be specified in the anynode configuration. Depending on the scheme a secure (wss) or insecure (ws) connection is established.
conn = new WebSocket('ws: localhost:8080');
conn = new WebSocket('wss: localhost:8080');
Using secure connections require that the certificate configured in anynode is accepted by the Web browser. WebSocket connections start via HTTP which is immediately upgraded to WebSocket. Following data frames contain a small header, data from the client to the server is masked.
4 Authentication
Authentication is done via the transport protocol and depends on the configuration of anynode. The authentication can be done by a username and password or by a token.
4.1 Authentication via username and password
For HTTP based transport protocols like WebSocket’s the HTTP authentication is used, either basic or digest. The username and password can be directly given to the URL when the WebSocket is created in JavaScript.
conn = new WebSocket('wss://testuser:12345678@localhost:8080');
Depending on the configuration anynode will request either digest or basic authentication. Authentication on the client side is handled by JavaScript.
4.2 Authentication via token
For client web applications that do not want to handle a password for security reasons, a token-based authentication can be used. This might be used for web sites that implement a “call me” button and just want to make a single outgoing call. In such a case a login and assignment of a username and local number is not necessary, and the WebSocket connection is closed once the call is finished. However client web applications using the token based authentication may also assign a username and local number to receive incoming calls.
Creating WebSocket's in JavaScript does not allow to set HTTP header, so support for authentication type Bearer is not available. The access token will be passed as parameter named access_token in the query part or the URI.
conn = new WebSocket('wss://localhost:8080?access_token=TOKEN-VALUE');
The token should be created by the web server hosting the client web application. The token must be formatted as a JSON web token (JWT) according to RFC 7519. Supported algorithm for signing depends on the configuration of anynode, currently supported are HS256 and RS256. The token consists of the JOSE header and the JWT claim set, both are JSON formatted.
The JOSE header must contain the type, which must be set to JWT, and the algorithm used for signing. Optionally a nonce parameter may be specified, which can be used for assignment upon token refresh.
The JWT claim set must contain the issuer and the expiration time in Seconds Since the Epoch. Optional a username can be specified.
4.2.1 Signing
The token must be signed by the issuer and will be validated by anynode. Signing can be done with symmetric or asymmetric keys, depending on the algorithm specified in the JOSE header. The corresponding parameter must be configured in anynode frontend. For the algorithm HS256 the symmetric key used by the issuer of the token must be configured in anynode. For the algorithm RS256 the public part of the X.509 certificate used by the issuer to sign the token must be configured in anynode.
4.2.2 Token refresh
When a token expired, the WebSocket connection is closed, and all existing connections based on this connection are disconnected. The client web application may refresh a token by using the nonce parameter in the JOSE header.
The refresh is not possible on the existing WebSocket connection. The client web application must create a new WebSocket connection with a new token using the same nonce parameter. The new WebSocket will be assigned to the existing instance, and the old WebSocket connection will be closed.
4.2.3 User identification
For clients that authenticate via username and password and phone number assignment is done via the username during login, the username must match the authenticated user. Refer to section 5.2. To have the same level of protection and avoid that a client uses any username for login the username must be part of the JWT claim set of the token.
4.2.4 Example JWT
To create the JWT the JOSE header and the JWT claim set are base64 encoded and combined via a period. Over this sequence the hash is created, base64 encoded and added after another period.
Processing the JOSE header:
The above JOSE header as base64 encoded sequence.
Processing the JWT claim set:
The above JWT claim set as base64 encoded sequence.
Combined by a period creates the following sequence (with line breaks for display purposes only).
Create the hash with the symmetric key $C&F)J@McQfTjWnZr4u7x!A%D*G-KaPd and base64 encode the hash.
The final JWT (with line breaks for display purposes only).
5 Phone number assignment
Depending on the anynode configuration the local phone number of the WebRTC client can be specified by the client or assigned by anynode during registration of the WebRTC client. The expected mode depends on the anynode configuration.
5.1 Phone number specified by WebRTC client
In this mode the WebRTC client specifies a phone number it wants to register to receive calls. The phone number might be validated by anynode by querying a directory (e.g., LDAP).
5.2 Phone number assigned by anynode
In this mode the WebRTC client specifies a username during registration. The corresponding phone number will be read from a directory by anynode.
Note that the username must correspond to the username used for authentication.
6 Background Notification
The WebRTC client running on a mobile device or as web-browser application may not be in foreground when a call should be routed to the client. In this case no WebSocket connection between the WebRTC client and anynode may exist to signal the call to the client. Via the configuration a messaging service can be configured and anynode will send a notification via the messaging service to the client. The client will then establish the WebSocket connection using a token provided with the notification. Via the token the client is assigned to the existing registration instance. Once the client is registered again anynode will signal the call.
The notification is currently supported via Google Firebase Cloud Messaging (FCM), more systems like Windows Push Notification Services (WNS) may follow.
7 Ringing Tone
Any tones to be played to the WebRTC client before a call is connected and media information is exchanged are expected to be generated by the WebRTC client.
8 Operations
There are different types of information that are exchanged between the WebRTC client and anynode via the WebSocket connection. They are called “operations” in the following chapters. The operations are:
Register
-
Register
-
Signaling
-
Media
The “Register” operation is used to register(login) to anynode and to terminate the registration. The “Signaling” operation is used to establish a call and report the call status to the WebRTC client. The “Media” operation is used to exchange media information between the WebRTC client and anynode.
8.1 Data Format
The messages exchanged between the WebRTC client and anynode will be JSON formatted. The JSON format is kept flexible based on a JSON schema. The same schema is used for all types or operations. Depending on the type of operation and the action not all fields may be present in the JSON data, or fields may be empty.
8.1.1 Version field
The version field must always be present and contains the version of the used JSON script. The version must be set to 1. If the version field does not exist, or does not contain a value of '1' the connection is terminated.
8.1.2 Operation Field
The operation field must always be present and include one of the enumeration values.
8.1.3 Action Field
The action field must always be present and include one of the enumeration values. Otherwise, the request will be silently discarded. The interpretation of the action field depends on the operation.
8.1.4 State Field
The state field must be present, if the action field is set to status. It may be available for other actions as well. The status is always maintained by anynode and communicated to the WebRTC client.
8.1.5 Reason Field
The reason field must be present, when an action completes (e.g. call terminated). It must include one of the enumeration values.
8.1.6 Identifier Field
The identifier field contains a unique identifier within the operation. The identifier is created by the initiator of the call using the start action.
8.1.7 Transfer Identifier Field
The transfer identifier field contains a unique identifier within the operation. The identifier is created by the initiator of the call using the start action. The transfer identifier is only used in the transfer action.
8.1.8 Notification Configuration Field
The notification configuration field contains the parameter to register the client with the background messaging system, e.g. FCM. The data is configured in anynode and passed unchanged to the client with the start action of the register operation. The usage of this information is optional, the client may use own configuration data or do not use background notification.
8.1.9 Notification Token Field
The notification token field contains the token assigned by the background messaging system when the client registers. The notification token is passed by the client to anynode with the status action of the register operation.
8.1.10 Notification URL Field
The notification URL field contains optional information that is passed to the client with the background notification. The notification URL is passed by the client to anynode with the status action of the register operation. The client may use this information to restore a web page.
8.1.11 Local Address Field
The localAddress field contains the local addresse of the WebRTC client. Note that the local address is always the address of the WebRTC client, regardless of the call direction.
8.1.12 Remote Address Field
The remoteAddress field contains the address to be dialed, if the WebRTC client send the “start” “action”, or the remote address if anynode sends the “start” “action”. The remote address is always the address of the remote side, from the view of the WebRTC client, regardless of the call direction.
8.1.13 Local side desciption
The localSideDescription field contains the symbolic description of the side sending the information. The field is optional. The WebRTC client may place any text here that describes the client. The information is shown in the anynode call history in the User Agent column. By default the anynode WebRTC client API sets this field to anynode WebRTC JavaScript 1.0.0. The field is set by anynode with the register response to anynode <VERSION>
8.1.14 Assignment Field
The assignment field must be present, if the action field contains the username and / or dial string to assign a phone number during registration (login) to anynode.
8.1.15 SDP field
The sdp field contains the session description. Depending on the action this is the offer or answer SDP.
8.1.16 ICE field
The ice field contains one or more ICE candidates. In general, the ICE candidates are part of the SDP, however depending on the configuration of the RTCPeerConnection by the JavaScript the WebRTC API delivers the SDP and ICE as different results. To avoid that the JavaScript has to modify SDP, both information is passed unchanged to anynode. If the ICE candidates are part of the SDP, which is the preferred handling, the field is not required.
9 Register Operation
To start the communication with anynode the WebRTC client send a register operation including the username and / or dial string in the assignment field. The username or dial string is used to assign the phone number to listen for. Depending on the result a registartion identifier is assigned, or an error is reported.
9.1 Actions
The following values for the action field are supported by the register operation.
start
Initiates the registration (login) of the WebRTC client with anynode.
terminate
Terminates an existing registration.
status
Report background notification infromation from the WebRTC client to anynode.
9.2 Successful Registration
WebRTC client request sent to anynode.
anynode response to WebRTC client.
9.3 Successful Registration with Notification
WebRTC client request sent to anynode.
anynode response to WebRTC client including configuration for background notification.
WebRTC client registers with messaging system and sends client notification data to anynode.
9.4 Failed Registration
WebRTC client request sent to anynode.
anynode response to WebRTC client.
9.5 Recreate existing Registration
The WebSocket connection between anynode any the WebRTC client may be disconnected. Reasons could be the reload of a web page or a mobile client in background mode. For both scenarios anynode provides methods to recreate a registration without a new login.
9.5.1 Web page reload
If the WebRTC client is implemented as part of a web page and the page is reloaded the WebSocket connection is lost. To recreate the existing registration the WebRTC client must store the identifier assigned with the initial registration. It is recommended that the JavaScript extracts the identifier from the initial response to the registration request and stores it in the document.cookie. With a new registration request e.g., after a page refresh, the identifier is restored from document.cookie and reused. The time the identifier is valid after the WebSocket connection is lost is configurable in anynode frontend.
The identifier is used in the query part of the URL that initiates the WebSocket connection.
If the identifier is valid the WebSocket connection is accepted without authentication and the registration information are sent by anynode to the WebRTC client.
If the recreation of the registration was successful and a call exists, anynode will sent information about call states etc. to the WebRTC client.
The time a registration is valid without an established WebSocket connection can be configured in anynode. If the identifier is already expired the WebSocket connection is refused with 401 authentication required and the WebRTC client must do a new registration.
9.5.2 Wakeup from background mode
If the WebRTC client is implemented as mobile device, the WebSocket connection may be disconnected when the device enters the sleep mode, or the app is in background mode. If a call should be route to the client, anynode must notify the client to reestablish the WebSocket connection. This requires that the WebRTC client has registered at the notification system and provided the notification parameter to anynode with the status action of the register operation. Refer to section section 9.3 for more information on registration for notifcation.
When anynode sends the notification to the notification system the following JSON formatted data is passed.
The field caller contains the number of the side that initiated the call and may be used to display a notification message. The field url contains an optional URL passed to anynode with the status action during registartion.
The field wakeupToken contains the token to be used in the query part of the URL that initiates the WebSocket connection.
If the wakeup token is still valid the WebSocket connection is accepted without authentication and the registration information are sent by anynode to the WebRTC client. Note that a new session identifier will be assigned.
Once the WebSocket connection is established the incoming call is signalled to the WebRTC client.
9.6 Terminate Registration
WebRTC client request sent to anynode.
anynode response to WebRTC client.
10 Signaling Operation
Calls may be initiated from anynode or the WebRTC client. The call status is always reported from anynode to the client. This chapter covers only the signaling operation, media information is handled in the chapter Media Operation.
10.1 Actions
The following values for the action field are supported by the signaling operation.
start
Initiates a call. The “start” action can be send by anynode or the WebRTC client. The sender of the start action assigns a unique identifier to be used in all communication for the call.
status
Reports the current call status. The status action is sent from anynode to the WebRTC client if the call state changes. The WebRTC client may use this information to display the call state.
accept
The accept action is sent by the WebRTC client to anynode to get a call initiated by anynode to the ringing state. Using this action is optional, the WebRTC client may directly answer a call. The new call state will be reported by anynode.
answer
The answer action is sent by the WebRTC client to anynode to answer a call initiated by anynode. The new call state will be reported by anynode.
terminate
The terminate action is sent by the WebRTC client to anynode to terminate a call. The call may be initiated by anynode or the WebRTC client. The new call state will be reported by anynode.
transfer
The transfer action is sent by the WebRTC client to anynode to transfer two calls. For both calls anynode will sent the terminated status.
hold
The hold action is sent by the WebRTC client to anynode to place a call on hold. The new call state will be reported by anynode.
retrieve
The retrieve action is sent by the WebRTC client to anynode to retrieve a call previously placed on hold. The new call state will be reported by anynode.
10.2 Call Identifier
The initiator of a call creates a unique identifier, which is used in the identifier field for all exchanged information. The identifier remains valid until anynode reports the status terminated.
It is recommended to use the universal unique identifier (UUID) format. The identifier may contain alphanumerical characters, the minus sign and the underscore. If an identifier did not conform to this, the call is rejected.
10.3 Successful Call initiated by the WebRTC client
WebRTC client initiates a new call to 4953638195999 (local address is optional).
anynode reports call ringing to WebRTC client.
anynode reports call active (connected) to WebRTC client.
WebRTC client initiates the termination of the call (address information is optional).
anynode reports call state terminating to WebRTC client.
anynode reports call state terminatied to WebRTC client.
10.4 Successful Call initiated by anynode
anynode initiates a new call from 4953638195999.
WebRTC client answers the call (address information is optional).
anynode reports call state active (connected) to WebRTC client.
anynode reports call state terminated to WebRTC client.
10.5 Failed Call initiated by the WebRTC client
WebRTC client initiates a new call to 4953638195999.
anynode reports call ringing to WebRTC client.
anynode reports call terminated to WebRTC client.
10.6 Failed Call initiated by anynode
anynode initiates a new call from 4953638195999 to 4953638195123.
WebRTC client rejects (terminates) the call (address information is optional).
anynode reports call terminated to WebRTC client.
10.7 Hold and retrieve reported by anynode
The following scenario expects a call in the “active” state initiated by anynode or the WebRTC client.
anynode reports the holding state to the WebRTC client.
anynode reports the call is retrieved by sending the active state to the WebRTC client.
10.8 Hold and retrieved initiated by the WebRTC client
The following scenario expects a call in the “active” state initiated by anynode or the WebRTC client.
WebRTC client places the call on hold.
anynode reports the held state to the WebRTC client.
WebRTC client retrieves the call previously placed on hold.
anynode reports the call is retrieved by sending the active state to the WebRTC client.
10.9 Call transfer initiated by WebRTC client
The following scenario expects two calls in the “active” state initiated by anynode or the WebRTC client.
WebRTC client initiates the call transfers.
anynode reports the terminatedterminated state of the transferor to the WebRTC client.
anynode reports the terminatedterminated state of the transferee to the WebRTC client.
11 Media Operation
Once a call is initiated and the call identifier is assigned, media operations can be exchanged. Media is exchanged in a way that one side sends a media offer and the other side responds with a media answer.
Depending on the operation mode, the JavaScript WebRTC API differentiates between the SDP information and the ICE candidates. Therefore, different fields are reserved in the data format. Having ICE candidates in the SDP is the preferred way.
The RTCPeerConnection should be configured to complete the gathering of ICE candidates before the SDP is generated.
The SDP and ICE candidate information can be quite huge. To simplify the sample media flows below, abbreviated SDP and candidate information are used.
11.1 Actions
The following values for the action field are supported by the media operation.
offer
The offer action is sent by the WebRTC client or anynode to initiate a media negotiation
answer
The answer action is sent by the WebRTC client or anynode to complete a media negotiation..
11.2 Simple Media Negotiation
anynode initiates media negotiation.
WebRTC client completes media negotiation.