diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md new file mode 100644 index 000000000..051d1aaf2 --- /dev/null +++ b/proposals/4157-future-widget-api.md @@ -0,0 +1,50 @@ +# Futures for the widget api + +With [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) a way to send Future events is introduced. Futures are events that are send **now** but will +be inserted into the dag (and distributed to all clients and federating servers) a time after **now** (based on timeout or delegation conditions). + +This is an extension to the client server api to expose Futures to widgets. +This can be useful for numerous widgets. It is required for widgets implementing MatrixRTC. +Futures are needed for reliable MatrixRTC memberships that get cleaned up when a client looses network connection. + +Since ElementCall (EC) is a widget and based on MatrixRTC this widget api proposel is required for EC to work. + +## Proposal + +We extend the send +`"send_event"` request: + +``` +{ + state_key?: string; + type: string; + content: unknown; + room_id?: string; + + timeout?: number; + group_id?: string; +} +``` + +and the `"send_event"` response: + +``` +{ + room_id: string; + event_id: string; + + group_id: string; + send_token: string; + cancel_token: string; + refresh_token: string; +} +``` + +to provide the same properties needed for [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140). The client is responsible to check +for the field `timeout` or `group_id` of the widget action and send a `/send` or `/send_future` http request +if one of them is present. + +Additionally the response is extended with the tokens and the group_id. + +All other details about the future concept can be found in [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) so here we intentionally don't mention +any of the details about futures.