---
allOf:
  - $ref: core-event-schema/event.yaml

description: |-
  This event type is used to indicate that the sender is not sharing room keys
  with the recipient. It is sent as a to-device event.

  Possible values for ``code`` include:

  * ``m.blacklisted``: the user/device was blacklisted.
  * ``m.unverified``: the user/device was not verified, and the sender is only
    sharing keys with verified users/devices.
  * ``m.unauthorised``: the user/device is not allowed to have the key. For
    example, this could be sent in response to a key request if the user/device
    was not in the room when the original message was sent.
  * ``m.unavailable``: sent in reply to a key request if the device that the
    key is requested from does not have the requested key.
  * ``m.no_olm``: an olm session could not be established.

  In most cases, this event refers to a specific room key. The one exception to
  this is when the sender is unable to establish an olm session with the
  recipient. When this happens, multiple sessions will be affected.  In order
  to avoid filling the recipient\'s device mailbox, the sender should only send
  one ``m.room_key.withheld`` message with no ``room_id`` nor ``session_id``
  set.  If the sender retries and fails to create an olm session again in the
  future, it should not send another ``m.room_key.withheld`` message with a
  ``code`` of ``m.no_olm``, unless another olm session was previously
  established successfully.  In response to receiving an
  ``m.room_key.withheld`` message with a ``code`` of ``m.no_olm``, the
  recipient may start an olm session with the sender and send an ``m.dummy``
  message to notify the sender of the new olm session.  The recipient may
  assume that this ``m.room_key.withheld`` message applies to all encrypted
  room messages sent before it receives the message.
properties:
  content:
    properties:
      algorithm:
        type: string
        enum: ["m.megolm.v1.aes-sha2"]
        description: |-
          The encryption algorithm for the key that this event is about.
      room_id:
        type: string
        description: |-
          Required if ``code`` is not ``m.no_olm``.  The room for the key that
          this event is about.
      session_id:
        type: string
        description: |-
          Required of ``code`` is not ``m.no_olm``.  The session ID of the key
          that this event is aboutis for.
      sender_key:
        type: string
        description: |-
          The unpadded base64-encoded device curve25519 key of the event\'s
          sender.
      code:
        type: string
        enum:
          - m.blacklisted
          - m.unverified
          - m.unauthorised
          - m.unavailable
          - m.no_olm
        description: |-
          A machine-readable code for why the key was not sent. Codes beginning
          with `m.` are reserved for codes defined in the Matrix
          specification. Custom codes must use the Java package naming
          convention.
      reason:
        type: string
        description: |-
          A human-readable reason for why the key was not sent. The receiving
          client should only use this string if it does not understand the
          ``code``.
    required:
      - algorithm
      - sender_key
      - code
    type: object
  type:
    enum:
      - m.room_key.withheld
    type: string
type: object