# Matrix

> Post to and manage Matrix rooms on any homeserver: send and read messages, create and join rooms, set topics, and invite and remove people. Start a workflow when a message is posted in a room.

App · 11 actions. Web page: https://docs.lodol.com/docs/integrations/matrix

## Actions

### Create room

Create a room without encryption and invite people to it.

**Inputs**

- Name (`name`, text, required): The room's name, such as Ops alerts.
- Topic (`topic`, text): What the room is for.
- Who can join (`access`, text): Only people invited, or anyone with the address. Defaults to only people invited. One of: `private` (Private (invite only)), `public` (Public (anyone can join)). Default: `private`.
- Address (`address`, text): A short name for its address, such as ops-alerts for #ops-alerts:matrix.org.
- Invite (`invite`, list): Matrix IDs of people to invite, such as @sam:matrix.org.

**Outputs**

- `address` (text): Its address, such as #team:matrix.org; empty if none
- `encrypted` (true/false): True when it is end-to-end encrypted
- `name` (text): Its name
- `room_id` (text): The room's ID
- `topic` (text): Its topic

**Example output**

```json
{
  "address": "#ops-alerts:matrix.org",
  "encrypted": false,
  "name": "Ops alerts",
  "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org",
  "topic": "Alerts from our workflows"
}
```

### Delete message

Remove a message from a room, wiping its words for everyone.

**Inputs**

- Room (`room`, text, required): The room. Pick one, or give its ID (!abc:matrix.org) or address (#name:matrix.org).
- Message (`event_id`, text, required): The message's event ID, starting with $, from 'Send message' or 'Get messages'.
- Reason (`reason`, text): Why it was removed, shown in its place.

**Outputs**

- `deleted` (true/false): True once removed
- `event_id` (text): The removed message's event ID
- `redaction_id` (text): The ID of the removal itself
- `room_id` (text): The room

**Example output**

```json
{
  "deleted": true,
  "event_id": "$9fGh2sKpQwErTyUi0oPlKjHgFdSaZxCv",
  "redaction_id": "$Qw3rTy8uIoPaSdFgHjKlZxCvBnM",
  "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org"
}
```

### Get messages

Get a room's most recent messages, newest first.

**Inputs**

- Room (`room`, text, required): The room. Pick one, or give its ID (!abc:matrix.org) or address (#name:matrix.org).
- How many (`limit`, number): How many messages. Defaults to 20. From 1 to 100.

**Outputs**

- `count` (number): How many messages
- `messages` (list): The messages, newest first
- `room_id` (text): The room

**Example output**

```json
{
  "count": 1,
  "messages": [
    {
      "event_id": "$9fGh2sKpQwErTyUi0oPlKjHgFdSaZxCv",
      "kind": "text",
      "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org",
      "sender": "@sam:matrix.org",
      "sent_at_ms": 1793095200000,
      "text": "Deploy finished"
    }
  ],
  "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org"
}
```

### Invite to room

Invite someone to a room by their Matrix ID.

**Inputs**

- Room (`room`, text, required): The room. Pick one, or give its ID (!abc:matrix.org) or address (#name:matrix.org).
- Person (`user`, text, required): Their Matrix ID, such as @sam:matrix.org.

**Outputs**

- `invited` (true/false): True once invited
- `room_id` (text): The room
- `user` (text): Who was invited

**Example output**

```json
{
  "invited": true,
  "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org",
  "user": "@sam:matrix.org"
}
```

### Join room

Join a public room, or one the account was invited to.

**Inputs**

- Room (`room`, text, required): The room's address (#name:matrix.org) or ID (!abc:matrix.org).

**Outputs**

- `address` (text): Its address, such as #team:matrix.org; empty if none
- `encrypted` (true/false): True when it is end-to-end encrypted
- `name` (text): Its name
- `room_id` (text): The room's ID
- `topic` (text): Its topic

**Example output**

```json
{
  "address": "#ops-alerts:matrix.org",
  "encrypted": false,
  "name": "Ops alerts",
  "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org",
  "topic": "Alerts from our workflows"
}
```

### Leave room

Leave a room.

**Inputs**

- Room (`room`, text, required): The room. Pick one, or give its ID (!abc:matrix.org) or address (#name:matrix.org).

**Outputs**

- `left` (true/false): True once left
- `room_id` (text): The room left

**Example output**

```json
{
  "left": true,
  "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org"
}
```

### List members

List the people in a room.

**Inputs**

- Room (`room`, text, required): The room. Pick one, or give its ID (!abc:matrix.org) or address (#name:matrix.org).

**Outputs**

- `count` (number): How many members
- `members` (list): The people in it
- `room_id` (text): The room

**Example output**

```json
{
  "count": 1,
  "members": [
    {
      "display_name": "Sam",
      "user": "@sam:matrix.org"
    }
  ],
  "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org"
}
```

### List rooms

List the rooms the account is in, with their names and whether they're encrypted.

**Inputs**: None.

**Outputs**

- `count` (number): How many rooms
- `rooms` (list): The rooms, by name

**Example output**

```json
{
  "count": 1,
  "rooms": [
    {
      "address": "#ops-alerts:matrix.org",
      "encrypted": false,
      "name": "Ops alerts",
      "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org",
      "topic": "Alerts from our workflows"
    }
  ]
}
```

### Remove from room

Remove someone from a room. They can join again if invited.

**Inputs**

- Room (`room`, text, required): The room. Pick one, or give its ID (!abc:matrix.org) or address (#name:matrix.org).
- Person (`user`, text, required): The person to remove. Pick one, or give their Matrix ID.
- Reason (`reason`, text): Why, shown to them and the room.

**Outputs**

- `removed` (true/false): True once removed
- `room_id` (text): The room
- `user` (text): Who was removed

**Example output**

```json
{
  "removed": true,
  "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org",
  "user": "@sam:matrix.org"
}
```

### Send message

Post a message to a room.

**Inputs**

- Room (`room`, text, required): The room. Pick one, or give its ID (!abc:matrix.org) or address (#name:matrix.org).
- Message (`message`, text, required): What to say. Markdown such as **bold** and [links](https://example.com) works.
- Send as (`send_as`, text): A message, or a notice, the kind bots send. Defaults to a message. One of: `text` (Message), `notice` (Notice (from a bot, no notification sound)). Default: `text`.
- Formatting (`formatting`, text): Read the message as Markdown or as plain text. Defaults to Markdown. One of: `markdown` (Markdown (bold, links, lists)), `plain` (Plain text). Default: `markdown`.

**Outputs**

- `event_id` (text): The message's event ID, for 'Delete message'
- `room_id` (text): The room it was sent to
- `sent` (true/false): True once sent

**Example output**

```json
{
  "event_id": "$9fGh2sKpQwErTyUi0oPlKjHgFdSaZxCv",
  "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org",
  "sent": true
}
```

### Set room topic

Change a room's topic, such as to show the current status.

**Inputs**

- Room (`room`, text, required): The room. Pick one, or give its ID (!abc:matrix.org) or address (#name:matrix.org).
- Topic (`topic`, text, required): The new topic.

**Outputs**

- `event_id` (text): The change's event ID
- `room_id` (text): The room
- `topic` (text): Its new topic

**Example output**

```json
{
  "event_id": "$Zx8cVbNmAsDfGhJkLqWeRtYuIo",
  "room_id": "!kBzNxRnXvLqHtYwPJa:matrix.org",
  "topic": "All systems normal"
}
```
