A Matrix client for Crystal matrix matrix-library
0.11.0 Latest release released

caridina 🦐

A Matrix client library written in Crystal.

It is also a species of shrimp, one of them being named "crystal red". Crystal for the language, red for the Matrix's red pill.

a crystal red shrimp


  1. Add the dependency to your shard.yml:

        github: erdnaxeli/caridina
  2. Run shards install


The API documentation is available here.


Create a new connection object:

require "caridina"

conn =
  "my access token",

You can also login to get a new access token:

access_token = Caridina::Connection.login(
  "my secret password",


Now we can create a new channel, and tell the connection object to start syncing. The sync responses will be streamed in the channel.

matrix = Channel(Caridina::Responses::Sync).new

sync = matrix.receive

You have now a sync response.

If you don't want to go through the whole sync response by yourself (which is understandable), we provide you a Caridina::Syncer object.

require "caridina/syncer"

syncer =
syncer.on(Caridina::Events::Message) do |event|
  event =
  # TODO: actually do something


:warning: The syncer is a new feature still in development. It currently only supports events in the joined rooms timeline. To access to other events, you need to go through the sync response.

Read event

The events in the sync response are all Caridina::Events::Event objects. You need to restrict the type of an event object to access all its fields.

sync.rooms.try &.join.each do |room_id, room| do |event|
    case event
    when Caridina::Events::Member
      # someone's membership changed
    when Caridina::Events::PowerLevels
      # some authorization changed
    when Caridina::Events::Message
      # someone talked
      # unknown event

Sometimes the event's content can be polymorphic too. That is especially the case for message events. By using again a case clause to event.content you can restrict its type to access all its fields.

Send events

There is not a single method to send an event. Instead this library provides a set of methods that correspond to different actions you may want to do. You usually do not need to worry about crafting the event to send.

:warning: This part is in a early stage. Only a few methods are currently provided.

# join a room
# send a message
event_id = conn.send_message("!", "Hello, world!")
# edit a message
conn.edit_message("!", event_id, "Hello, world!")
# send a read receipt
conn.send_receipt("!", "$")
# Use the typing notification as a loader
conn.typing("!") do
  # Do some processing.
  # While we are in the block, a typing notification will be shown on the given
  # room.
  conn.send_message("!", "All done!")


Install the dependencies with shards install.

  • make test runs the tests
  • make lint runs the formater plus a linter


  1. Fork it (
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


  github: erdnaxeli/caridina
  version: ~> 0.11.0
License MIT
Crystal >=0.36.1, <2


Dependencies 0

Development Dependencies 1

  • ameba ~>1.3.0
    {'github' => 'crystal-ameba/ameba', 'version' => '~>1.3.0'}

Dependents 0

Last synced .
search fire star recently