Add party_id

content/client-server-api/modules/voip_events.md

@@ -21,6 +21,26 @@ backwards-compatible.  If it does become necessary to introduce a non
 backwards-compatible VoIP spec, the intention would be for it to simply use a
 separate set of event types.
 
+#### Party Identifiers
+Whenever a client first participates in a new call, it generates a `party_id` for itself to use for the
+duration of the call. This needs to be long enough that the chance of a collision between multiple devices
+both generating an answer at the same time generating the same party ID is vanishingly small: 8 uppercase +
+lowercase alphanumeric characters is recommended. Parties in the call are identified by the tuple of
+`(user_id, party_id)`.
+
+The client  adds a `party_id` field containing this ID to the top-level of the content of all VoIP events
+it sends on the call, including `m.call.invite`. Clients use this to identify remote echo of their own
+events: since a user may now call themselves, they can no longer ignore events from their own user. This
+field also identifies different answers sent by different clients to an invite, and matches `m.call.candidates`
+events to their respective answer/invite.
+
+A client implementation may choose to use the device ID used in end-to-end cryptography for this purpose,
+or it may choose, for example, to use a different one for each call to avoid leaking information on which
+devices were used in a call (in an unencrypted room) or if a single device (ie. access token) were used to
+send signalling for more than one call party.
+
+A grammar for `party_id` is defined [below](#specify-exact-grammar-for-voip-ids).
+
 #### Events
 
 {{% event-group group_name="m.call" %}}

data/event-schemas/schema/m.call.answer.yaml

@@ -32,6 +32,9 @@
                 "version": {
                     "type": "number",
                     "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0"
+                },
+                "party_id": {
+                    "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. "
                 }
             },
             "required": ["call_id", "answer", "version"]

data/event-schemas/schema/m.call.candidates.yaml

@@ -35,6 +35,9 @@
                         "required": ["candidate", "sdpMLineIndex", "sdpMid"]
                     }
                 },
+                "party_id": {
+                    "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. "
+                },
                 "version": {
                     "type": "integer",
                     "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0."

data/event-schemas/schema/m.call.hangup.yaml

@@ -16,6 +16,9 @@
                     "type": "integer",
                     "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0."
                 },
+                "party_id": {
+                    "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. "
+                },
                 "reason": {
                     "type": "string",
                     "description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call. When there was an error in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or `invite_timeout` for when the other party did not answer in time.",

data/event-schemas/schema/m.call.invite.yaml

@@ -33,6 +33,9 @@
                     "type": "string",
                     "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0."
                 },
+                "party_id": {
+                    "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. "
+                },
                 "lifetime": {
                     "type": "integer",
                     "description": "The time in milliseconds that the invite is valid for. Once the invite age exceeds this value, clients should discard it. They should also no longer show the call as awaiting an answer in the UI."
@@ -42,7 +45,7 @@
                     "description": "The ID of the user being called.",
                 }
             },
-            "required": ["call_id", "offer", "version", "lifetime"]
+            "required": ["call_id", "offer", "version", "lifetime", "party_id"]
         },
         "type": {
             "type": "string",