Instant Messaging

This module adds support for sending human-readable messages to a room. It also adds support for associating human-readable information with the room itself such as a room name and topic.

You can always refer to the matrix documentation: https://matrix.org/docs/spec/client_server/latest#id43

Send Event to room

POST https://{{tekos_homeserver}}/_matrix/client/r0/rooms/{roomId}/send/{{eventType}}

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 the 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.

Path Parameters

Name	Type	Description
eventType	string	The type of event to send.
roomId	string	The room to send the event to.
tekos_homeserver	string	Your home server address, the default one is m.tekos.co, but we suggest to use env.get('BASE_URL') this variable should contain address to your home server stored on our S3 server.

Query Parameters

Name	Type	Description
access_token	string	Access Token of the user or bot that will send a message.

Request Body

Name	Type	Description
msg.payload	object	See the Events avalible for the body.

200 An ID for the sent event.

{
  "event_id": "$YUwRidLecu:example.com"
}

Events

m.room.message

Message Event

This event is used when sending messages in a room. Messages are not limited to be text. The msgtype key outlines the type of message, e.g. text, audio, image, video, etc. The body key is text and MUST be used with every kind of msgtype as a fallback mechanism for when a client cannot render a message. This allows clients to display something even if it is just plain text. For more information on msgtypes, see m.room.message msgtypes.

Content Key	Type	Description
body	string	Required. The textual representation of this message.
msgtype	string	Required. The type of message, e.g. m.image, m.text

Examples:

