From fdb4d74dd63eb94a0a0e59267daf5f515cf27248 Mon Sep 17 00:00:00 2001
From: Joachim Bauch <bauch@struktur.de>
Date: Tue, 24 Oct 2023 11:26:58 +0200
Subject: [PATCH] Add note on control messages and phone sessions.

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

diff --git a/docs/standalone-signaling-api-v1.md b/docs/standalone-signaling-api-v1.md
index 72210c0..d05ae68 100644
--- a/docs/standalone-signaling-api-v1.md
+++ b/docs/standalone-signaling-api-v1.md
@@ -793,6 +793,74 @@ Message format (Server -> Client, receive message)
 - The `userid` is omitted if a message was sent by an anonymous user.
 
 
+## Control messages
+
+Similar to regular messages between clients which can be sent by any session,
+messages with type `control` can only be sent if the permission flag `control`
+is available.
+
+These messages can be used to perform actions on clients that should only be
+possible by some users (e.g. moderators).
+
+Message format (Client -> Server, mute phone):
+
+    {
+      "id": "unique-request-id",
+      "type": "control",
+      "control": {
+        "recipient": {
+          "type": "session",
+          "sessionid": "the-session-id-to-send-to"
+        },
+        "data": {
+          "type": "mute",
+          "audio": "audio-flags"
+        }
+      }
+    }
+
+The bit-field `audio-flags` supports the following bits:
+- `1`: mute speaking (i.e. phone can no longer talk)
+- `2`: mute listening (i.e. phone is on hold and can no longer hear)
+
+To unmute, a value of `0` must be sent.
+
+Message format (Client -> Server, hangup phone):
+
+    {
+      "id": "unique-request-id",
+      "type": "control",
+      "control": {
+        "recipient": {
+          "type": "session",
+          "sessionid": "the-session-id-to-send-to"
+        },
+        "data": {
+          "type": "hangup"
+        }
+      }
+    }
+
+Message format (Client -> Server, send DTMF):
+
+    {
+      "id": "unique-request-id",
+      "type": "control",
+      "control": {
+        "recipient": {
+          "type": "session",
+          "sessionid": "the-session-id-to-send-to"
+        },
+        "data": {
+          "type": "dtmf",
+          "digit": "the-digit"
+        }
+      }
+    }
+
+Supported digits are `0`-`9`, `*` and `#`.
+
+
 ## Transient data
 
 Transient data can be used to share data in a room that is valid while sessions
@@ -936,6 +1004,13 @@ Message format (Client -> Server):
     }
 
 
+Phone sessions will have `type` set to `phone` in the additional user data
+(which will be included in the `joined` [room event](#room-events)),
+`callid` will be the id of the phone call and `number` the target of the call.
+The call id will match the one returned for accepted outgoing calls and the
+associated session id can be used to hangup a call or send DTMF tones to it.
+
+
 ### Update virtual session
 
 Message format (Client -> Server):