diff --git a/api/client-server/v1/room_send.yaml b/api/client-server/v1/room_send.yaml new file mode 100644 index 00000000..9c9273df --- /dev/null +++ b/api/client-server/v1/room_send.yaml @@ -0,0 +1,125 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server v1 message event send API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/api/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + accessToken: + type: apiKey + description: The user_id or application service access_token + name: access_token + in: query +paths: + "/rooms/{roomId}/send/{eventType}/{txnId}": + put: + summary: Send a message event to the given room. + description: |- + This endpoint is used to send a message event to a room. Message events + allow access to historical events and pagination, making them suited + for "once-off" activity in a room. + + The body of the request should be the content object of the event; the + fields in this object will vary depending on the type of event. See + `Room Events`_ for the m. event specification. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room to send the event to. + required: true + x-example: "!636q39766251:example.com" + - in: path + type: string + name: eventType + description: The type of event to send. + required: true + x-example: "m.room.message" + - in: path + name: txnId + type: string + description: |- + The transaction ID for this event. Clients should generate a + unique ID; it will be used by the server to ensure idempotency of requests. + required: true + x-example: "35" + - in: body + name: body + schema: + type: object + example: |- + { + "msgtype": "m.text", + "body": "hello" + } + responses: + 200: + description: "An ID for the sent event." + examples: + application/json: |- + { + "event_id": "YUwRidLecu" + } + schema: + type: object + properties: + event_id: + type: string + description: |- + A unique identifier for the event. + "/rooms/{roomId}/send/{eventType}": + post: + summary: Send a message event to the given room. + description: |- + This endpoint can be used to send a message event to a room; however + the lack of a transaction ID means that it is possible to cause message + duplication if events are resent on error, so it is preferable to use + `PUT /_matrix/client/api/v1/rooms/{roomId}/send/{eventType}/{txnId}`_. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room to send the event to. + required: true + x-example: "!636q39766251:example.com" + - in: path + type: string + name: eventType + description: The type of event to send. + required: true + x-example: "m.room.message" + - in: body + name: body + schema: + type: object + example: |- + { + "msgtype": "m.text", + "body": "hello" + } + responses: + 200: + description: "An ID for the sent event." + examples: + application/json: |- + { + "event_id": "YUwRidLecu" + } + schema: + type: object + properties: + event_id: + type: string + description: |- + A unique identifier for the event. diff --git a/api/client-server/v1/room_state.yaml b/api/client-server/v1/room_state.yaml new file mode 100644 index 00000000..ec30fd34 --- /dev/null +++ b/api/client-server/v1/room_state.yaml @@ -0,0 +1,80 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server v1 state event send API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/api/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + accessToken: + type: apiKey + description: The user_id or application service access_token + name: access_token + in: query +paths: + "/rooms/{roomId}/state/{eventType}/{stateKey}": + put: + summary: Send a message event to the given room. + description: | + State events can be sent using this endpoint. These events will be + overwritten if ````, ```` and ```` all + match. If the state event has an empty ``state_key``, it can be + omitted from the path. + + Requests to this endpoint **cannot use transaction IDs** + like other ``PUT`` paths because they cannot be differentiated from the + ``state_key``. Furthermore, ``POST`` is unsupported on state paths. + + The body of the request should be the content object of the event; the + fields in this object will vary depending on the type of event. See + `Room Events`_ for the ``m.`` event specification. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room to set the state in + required: true + x-example: "!636q39766251:example.com" + - in: path + type: string + name: eventType + description: The type of event to send. + required: true + x-example: "m.room.name" + - in: path + type: string + name: stateKey + description: The state_key for the state to send. Defaults to the empty string. + required: true + x-example: "" + - in: body + name: body + schema: + type: object + example: |- + { + "name": "New name for the room" + } + responses: + 200: + description: "An ID for the sent event." + examples: + application/json: |- + { + "event_id": "YUwRidLecu" + } + schema: + type: object + properties: + event_id: + type: string + description: |- + A unique identifier for the event. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 43c1ee0b..9e230334 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -595,6 +595,30 @@ To continue paginating backwards, one calls the /messages API again, supplying the new ``start`` value as the ``from`` parameter. +Types of room events +~~~~~~~~~~~~~~~~~~~~ + +Room events are split into two categories: + +:State Events: + These are events which update the metadata state of the room (e.g. room topic, + room membership etc). State is keyed by a tuple of event ``type`` and a + ``state_key``. State in the room with the same key-tuple will be overwritten. + +:Message events: + These are events which describe transient "once-off" activity in a room: + typically communication such as sending an instant message or setting up a + VoIP call. + +This specification outlines several events, all with the event type prefix +``m.``. (See `Room Events`_ for the m. event specification.) However, +applications may wish to add their own type of event, and this can be achieved +using the REST API detailed in the following sections. If new events are added, +the event ``type`` key SHOULD follow the Java package naming convention, +e.g. ``com.example.myapp.event``. This ensures event types are suitably +namespaced for each application and reduces the risk of clashes. + + Syncing ~~~~~~~ @@ -623,44 +647,33 @@ This API also returns an ``end`` token which can be used with the event stream. {{sync_http_api}} -Types of room events -~~~~~~~~~~~~~~~~~~~~ -Room events are split into two categories: +Getting events for a room +~~~~~~~~~~~~~~~~~~~~~~~~~ -:State Events: - These are events which update the metadata state of the room (e.g. room topic, - room membership etc). State is keyed by a tuple of event ``type`` and a - ``state_key``. State in the room with the same key-tuple will be overwritten. +There are several APIs provided to ``GET`` events for a room: -:Message events: - These are events which describe transient "once-off" activity in a room: - typically communication such as sending an instant message or setting up a - VoIP call. +{{rooms_http_api}} -This specification outlines several events, all with the event type prefix -``m.``. However, applications may wish to add their own type of event, and this -can be achieved using the REST API detailed in the following sections. If new -events are added, the event ``type`` key SHOULD follow the Java package naming -convention, e.g. ``com.example.myapp.event``. This ensures event types are -suitably namespaced for each application and reduces the risk of clashes. -State events -++++++++++++ +{{message_pagination_http_api}} + -State events can be sent by ``PUT`` ing to -|/rooms//state//|_. These events will be -overwritten if ````, ```` and ```` all match. -If the state event has no ``state_key``, it can be omitted from the path. These -requests **cannot use transaction IDs** like other ``PUT`` paths because they -cannot be differentiated from the ``state_key``. Furthermore, ``POST`` is -unsupported on state paths. Valid requests look like:: +Sending events to a room +~~~~~~~~~~~~~~~~~~~~~~~~ - PUT /rooms/!roomid:domain/state/m.example.event - { "key" : "without a state key" } +{{room_state_http_api}} - PUT /rooms/!roomid:domain/state/m.another.example.event/foo - { "key" : "with 'foo' as the state key" } + +**Examples** + +Valid requests look like:: + + PUT /rooms/!roomid:domain/state/m.example.event + { "key" : "without a state key" } + + PUT /rooms/!roomid:domain/state/m.another.example.event/foo + { "key" : "with 'foo' as the state key" } In contrast, these requests are invalid:: @@ -686,34 +699,8 @@ In some cases, there may be no need for a ``state_key``, so it can be omitted:: PUT /rooms/!roomid:domain/state/m.room.bgd.color { "color": "red", "hex": "#ff0000" } -See `Room Events`_ for the ``m.`` event specification. - -Message events -++++++++++++++ - -Message events can be sent by sending a request to -|/rooms//send/|_. These requests *can* use transaction -IDs and ``PUT``/``POST`` methods. Message events allow access to historical -events and pagination, making it best suited for sending messages. For -example:: +{{room_send_http_api}} - POST /rooms/!roomid:domain/send/m.custom.example.message - { "text": "Hello world!" } - - PUT /rooms/!roomid:domain/send/m.custom.example.message/11 - { "text": "Goodbye world!" } - -See `Room Events`_ for the ``m.`` event specification. - -Getting events for a room -~~~~~~~~~~~~~~~~~~~~~~~~~ - -There are several APIs provided to ``GET`` events for a room: - -{{rooms_http_api}} - - -{{message_pagination_http_api}} Redactions ~~~~~~~~~~ @@ -1007,12 +994,6 @@ have to wait in milliseconds before they can try again. .. |/rooms//state| replace:: ``/rooms//state`` .. _/rooms//state: /docs/api/client-server/#!/-rooms/get_state_events -.. |/rooms//send/| replace:: ``/rooms//send/`` -.. _/rooms//send/: /docs/api/client-server/#!/-rooms/send_non_state_event - -.. |/rooms//state//| replace:: ``/rooms//state//`` -.. _/rooms//state//: /docs/api/client-server/#!/-rooms/send_state_event - .. |/rooms//invite| replace:: ``/rooms//invite`` .. _/rooms//invite: /docs/api/client-server/#!/-rooms/invite