rn-matrix

rn-matrix

  • Docs
  • Example
  • GitLab

›Core

Getting Started

  • Installation
  • Installation (UI)
  • Installation (Expo)

Guides

  • Encryption
  • Authentication Flow
  • Managing Messages

API

    Core

    • matrix
    • matrixSdk
    • Chat (Class)
    • Message (Class)

    UI

    • RoomList
    • MessageList

Exported "matrix" module

This exported variable contains **all data methods from rn-matrix.** Anything you want to do with data can probably be done with matrix.*

This variable differs from the exported matrixSdk in that matrixSdk is the original export from the matrix-js-sdk, so if rn-matrix limits you in any way, you can see if the matrix-js-sdk can solve your problem.

Methods

Core

createClient

createClient(baseUrl, accessToken, MXID, deviceId)

Creates a new instance of a Matrix Client.

PropTypeDescription
baseUrlstringThe URL of the homeserver the client should connect to.
accessTokenstringThe access token of the user you want to log in.
MXIDstringThe MXID (@john:matrix.org) of the user you want to log in.
deviceIdstring(Only required for encryption) The device ID returned from the call to login.
import {matrix} from 'rn-matrix';
...
const accessToken = 'asdf';
const deviceId = '1234';
matrix.createClient('https://matrix.ditto.chat', accessToken, '@test:ditto.chat', deviceId);

start

start(useCrypto)

Starts the client. Required early on in app start so that the client can begin listening for events.

PropTypeDescription
useCryptoboolean(Default false) Enables end to end encryption.

Must happen after creating the client.

import { matrix } from 'rn-matrix';
...
matrix.start();

Rooms

createRoom

createRoom(options)

Creates a room and returns its details

PropTypeDescriptionExample
optionsobject{
visibility: 'private' or 'public',
invite: array of userId strings,
name: string for name,
room_topic: string for topic
}
{
visibility: 'private',
invite: ['@annie:ditto.chat'],
name: 'New Room',
room_topic: ''
}

Returns

{
  id, // the id of the new room
    name; // the name you used, or the default
}

You can use the information returned to navigate to the created chat.

import { matrix } from 'rn-matrix'
...
// any excluded options will use the defaults
const options = {
  visibility: 'public',
  invite: ['@annie:ditto.chat', '@test:ditto.chat'], // can be empty
  name: 'My Cool New Room',
  room_topic: 'Here\'s a place for us to chat about RnMatrix!'
}
const room = await matrix.createRoom(options)
console.log(room) // { id: <room id>, name: <room name> }

getRooms$

getRooms()

Returns

Behavior subject for the list of all rooms.
We use behavior subjects because when you reference this list, you can use useObservableState from observable-hooks to have it automatically update when events happen.

In order to get the array, call .getValue()

import { matrix } from 'rn-matrix'
import { useObservableState } from 'observable-hooks'
...
const rooms = matrix.getRooms()
const updatingRooms = useObservableState(matrix.getRooms())
console.log(rooms) // BehaviorSubject
console.log(rooms.getValue()) // Array of Chats
console.log(updatingRooms) // This will update when the room list is updated

getRoomById

getRoomById(roomId)

Returns

A Chat class object (yes, I should refactor this to be called a "Room")

A Chat class object has Behavior Subjects that can be used with useObservableState to listen for updates. These can be found in these docs.

For example, if I want to get the chat name:

import { matrix } from 'rn-matrix'
import { useObservableState } from 'observable-hooks'
...
const room = matrix.getRoomById('roomId')
const roomName = useObservableState(room.name$)
console.log(roomName) // Will update if the room name is changed

getRoomsByType$

getRoomsByType$(type: 'direct' | 'invites' | 'groups')

Returns

A Behavior Subject for the list of rooms, filtered by type given.

import { matrix } from 'rn-matrix'
import { useObservableState } from 'observable-hooks'
...
const directChats = useObservableState(matrix.getRoomsByType$('direct'))
console.log(directChats) // Will update if the direct chats are changed

getDirectMessage

getDirectMessage(userId)

Returns

A Chat class object which contains only you and the userID indicated (can be used to simulate canonical DMs)

setRoomName

setRoomName(roomId, name)

Sets the name for the specified room ID. You can also set the name directly with the Chat object (see Chat docs).

leaveRoom

leaveRoom(roomId)

Leaves the room with the given ID.

joinRoom

joinRoom(roomId)

Joins the given room ID (if possible).

rejectInvite

rejectInvite(roomId)

Rejects the invite for a room you were invited to - actually just calls "leaveRoom" behind the scenes.

Messages

deleteMessage

deleteMessage(message)

Deletes a message (View guide)

PropTypeDescription
messageMessageThe message (of type "Message" class) to delete
import {matrix} from 'rn-matrix';
...
matrix.deleteMessage(message);
← Managing MessagesmatrixSdk →
  • Core
    • createClient
    • start
  • Rooms
    • createRoom
    • getRooms$
    • getRoomById
    • getRoomsByType$
    • getDirectMessage
    • setRoomName
    • leaveRoom
    • joinRoom
    • rejectInvite
  • Messages
    • deleteMessage
Docs
Getting Started
Community
Ditto Chat Project
More
GitLab
Copyright © 2020 Annie Elequin