{
    "content": {
        "body": "Bee Gees - Stayin' Alive",
        "info": {
            "duration": 2140786,
            "mimetype": "audio/mpeg",
            "size": 1563685
        },
        "msgtype": "m.audio",
        "url": "mxc://example.org/ffed755USFFxlgbQYZGtryd"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

{
    "content": {
        "body": "thinks this is an example emote",
        "format": "org.matrix.custom.html",
        "formatted_body": "thinks <b>this</b> is an example emote",
        "msgtype": "m.emote"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

{
    "content": {
        "body": "something-important.doc",
        "filename": "something-important.doc",
        "info": {
            "mimetype": "application/msword",
            "size": 46144
        },
        "msgtype": "m.file",
        "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

{
    "content": {
        "body": "filename.jpg",
        "info": {
            "h": 398,
            "mimetype": "image/jpeg",
            "size": 31037,
            "w": 394
        },
        "msgtype": "m.image",
        "url": "mxc://example.org/JWEIFJgwEIhweiWJE"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

{
    "content": {
        "body": "Big Ben, London, UK",
        "geo_uri": "geo:51.5008,0.1247",
        "info": {
            "thumbnail_info": {
                "h": 300,
                "mimetype": "image/jpeg",
                "size": 46144,
                "w": 300
            },
            "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
        },
        "msgtype": "m.location"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

{
    "content": {
        "body": "This is an example notice",
        "format": "org.matrix.custom.html",
        "formatted_body": "This is an <strong>example</strong> notice",
        "msgtype": "m.notice"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

{
    "content": {
        "admin_contact": "mailto:[e-mail]",
        "body": "Human-readable message to explain the notice",
        "limit_type": "monthly_active_user",
        "msgtype": "m.server_notice",
        "server_notice_type": "m.server_notice.usage_limit_reached"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

{
    "content": {
        "body": "This is an example text message",
        "format": "org.matrix.custom.html",
        "formatted_body": "<b>This is an example text message</b>",
        "msgtype": "m.text"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

{
    "content": {
        "body": "Gangnam Style",
        "info": {
            "duration": 2140786,
            "h": 320,
            "mimetype": "video/mp4",
            "size": 1563685,
            "thumbnail_info": {
                "h": 300,
                "mimetype": "image/jpeg",
                "size": 46144,
                "w": 300
            },
            "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
            "w": 480
        },
        "msgtype": "m.video",
        "url": "mxc://example.org/a526eYUSFFxlgbQYZmo442"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

m.room.message.feedback

Message Event

NB: Usage of this event is discouraged in favour of the receipts module. Most clients will not recognise this event. Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: delivered (sent when the event has been received) and read (sent when the event has been observed by the end-user). The target_event_id should reference the m.room.message event being acknowledged.

Content Key	Type	Description
target_event_id	string	Required. The event that this feedback is related to.
type	enum	Required. The type of feedback. One of: ["delivered", "read"]

Example:

{
    "content": {
        "target_event_id": "$WEIGFHFW:localhost",
        "type": "delivered"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message.feedback",
    "unsigned": {
        "age": 1234
    }
}

Usage of this event is discouraged for several reasons:

• The number of feedback events will grow very quickly with the number of users in the room. This event provides no way to "batch" feedback, unlike the receipts module.

• Pairing feedback to messages gets complicated when paginating as feedback arrives before the message it is acknowledging.

• There are no guarantees that the client has seen the event ID being acknowledged.

m.room.name

State Eventstate_key: A zero-length string.

A room has an opaque room ID which is not human-friendly to read. A room alias is human-friendly, but not all rooms have room aliases. The room name is a human-friendly string designed to be displayed to the end-user. The room name is not unique, as multiple rooms can have the same room name set.

A room with an m.room.name event with an absent, null, or empty name field should be treated the same as a room with no m.room.name event.

An event of this type is automatically created when creating a room using /createRoom with the name key.

Content Key	Type	Description
name	string	Required. The name of the room. This MUST NOT exceed 255 bytes.

Example:

{
    "content": {
        "name": "The room name"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "state_key": "",
    "type": "m.room.name",
    "unsigned": {
        "age": 1234
    }
}

m.room.topic

State Eventstate_key: A zero-length string.

A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using /createRoom with the topic key.

Content Key	Type	Description
topic	string	Required. The topic text.

Example:

{
    "content": {
        "topic": "A room topic"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "state_key": "",
    "type": "m.room.topic",
    "unsigned": {
        "age": 1234
    }
}

m.room.avatar

State Eventstate_key: A zero-length string.

A picture that is associated with the room. This can be displayed alongside the room information.

Content Key	Type	Description
info	ImageInfo	Metadata about the image referred to in url.
url	string	Required. The URL to the image.

ImageInfo
ImageInfo Key	Type	Description
h	integer	The intended display height of the image in pixels. This may differ from the intrinsic dimensions of the image file.
w	integer	The intended display width of the image in pixels. This may differ from the intrinsic dimensions of the image file.
mimetype	string	The mimetype of the image, e.g. image/jpeg.
size	integer	Size of the image in bytes.
thumbnail_url	string	The URL (typically MXC URI) to a thumbnail of the image. Only present if the thumbnail is unencrypted.
thumbnail_file	EncryptedFile	Information on the encrypted thumbnail file, as specified in End-to-end encryption. Only present if the thumbnail is encrypted.
thumbnail_info	ThumbnailInfo	Metadata about the image referred to in thumbnail_url.

ThumbnailInfo
ThumbnailInfo Key	Type	Description
h	integer	The intended display height of the image in pixels. This may differ from the intrinsic dimensions of the image file.
w	integer	The intended display width of the image in pixels. This may differ from the intrinsic dimensions of the image file.
mimetype	string	The mimetype of the image, e.g. image/jpeg.
size	integer	Size of the image in bytes.

Example:

{
    "content": {
        "info": {
            "h": 398,
            "mimetype": "image/jpeg",
            "size": 31037,
            "w": 394
        },
        "url": "mxc://example.org/JWEIFJgwEIhweiWJE"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "state_key": "",
    "type": "m.room.avatar",
    "unsigned": {
        "age": 1234
    }
}

m.room.pinned_events

State Eventstate_key: A zero-length string.

This event is used to "pin" particular events in a room for other participants to review later. The order of the pinned events is guaranteed and based upon the order supplied in the event. Clients should be aware that the current user may not be able to see some of the events pinned due to visibility settings in the room. Clients are responsible for determining if a particular event in the pinned list is displayable, and have the option to not display it if it cannot be pinned in the client.

Content Key	Type	Description
pinned	[string]	Required. An ordered list of event IDs to pin.

Example:

{
    "content": {
        "pinned": [
            "$someevent:example.org"
        ]
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "state_key": "",
    "type": "m.room.pinned_events",
    "unsigned": {
        "age": 1234
    }
}