diff --git a/api/widgets/definitions/shared_props.yaml b/api/widgets/definitions/shared_props.yaml
index aec0ae571b2..753789b9d64 100644
--- a/api/widgets/definitions/shared_props.yaml
+++ b/api/widgets/definitions/shared_props.yaml
@@ -54,6 +54,15 @@ properties:
       from view until the ``content_loaded`` API action is sent by the widget. Defaults to
       true.
     example: true
+  avatar_url:
+    type: string
+    description: |-
+      An optional MXC URI to an image which can be used to identify the widget. Recommended
+      for use alongside the ``name`` and ``data.title``.
+
+      Images SHOULD be legible at small sizes, such as 20x20 pixels. The MXC URI here should
+      be the source material to allow clients to use the ``/thumbnail`` endpoint on the media.
+    example: "mxc://example.org/aaabbbccc"
   data:
     type: object
     title: WidgetData
diff --git a/api/widgets/examples/shared_props.json b/api/widgets/examples/shared_props.json
index ce848b3bc23..d384cc8830f 100644
--- a/api/widgets/examples/shared_props.json
+++ b/api/widgets/examples/shared_props.json
@@ -8,5 +8,6 @@
     "name": "My Cool Widget",
     "type": "m.custom",
     "url": "https://example.org/my/widget.html?roomId=$matrix_room_id",
-    "waitForIframeLoad": true
+    "waitForIframeLoad": true,
+    "avatar_url": "mxc://example.org/aaabbbccc"
 }