Matrix: Send message

Posts a message to a Matrix room, as the account whose access token the credential holds.

• Kind: matrix.send_message
• Palette: Integrations, under Matrix
• Credential: a credential of kind bearer, named in credential

When to use

• Telling a team room that a run failed, a deploy finished or an approval is waiting.
• Any message where formatting helps. Written on the canvas, text gets a markdown editor, and the step stores the rendered HTML beside it as text_html, which posts formatted with the plain text as the fallback. A graph written as YAML sets text_html itself, or posts plain text.

The send uses the step’s idempotency key as its Matrix transaction id, so a retried step shows one message in the room.

Connection (with)

Field	Required	Description
homeserver	yes	Base URL of your Matrix homeserver. For example: https://matrix.org.
room_id	yes	Internal room id the access token can post to. For example: !abc123:matrix.org.

Input (input)

Field	Type	Required	Description
text	string	yes	Message body. Write markdown; it renders in the room. Written in a markdown editor; the rendered HTML is stored beside it as <name>_html.

Settings

Beside with and input in the node’s config.

Field	Type	Required	Description
credential	string	yes	Name of the project credential the action authenticates with.
fail_on_error_status	boolean	no	Treat any 4xx/5xx as a failure. On by default: an action either did its job or did not. Default true.
optional_when_untrusted	boolean	no	Run without the credential when the run is untrusted (a fork pull request), instead of failing. The credential is still withheld.
retry_on	array	no	Status codes that fail the node instead of returning, so its retry: policy applies (e.g. [429, 503]).

Output

The HTTP response. The reply is under body: nodes.<id>.output.body.<field>.

Field	Type	Description
status	integer	The HTTP status code.
headers	object	The response headers.
body	object	The response body, parsed as JSON when it is JSON.
body.event_id	string	The id of the message in the room.

How it runs

• On an agent with the connector capability. The managed environments have one, so this needs no agent of your own.
• One PUT request to an address built from with.
• Any 4xx or 5xx fails the step, unless fail_on_error_status is false. retry: asks again after a 5xx, a 401, 408, 409, 423, 425 or 429, or a 4xx with Retry-After, and not after any other 4xx, which would get the same answer.

Example

version: hyperspool-graph/v1
nodes:
  - id: on_failure
    type: trigger
    config: { event: run.failed }
  - id: post
    type: matrix.send_message
    config:
      credential: matrix
      with:
        homeserver: https://matrix.example
        room_id: "!abc:example"
      input:
        text: { $template: "Run failed: {{ input.payload.error }}" }
edges:
  - { from: on_failure, to: post }

Create the credential once with spool credential set matrix --kind bearer, which prompts for the access token. A connector step can’t be a fan_out body; to post one message per item, put it in the graph a workflow body names.

See Connectors for credentials and versions, and the node reference for every other node.