SignalDBus

This module is the main entry point for this library.

To get started, install and set up signal-cli, and make sure it's running in daemon mode, with the dbus interface enabled. Then, as an example, you could use the following code to react with "💀" to every message received from a specific user either via PM or in groups you're a member of:

import Control.Monad (forever, when)
import SignalDBus

reactWithSkull :: Timestamp -> String -> Maybe Group -> SignalConn -> IO Timestamp
reactWithSkull ts n mayG sc =
    case mayG of
        Nothing -> sendMessageReaction "💀" False n ts n sc
        Just g -> sendGroupMessageReaction "💀" False n ts g sc

-- react with 💀 to every message received by a specific user
main :: IO ()
main = do
    let num = "[insert phone number with country code]"
    withConn $ \sc -> do
        n <- getSelfNumber sc
        putStrLn $ "Running on: " ++ show n
        withReceiveMessages sc $ \getMsg -> forever $ do
            getMsg >>= \case
                Receipt _ _ -> return ()
                SyncMessage _ _ _ _ _ -> return ()
                Message ts n g _ _ -> when (n == num) $ do
                    reactWithSkull ts num g sc
                    return ()

    return ()

All of the functions exported may fail with a ClientError if something goes wrong. None of the functions should throw any other exception.

Quite a few of these functions have a scary-looking "UNTESTED" in their documentation. If you end up using any of those, and they work, please tell me so I can remove that disclaimer.

This package aims to provide somewhat direct bindings for all methods described by https://github.com/AsamK/signal-cli/blob/master/man/signal-cli-dbus.5.adoc. In cases where methods are overloaded, this library almost always chooses to implement the more general ones. Some functionality of the dbus interface of signal-cli isn't implemented, as it's either not documented or not often useful; if you require any of that, I'd recommend looking at SignalDBus.Interface.

Opening connections

withConn :: MonadUnliftIO m => (SignalConn -> m a) -> m a

Run an action that requires a signal connection, and return its result

withConnNum :: MonadUnliftIO m => String -> (SignalConn -> m a) -> m a

Like withConn, but you have to manually specify a phone number to use, which is useful if the signal daemon doesn't have a default number. This may not be used with a signal-cli daemon that has a default number configured.

Receiving Messages

withReceiveMessages :: MonadUnliftIO m => SignalConn -> (m ReceivedMessage -> m a) -> m a

Run an action that receives a callback to receive new messages, and return its result. This will not yield messages that were received prior to calling this.

Control interface

These methods are only available if the signal-cli daemon was started in multi-account mode.

link :: MonadIO m => String -> SignalConn -> m String

UNTESTED. Link this as a new device, identified by the given string.

listAccounts :: MonadIO m => SignalConn -> m [String]

List accounts attached to this signal-cli instance

register :: MonadIO m => String -> Bool -> SignalConn -> m ()

UNTESTED. Register this as the primary device for the given number. Set the second argument to True to request voice verification instead of SMS verification.

registerWithCaptcha :: MonadIO m => String -> Bool -> String -> SignalConn -> m ()

UNTESTED. Same as register, but include a Captcha string.

verify

Arguments

:: MonadIO m

=> String

Phone number

-> String

Verification code

-> SignalConn

Connection object

-> m ()

UNTESTED. Verify your phone number after requesting registration via register or registerWithCaptcha

verifyWithPin

Arguments

:: MonadIO m

=> String

Phone number

-> String

Verification code

-> String

Pin

-> SignalConn

Connection object

-> m ()

UNTESTED. Same as verify, but include a registration pin for protected accounts

Account interface

These methods may only be called on a connection object that knows which account to use; that is, either the signal daemon has a default account, and you've used withConn, or it doesn't, and you've used withConnNum.

getContactName :: MonadIO m => String -> SignalConn -> m String

Takes a number, and returns the name of the contact, empty if unknown

getContactNumber :: MonadIO m => String -> SignalConn -> m [String]

Takes a contact name, and returns known numbers, both as strings

getSelfNumber :: MonadIO m => SignalConn -> m String

Returns your own number

isContactBlocked :: MonadIO m => String -> SignalConn -> m Bool

Returns true if you blocked this number

isRegistered :: MonadIO m => [String] -> SignalConn -> m [Bool]

