siggy 1.4.0

Terminal-based Signal messenger client with vim keybindings
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

# signal-cli Protocol

siggy communicates with signal-cli using
[JSON-RPC 2.0](https://www.jsonrpc.org/specification) over stdin/stdout. signal-cli
is spawned as a child process in `jsonRpc` mode.

## Starting signal-cli

signal-cli is launched with:

```sh
signal-cli -a +15551234567 jsonRpc
```

This starts signal-cli in JSON-RPC mode, reading requests from stdin and writing
responses/notifications to stdout. Each message is a single JSON line.

## Request format

Requests sent from siggy to signal-cli:

```json
{
    "jsonrpc": "2.0",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "method": "send",
    "params": {
        "recipient": ["+15551234567"],
        "message": "Hello!"
    }
}
```

Each request has a unique UUID `id` for response correlation.

## Response format

Responses from signal-cli for RPC calls:

```json
{
    "jsonrpc": "2.0",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "result": { ... }
}
```

Or on error:

```json
{
    "jsonrpc": "2.0",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "error": {
        "code": -1,
        "message": "error description"
    }
}
```

## Notification format

Notifications are unsolicited JSON-RPC requests from signal-cli (no matching
outbound request). They have a `method` field but no `id`:

```json
{
    "jsonrpc": "2.0",
    "method": "receive",
    "params": {
        "envelope": {
            "source": "+15559876543",
            "sourceDevice": 1,
            "timestamp": 1700000000000,
            "dataMessage": {
                "message": "Hey there!",
                "timestamp": 1700000000000
            }
        }
    }
}
```

## Methods used

### Outbound (siggy -> signal-cli)

| Method | Purpose |
|---|---|
| `send` | Send a message (also used for edits via `editTimestamp` param) |
| `listContacts` | Request the contact address book |
| `listGroups` | Request the list of groups |
| `sendSyncRequest` | Request a sync from the primary device |
| `sendReaction` | Send an emoji reaction to a message |
| `remoteDelete` | Delete a message for all recipients |
| `sendTypingIndicator` | Send typing started/stopped indicator |
| `sendReceipt` | Send a read receipt for one or more messages |
| `updateGroup` | Create/rename group, add/remove members |
| `quitGroup` | Leave a group |
| `block` | Block a contact or group |
| `unblock` | Unblock a contact or group |
| `setExpiration` | Set disappearing message timer |
| `updateProfile` | Update own Signal profile (name, about, emoji) |
| `listIdentities` | List known identity keys for contacts |
| `trust` | Trust a contact's identity key |
| `sendMessageRequestResponse` | Accept or delete a message request |

### Inbound notifications (signal-cli -> siggy)

| Method | Purpose | Maps to |
|---|---|---|
| `receive` | Incoming message | `SignalEvent::MessageReceived` |
| `receiveTyping` | Typing indicator | `SignalEvent::TypingIndicator` |
| `receiveReceipt` | Delivery/read receipt | `SignalEvent::ReceiptReceived` |

Incoming `receive` envelopes may also contain:

| Envelope field | Purpose | Maps to |
|---|---|---|
| `dataMessage.reaction` | Incoming reaction | `SignalEvent::ReactionReceived` |
| `dataMessage.remoteDelete` | Remote delete request | `SignalEvent::RemoteDeleteReceived` |
| `dataMessage.quote` | Quoted reply metadata | `quote` field on `SignalMessage` |
| `editMessage` | Edited message | `SignalEvent::EditReceived` |
| `syncMessage.sentMessage` | Outgoing sync (own messages from other devices) | Same as above, with `is_outgoing = true` |
| `syncMessage.readMessages` | Read sync from other devices | `SignalEvent::ReadSyncReceived` |
| `dataMessage.sticker` | Sticker message | Body set to `[Sticker: emoji]` |
| `dataMessage.textStyles` / `bodyRanges` | Text formatting (bold, italic, etc.) | `text_styles` field on `SignalMessage` |
| `dataMessage.expiresInSeconds` | Disappearing message timer | `expires_in_seconds` on `SignalMessage` |
| `dataMessage.isViewOnce` | View-once message flag | Body set to `[View-once message]` |
| `callMessage` | Missed call notification | `SignalEvent::SystemMessage` |

## Parsing logic

The stdout reader in `SignalClient` determines the message type by checking
which fields are present:

1. If `method` is present -> it's a notification, parse based on method name
2. If `id` and `result`/`error` are present -> it's a response, look up the
   method via `pending_requests[id]` and parse accordingly
3. Unknown methods are logged and discarded

## Sync messages

Messages sent from the primary device arrive as sync messages. They are
identified by having `is_outgoing = true` in the parsed `SignalMessage`.
The `destination` field indicates the recipient, and the message is routed
to the appropriate conversation.