Skip to main content

Setting up Hookshot without E2EE support in encrypted rooms

If your Hookshot instance does not have E2EE support enabled but you still want to add it to an encrypted room, you can do this with a couple of caveats:

  • You cannot send commands to Hookshot in the room as Hookshot cannot read any messages in the room
  • Any messages sent by Hookshot will be unencrypted

To set this up:

  • Invite your Hookshot bot to the room, this works the same as with unencrypted rooms. The bot follows the same permissions in encrypted vs. unencrypted rooms and will join when invited.
  • Promote the Hookshot bot to the required room permissions. By default, Moderator.
  • If your Hookshot is configured to automatically add the widget on invite, no further configuration is required.
  • If not, you need to manually send the setup-widget command unencrypted. By design, it is impossible to send an unencrypted message into an encrypted room using Element. So to do it:
    • Grab your account access token from Element settings -> Help & About -> Advanced -> Access Token

      Your access token grants full access to your Matrix account, threat it carefully like you would with a password

    • Grab the room ID for the room you wish to add Hookshot to by clicking the (i) Room Info button, then Settings in the right column
    • Under Advanced, copy the Internal room ID
    • Replace the leading ! (exclamation mark) with %21 (for example, !QrmxBsBKPajykCohPz:localhost:8448 becomes %21QrmxBsBKPajykCohPz:localhost:8448)
    • Find the URL where your Matrix server is exposed. This may not be the same as the domain in your Matrix ID
    • Open a terminal on your computer. On Windows; PowerShell, on Mac; Terminal
    • Send the command below for your operating system. Replace domain-where-your-matrix-server-is-exposed, room-id and access-toke with the values from earlier. Note, if you are sending more than one message using your terminal, you need to change 1234 to another value each time.
      • Mac and Linux: 
        curl --request PUT \
  --url 'https://domain-where-your-matrix-server-is-exposed/_matrix/client/r0/rooms/room-id/send/m.room.message/1234' \
  --header 'Authorization: Bearer access-token' \
  --header 'content-type: application/json' \
  --data '{
	"msgtype":"m.text",
	"body":"!hookshot setup-widget"
}'
        For example: 
        curl --request PUT \
  --url 'https://localhost:8448/_matrix/client/r0/rooms/%21QrmxBsBKPajykCohPz:localhost:8448/send/m.room.message/1234' \
  --header 'Authorization: Bearer syt_YWRtaW4_epoEMAUauwwFpsOGJxIg_471LjM' \
  --header 'content-type: application/json' \
  --data '{
	"msgtype":"m.text",
	"body":"!hookshot setup-widget"
}'
      • Windows: 
        $url = "https://domain-where-your-matrix-server-is-exposed/_matrix/client/r0/rooms/room-id/send/m.room.message/1234"

$headers = @{
    "Authorization" = "Bearer access-token"
    "Content-Type" = "application/json"
}

$body = @{
    msgtype = "m.text"
    body = "!hookshot setup-widget"
} | ConvertTo-Json

Invoke-RestMethod -Uri $url -Method Put -Headers $headers -Body $body
        For example: 
        $url = "https://localhost:8448/_matrix/client/r0/rooms/%21QrmxBsBKPajykCohPz:localhost:8448/send/m.room.message/1234"

$headers = @{
    "Authorization" = "Bearer syt_YWRtaW4_epoEMAUauwwFpsOGJxIg_471LjM"
    "Content-Type" = "application/json"
}

$body = @{
    msgtype = "m.text"
    body = "!hookshot setup-widget"
} | ConvertTo-Json

Invoke-RestMethod -Uri $url -Method Put -Headers $headers -Body $body

My message was sent without encryption and Hookshot responded. You can now use Hookshot via the widget normally.

Note that all messages sent by Hookshot remain unencrypted. Element warns you with the red shield on the messages.

Back to top