Skip to content
A two-way puppeted Matrix bridge for Apple iMessage / Messages
JavaScript Shell
Branch: master
Clone or download
nr23730 Merge pull request #29 from nr23730/receipts
Read Receipts iMessage -> Matrix
Latest commit 82fe7fe Aug 17, 2019


This is a Matrix bridge for Apple iMessage


You need a Mac with a functional, already authenticated.

The bridge uses applescripts for outbound messages and watches ~/Library/Containers/ for incoming messages, parsed with ichat2json.


clone this repo

cd into the directory

run npm install

special for macOS Mojave and later

Since Mojave the System Integrity Protection (SIP) prevents ichat2json from reading incoming messages. There are two options:

a) Allow access for ichat2json (recommeded)

Go to "System settings" -> "Data protection" -> "Full disk access" and add ichat2json from matrix-puppet-imagessage/bin/

b) Disable SIP (not recommended)

Boot to recovery using CMD+R, open terminal, type csrutil disable and reboot.


Copy config.sample.json to config.json and update it to match your setup

register the app service

Generate an imessage-registration.yaml file with node index.js -r -u "http://your-bridge-server:8090"

Note: The 'registration' setting in the config.json needs to set to the path of this file. By default, it already is.

Copy this imessage-registration.yaml file to your home server, then edit it, setting its url to point to your bridge server. e.g. url: ''

Edit your homeserver.yaml file and update the app_service_config_files with the path to the imessage-registration.yaml file.

Launch the bridge with node index.js.

Restart your HS.

Discussion, Help and Support

Join us in the Matrix Puppet Bridge room


  • Be able to originate conversations from the Matrix side.
You can’t perform that action at this time.