For each given number, returns whether that user is registered on Signal

listNumbers :: MonadIO m => SignalConn -> m [String]

List all known numbers (e.g. group members and senders of received messages)

removePin :: MonadIO m => SignalConn -> m ()

UNTESTED. Removes registration pin protection.

sendEndSessionMessage :: MonadIO m => SignalConn -> m ()

UNTESTED. No idea what this accomplishes, so hmu if you know. It's implemented though

sendMessage

Arguments

:: MonadIO m

=> String

Message content

-> [String]

Paths to attachments. Resolves using the working dir of the signal-cli daemon, not this process

-> [String]

Recipients

-> SignalConn

Connection object

-> m Timestamp

Timestamp of sent message

Sends a message, possibly with attachments, to a number of recipients

sendMessageReaction

Arguments

:: MonadIO m

=> String

Unicode grapheme cluster. Only tested with "😂"

-> Bool

Whether to remove a previously sent reaction instead of adding one

-> String

Author of the message you want to react to

-> Timestamp

Timestamp of message to react to

-> String

Phone numbers of recipient

-> SignalConn

Connection object

-> m Timestamp

Timestamp of reaction

Reacts to a message

sendNoteToSelfMessage

Arguments

:: MonadIO m

=> String

Message

-> [String]

Paths to attachments. Resolves using the working dir of the signal-cli daemon, not this process

-> SignalConn

Connection object

-> m Timestamp

Timestamp of sent message

Sends a message to yourself

sendReadReceipt :: MonadIO m => String -> [Timestamp] -> SignalConn -> m ()

Sends read receipts for the messages with the specified timestamps to the given phone number. These timestamps must belong to messages you received from that number.

sendViewedReceipt :: MonadIO m => String -> [Timestamp] -> SignalConn -> m ()

Sends viewed receipts for the messages with the specified timestamps to the given phone number. This is probably not what you want; sendReadReceipt seems to be the way to go.

sendRemoteDeleteMessage

Arguments

:: MonadIO m

=> Timestamp

Timestamp of message to delete

-> [String]

Recipients

-> SignalConn

Connection object

-> m Timestamp

Timestamp, can be used to identify corresponding replies

Delete one of you own private messages; also deletes them remotely on supported clients (Signal-desktop, Android/IOS apps, ...)

sendTyping :: MonadIO m => String -> Bool -> SignalConn -> m ()

Send updates about whether you're typing to the given number. NOTE: the boolean argument should be False to indicate you're typing, and True to clear the typing state

setContactBlocked :: MonadIO m => String -> Bool -> SignalConn -> m ()

UNTESTED. Sets whether a contact is blocked. This is only done locally, so this just disabled messages from that number from being forwarded via DBus.

setContactName :: a

Not implemented, as the documentation doesn't state the type of the name (probably a String, but I dont feel like testing stuff rn)

deleteContact :: MonadIO m => String -> SignalConn -> m ()

UNTESTED. Probably deletes a contact, given by a phone number, or something.

deleteRecipient :: MonadIO m => String -> SignalConn -> m ()

UNTESTED. Idk what this does, but tell me if you know/have used this.

setExpirationTimer :: (MonadIO m, Integral i) => String -> i -> SignalConn -> m ()

Set seconds until messages to this recipient dissapear (on supported clients). Set to 0 to disable.

setPin :: MonadIO m => String -> SignalConn -> m ()

UNTESTED. Set registration pin to prevent others from registering your number.

submitRateLimitChallenge :: MonadIO m => String -> String -> SignalConn -> m ()

UNTESTED. Idk but seems to be useful for lifting rate limits

updateProfile

Arguments

:: MonadIO m

=> String

Given name

-> String

Family name

-> String

About message

-> String

Emoji for profile

-> String

Avatar file name. Resolves using the working dir of the signal-cli daemon, not this process

-> Bool

True if the avatar should be removed

-> SignalConn

Connection object

-> m ()

Update parts of your profile. You can leave any string field empty to keep the old value.

uploadStickerPack :: MonadIO m => String -> SignalConn -> m String

UNTESTED. Uploads a sticker pack, given by the path to a manifest.json or zip file, and return the URL of the pack.

version :: MonadIO m => SignalConn -> m String

Return version string of signal-cli. This also works for multi-account connections.

