noordstar / elm-matrix-webhooks / Matrix.Webhooks

The MatrixWebhooks module connects to the Matrix-Webhook API.

Webhook

First, you'll set up a configuration to connect to a webhook.


type alias Webhook =
Internal.WebhookToken

Webhook that can be connected to.

toWebhook : String -> String -> String -> Webhook

You can configure access to the webhook using this function.

webhook : Webhook
webhook =
    toWebhook
        "https://example.com"
        "your-secret-api-key"
        "!abcdef:example.org"

Sending messages

sendMessage : (Result Error () -> msg) -> Webhook -> String -> Platform.Cmd.Cmd msg

Send a message to the webhook. The message supports Markdown.

sendMessage : Cmd msg
sendMessage toMsg webhook "hi mom!"

It is recommended to use this function to make a smaller one and focus on sending the messages.

send : String -> Cmd msg
send = sendMessage toMsg webhook

-- These all send a message to the Matrix-Webhook API
send "hi mom!"
send "I am a **big** adult now."
send "Are you proud of me? :)"

sendRaw : (Basics.Bool -> msg) -> String -> String -> String -> String -> Platform.Cmd.Cmd msg

The previous message is all nicely set up, but some people prefer a simple function where you can insert all your data right away. This function is relatively careless, allowing you to send message to the Webhook API and only getting a Bool in return that lets you know whether the message was sent successfully.

type Msg = Success Bool

sendRaw
    Success
    "https://example.com"
    "your-secret-api-key"
    "!abcdef:example.org"
    "hi mom!"
== sendMessage toMsg webhook "hi mom!"

Note: If the function returns False, there is no way of finding out why it went wrong.

Catching errors


type Error
    = BadUrl String
    | HomeserverReturnedError Basics.Int String
    | HomeserverTimeoutError
    | NetworkError
    | NotJoinedToRoom
    | Unauthorized
    | WebhookMissingInput
    | WebhookReturnedInvalidJSON
    | WebhookTimeoutError

Sometimes the webhook request fails, and you'd like to know why. The error type explains more about why a request may have failed: