matrix-spec/data/event-schemas/schema/m.call.negotiate.yaml

---
type: object
description: |
  Provides SDP negotiation semantics for media pause, hold/resume, ICE restarts
  and voice/video call up/downgrading. Clients should implement and honour hold
  functionality as per [WebRTC's recommendation](https://www.w3.org/TR/webrtc/#hold-functionality).

  If both the invite event and the accepted answer event have `version` equal
  to `"1"`, either party may send `m.call.negotiate` with a `description` field
  to offer new SDP to the other party. This event has `call_id` with the ID of
  the call and `party_id` equal to the client's party ID for that call.  The
  caller ignores any negotiate events with `party_id` + `user_id` tuple not
  equal to that of the answer it accepted and the callee ignores any negotiate
  events with `party_id` + `user_id` tuple not equal to that of the caller.
  Clients should use the `party_id` field to ignore the remote echo of their
  own negotiate events.

  This has a `lifetime` field as in `m.call.invite`, after which the sender of
  the negotiate event should consider the negotiation failed (timed out) and
  the recipient should ignore it.

  The `description` field is the same as the `offer` field in `m.call.invite`
  and `answer` field in `m.call.answer` and is an `RTCSessionDescriptionInit`
  object as per https://www.w3.org/TR/webrtc/#dom-rtcsessiondescriptioninit.

  Once an `m.call.negotiate` event is received, the client must respond with
  another `m.call.negotiate` event, with the SDP answer (with `"type": "answer"`)
  in the `description` property.

  In the `m.call.invite` and `m.call.answer` events, the `offer` and `answer`
  fields respectively are objects of type `RTCSessionDescriptionInit`.  Hence
  the `type` field, whilst redundant in these events, is included for ease of
  working with the WebRTC API and is mandatory. Receiving clients should not
  attempt to validate the `type` field, but simply pass the object into the
  WebRTC API.
x-addedInMatrixVersion: "1.7"
x-weight: 60
allOf:
- "$ref": core-event-schema/room_event.yaml
properties:
  content:
    type: object
    allOf:
    - "$ref": core-event-schema/call_event.yaml
    properties:
      description:
        type: object
        title: Description
        description: The session description object
        properties:
          type:
            type: string
            enum:
            - offer
            - answer
            description: The type of session description.
          sdp:
            type: string
            description: The SDP text of the session description.
        required:
        - type
        - sdp
      lifetime:
        type: integer
        description: The time in milliseconds that the negotiation is valid for.
          Once the negotiation age exceeds this value, clients should discard it.
      sdp_stream_metadata:
        $ref: components/sdp_stream_metadata.yaml
    required:
    - description
    - lifetime
  type:
    type: string
    enum:
    - m.call.negotiate