createGroup

Arguments

:: MonadIO m

=> String

Group name

-> [String]

Initial members

-> String

Avatar file name. Resolves using the working dir of the signal-cli daemon, not this process

-> SignalConn

Connection object

-> m Group

Group object

Create a group

getGroup :: MonadIO m => ByteString -> SignalConn -> m Group

Get DBus object path for a group, given by its signal-internal binary identifier.

joinGroup :: MonadIO m => String -> SignalConn -> m ()

UNTESTED. Join a group given by an invite link. Behaviour of this depends on properties of the group; see "joinGroup" on https://github.com/AsamK/signal-cli/blob/master/man/signal-cli-dbus.5.adoc (latest commit while writing this: 34cc64f8ce97a63c859bd95faf6783422f14df61)

listGroups :: MonadIO m => SignalConn -> m [(Group, ByteString, String)]

List known groups, represented as (group object, internal identifier, group name)

sendGroupMessage

Arguments

:: MonadIO m

=> String

Message content

-> [String]

Paths to attachments. Resolves using the working dir of the signal-cli daemon, not this process

-> Group

Group in which to send a message

-> SignalConn

Connection object

-> m Timestamp

Timestamp of sent message

Sends a message, possibly with attachments, to a group

sendGroupTyping :: MonadIO m => Group -> Bool -> SignalConn -> m ()

Send updates about whether you're typing to the given group. NOTE: the boolean argument should be False to indicate you're typing, and True to clear the typing state

sendGroupMessageReaction

Arguments

:: MonadIO m

=> String

Unicode grapheme cluster. Only tested with "😂"

-> Bool

Whether to remove a previously sent reaction instead of adding one

-> String

Author of the message you want to react to

-> Timestamp

Timestamp of message to react to

-> Group

Group in which to react

-> SignalConn

Connection object

-> m Timestamp

Timestamp of reaction

Reacts to a message

sendGroupRemoteDeleteMessage

Arguments

:: MonadIO m

=> Timestamp

Timestamp of message to delete

-> Group

Group in which to delete your message

-> SignalConn

Connection object

-> m Timestamp

Timestamp, can be used to identify corresponding replies

Delete one of you own group messages; also deletes them remotely on supported clients (Signal-desktop, Android/IOS apps, ...)

addDevice :: MonadIO m => String -> SignalConn -> m ()

UNTESTED. Add a device that wants to link to this account using a link

getDevice :: MonadIO m => Int64 -> SignalConn -> m ObjectPath

Get DBus object path for a device given by a device ID

listDevices :: MonadIO m => SignalConn -> m [(ObjectPath, Int64, String)]

List devices linked with this account, represented as (object path, device id, device name)

Group interface

getGroupId :: MonadIO m => Group -> SignalConn -> m ByteString

Byte array representing the internal group identifier

getGroupName :: MonadIO m => Group -> SignalConn -> m String

Display name

getGroupDescription :: MonadIO m => Group -> SignalConn -> m String

Description

getGroupIsBlocked :: MonadIO m => Group -> SignalConn -> m Bool

UNTESTED. If true, messages won't be forwarded via DBus

getGroupIsAdmin :: MonadIO m => Group -> SignalConn -> m Bool

Whether this account is a group admin

getGroupMessageExpirationTimer :: MonadIO m => Group -> SignalConn -> m Int

Message expiration timer. 0 if disabled

getGroupMembers :: MonadIO m => Group -> SignalConn -> m [String]

List of group members' phone numbers

getGroupPendingMembers :: MonadIO m => Group -> SignalConn -> m [String]

UNTESTED. List of pending group members; I don't know what this does, but I imagine you're probably looking for getGroupRequestingMembers

getGroupRequestingMembers :: MonadIO m => Group -> SignalConn -> m [String]

List of phone numbers requesting to join the group, if theres an invite link set to require admin approval

getGroupAdmins :: MonadIO m => Group -> SignalConn -> m [String]

List of group admins' phone numbers

getGroupPermissionAddMember :: MonadIO m => Group -> SignalConn -> m String

String representing who has permission to add members (one of ONLY_ADMINS, EVERY_MEMBER)

getGroupPermissionEditDetails :: MonadIO m => Group -> SignalConn -> m String

