From 1997a8eecbee4539bef4265b806c1be9386144a9 Mon Sep 17 00:00:00 2001
From: Joachim Bauch <bauch@struktur.de>
Date: Wed, 15 Feb 2023 11:07:56 +0100
Subject: [PATCH] Add docs on internal clients.

---
 docs/standalone-signaling-api-v1.md | 94 +++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/docs/standalone-signaling-api-v1.md b/docs/standalone-signaling-api-v1.md
index 4d4af96..69ea27e 100644
--- a/docs/standalone-signaling-api-v1.md
+++ b/docs/standalone-signaling-api-v1.md
@@ -141,6 +141,7 @@ Message format (Client -> Server):
       "type": "hello",
       "hello": {
         "version": "the-protocol-version",
+        "features": ["optional", "list, "of", "client", "feature", "ids"],
         "auth": {
           "url": "the-url-to-the-auth-backend",
           "params": {
@@ -307,6 +308,7 @@ Message format (Client -> Server):
       "type": "hello",
       "hello": {
         "version": "the-protocol-version",
+        "features": ["optional", "list, "of", "client", "feature", "ids"],
         "auth": {
           "type": "the-client-type",
           ...other attributes depending on the client type...
@@ -869,6 +871,98 @@ Message format (Server -> Client):
     }
 
 
+## Internal clients
+
+Internal clients can be used by third-party applications to perform tasks that
+a regular client can not be used. Examples are adding virtual sessions or
+sending media without a regular client connected. This is used for example by
+the SIP bridge to publish mixed phone audio and show "virtual" sessions for the
+individial phone calls.
+
+See above for details on how to connect as internal client. By default, internal
+clients have their "inCall" and the "publishing audio" flags set. Virtual
+sessions have their "inCall" and the "publishing phone" flags set.
+
+This can be changed by including the client feature flag `internal-incall`
+which will require the client to set the flags as necessary.
+
+
+### Add virtual session
+
+Message format (Client -> Server):
+
+    {
+      "type": "internal",
+      "internal": {
+        "type": "addsession",
+        "addsession": {
+          "sessionid": "the-virtual-sessionid",
+          "roomid": "the-room-id-to-add-the-session",
+          "userid": "optional-user-id",
+          "user": {
+            ...additional data of the user...
+          },
+          "flags": "optional-initial-flags",
+          "incall": "optional-initial-incall",
+          "options": {
+            "actorId": "optional-actor-id",
+            "actorType": "optional-actor-type",
+          }
+        }
+      }
+    }
+
+
+### Update virtual session
+
+Message format (Client -> Server):
+
+    {
+      "type": "internal",
+      "internal": {
+        "type": "updatesession",
+        "updatesession": {
+          "sessionid": "the-virtual-sessionid",
+          "roomid": "the-room-id-to-update-the-session",
+          "flags": "optional-updated-flags",
+          "incall": "optional-updated-incall"
+        }
+      }
+    }
+
+
+### Remove virtual session
+
+Message format (Client -> Server):
+
+    {
+      "type": "internal",
+      "internal": {
+        "type": "removesession",
+        "removesession": {
+          "sessionid": "the-virtual-sessionid",
+          "roomid": "the-room-id-to-add-the-session",
+          "userid": "optional-user-id"
+        }
+      }
+    }
+
+
+### Change inCall flags of internal client
+
+Message format (Client -> Server):
+
+    {
+      "type": "internal",
+      "internal": {
+        "type": "incall",
+        "incall": {
+          "incall": "the-incall-flags"
+        }
+      }
+    }
+
+
 # Internal signaling server API
 
 The signaling server provides an internal API that can be called from Nextcloud