String representing who has permission to edit group description (one of ONLY_ADMINS, EVERY_MEMBER)

getGroupPermissionSendMessage :: MonadIO m => Group -> SignalConn -> m String

String representing who has permission to send messages (one of ONLY_ADMINS, EVERY_MEMBER)

getGroupInviteLink :: MonadIO m => Group -> SignalConn -> m String

Group invitation link. Empty if disabled

setGroupName :: MonadIO m => String -> Group -> SignalConn -> m ()

Display name

setGroupDescription :: MonadIO m => String -> Group -> SignalConn -> m ()

Description

setGroupAvatar :: MonadIO m => String -> Group -> SignalConn -> m ()

Filename of group avatar. Resolves using the working dir of the signal-cli daemon, not this process

setGroupIsBlocked :: MonadIO m => Bool -> Group -> SignalConn -> m ()

UNTESTED. If true, messages won't be forwarded via DBus

setGroupMessageExpirationTimer :: MonadIO m => Int -> Group -> SignalConn -> m ()

Message expiration timer. 0 to disable

setGroupPermissionAddMember :: MonadIO m => String -> Group -> SignalConn -> m ()

String representing who has permission to add members (one of ONLY_ADMINS, EVERY_MEMBER)

setGroupPermissionEditDetails :: MonadIO m => String -> Group -> SignalConn -> m ()

String representing who has permission to edit group description (one of ONLY_ADMINS, EVERY_MEMBER)

setGroupPermissionSendMessage :: MonadIO m => String -> Group -> SignalConn -> m ()

String representing who has permission to send messages (one of ONLY_ADMINS, EVERY_MEMBER)

groupAddAdmins :: MonadIO m => [String] -> Group -> SignalConn -> m ()

Add admins

groupAddMembers :: MonadIO m => [String] -> Group -> SignalConn -> m ()

Add numbers who are pending members to the group, and other numbers to requesting members list

groupDisableLink :: MonadIO m => Group -> SignalConn -> m ()

Disable group invitation link

groupEnableLink :: MonadIO m => Bool -> Group -> SignalConn -> m ()

Enable group invitation link. If the argument is true, users cannot join directly, but are added to the requesting members list first.

groupQuit :: MonadIO m => Group -> SignalConn -> m ()

Quit the group

groupRemoveAdmins :: MonadIO m => [String] -> Group -> SignalConn -> m ()

Remove admins

groupRemoveMembers :: MonadIO m => [String] -> Group -> SignalConn -> m ()

Remove numbers from the group

groupResetLink :: MonadIO m => Group -> SignalConn -> m ()

Reset the group invitation link

Types

data SignalConn

Opaque connection object, aquired by withConn or withConnNum

data Timestamp

Timestamp, represented as an ms-precision unix timestamp

Instances

Eq Timestamp

Defined in SignalDBus.Types

Methods

(==) :: Timestamp -> Timestamp -> Bool

(/=) :: Timestamp -> Timestamp -> Bool

Ord Timestamp

Defined in SignalDBus.Types

Methods

compare :: Timestamp -> Timestamp -> Ordering

(<) :: Timestamp -> Timestamp -> Bool

(<=) :: Timestamp -> Timestamp -> Bool

(>) :: Timestamp -> Timestamp -> Bool

(>=) :: Timestamp -> Timestamp -> Bool

max :: Timestamp -> Timestamp -> Timestamp

min :: Timestamp -> Timestamp -> Timestamp

Read Timestamp

Defined in SignalDBus.Types

Methods

readsPrec :: Int -> ReadS Timestamp

readList :: ReadS [Timestamp]

readPrec :: ReadPrec Timestamp

readListPrec :: ReadPrec [Timestamp]

Show Timestamp

Defined in SignalDBus.Types

Methods

showsPrec :: Int -> Timestamp -> ShowS

show :: Timestamp -> String

showList :: [Timestamp] -> ShowS

IsVariant Timestamp

Defined in SignalDBus.Types

Methods

toVariant :: Timestamp -> Variant

fromVariant :: Variant -> Maybe Timestamp

IsValue Timestamp

Defined in SignalDBus.Types

Methods

typeOf_ :: Proxy Timestamp -> Type

toValue :: Timestamp -> Value

fromValue :: Value -> Maybe Timestamp

data Device

Opaque object representing a linked device

Instances

Eq Device

Defined in SignalDBus.Types

Methods

(==) :: Device -> Device -> Bool

(/=) :: Device -> Device -> Bool

Read Device

Defined in SignalDBus.Types

Methods

readsPrec :: Int -> ReadS Device

readList :: ReadS [Device]

readPrec :: ReadPrec Device

readListPrec :: ReadPrec [Device]

Show Device

Defined in SignalDBus.Types

Methods

showsPrec :: Int -> Device -> ShowS

show :: Device -> String

showList :: [Device] -> ShowS

IsVariant Device

Defined in SignalDBus.Types

Methods

toVariant :: Device -> Variant

fromVariant :: Variant -> Maybe Device

IsValue Device

Defined in SignalDBus.Types

Methods

typeOf_ :: Proxy Device -> Type

toValue :: Device -> Value

fromValue :: Value -> Maybe Device

data Group

Opaque Group object, aquired by listGroups or getGroup

Instances

Eq Group

Defined in SignalDBus.Types

Methods

(==) :: Group -> Group -> Bool

(/=) :: Group -> Group -> Bool

Ord Group

Defined in SignalDBus.Types

Methods

compare :: Group -> Group -> Ordering

(<) :: Group -> Group -> Bool

(<=) :: Group -> Group -> Bool

(>) :: Group -> Group -> Bool

(>=) :: Group -> Group -> Bool

max :: Group -> Group -> Group

min :: Group -> Group -> Group

Read Group

Defined in SignalDBus.Types

Methods

readsPrec :: Int -> ReadS Group

readList :: ReadS [Group]

readPrec :: ReadPrec Group

readListPrec :: ReadPrec [Group]

Show Group

Defined in SignalDBus.Types

Methods

showsPrec :: Int -> Group -> ShowS

show :: Group -> String

showList :: [Group] -> ShowS

IsVariant Group

Defined in SignalDBus.Types

Methods

toVariant :: Group -> Variant

fromVariant :: Variant -> Maybe Group

IsValue Group

Defined in SignalDBus.Types

Methods

typeOf_ :: Proxy Group -> Type

toValue :: Group -> Value

fromValue :: Value -> Maybe Group

data ReceivedMessage

Received message

Constructors

SyncMessage

Message sent by a linked device to someone else

Fields

• Timestamp

  When this message was sent

• String

  Message sender (TODO: always yourself?)

• (Maybe Group)

  If sent in a group, corresponding group object

• String

  Message text

• [String]

  Paths to stored attachments

Receipt

Read receipt sent by someone else in response to one of your messages

Fields

• Timestamp

  Which message was read

• String

  Phone number of the receipt sender

Message

Message sent to you by someone else

Fields

• Timestamp

  When this message was sent

• String

  Message sender

• (Maybe Group)

  If sent in a group, corresponding group object

• String

  Message text

• [String]

  Paths to stored attachments

Instances

Eq ReceivedMessage

Defined in SignalDBus.Types

Methods

(==) :: ReceivedMessage -> ReceivedMessage -> Bool

(/=) :: ReceivedMessage -> ReceivedMessage -> Bool

Ord ReceivedMessage

Defined in SignalDBus.Types

Methods

compare :: ReceivedMessage -> ReceivedMessage -> Ordering

(<) :: ReceivedMessage -> ReceivedMessage -> Bool

(<=) :: ReceivedMessage -> ReceivedMessage -> Bool

(>) :: ReceivedMessage -> ReceivedMessage -> Bool

(>=) :: ReceivedMessage -> ReceivedMessage -> Bool

max :: ReceivedMessage -> ReceivedMessage -> ReceivedMessage

min :: ReceivedMessage -> ReceivedMessage -> ReceivedMessage

Read ReceivedMessage

Defined in SignalDBus.Types

Methods

readsPrec :: Int -> ReadS ReceivedMessage

readList :: ReadS [ReceivedMessage]

readPrec :: ReadPrec ReceivedMessage

readListPrec :: ReadPrec [ReceivedMessage]

Show ReceivedMessage

Defined in SignalDBus.Types

Methods

showsPrec :: Int -> ReceivedMessage -> ShowS

show :: ReceivedMessage -> String

showList :: [ReceivedMessage] -> ShowS