signal-bot/DOCS-signal-envelopes.md

# Signal envelope shapes

Reference for the two JSON frames `signal-cli-rest-api` pushes down
`ws://…/v1/receive/{number}`. `signal_bot/models.py` flattens both into one
`IncomingMessage`; these are the shapes it flattens.

## From another account: `dataMessage`

```json
{
  "envelope": {
    "source": "NAME",
    "sourceNumber": "PHONE_NUMBER",
    "sourceUuid": "SOURCE_ID",
    "sourceName": "USER_DEFINED_NAME",
    "sourceDevice": 69,
    "timestamp": 1719177917717,
    "dataMessage": {
      "timestamp": 1719177917717,
      "message": "MESSAGE_CONTENT",
      "expiresInSeconds": 0,
      "viewOnce": false,
      "sticker": { "packId": "166dd1b5…", "stickerId": 6 },
      "groupInfo": { "groupId": "ID_OF_GROUP", "type": "DELIVER" }
    }
  },
  "account": "BOT_ACCOUNT_PHONE_NUMBER"
}
```

## A message with an attachment

Captured from the live API on 2026-08-30 with `LOG_LEVEL=DEBUG`, which makes
the dispatcher log each frame's shape (keys and types, never values -- see
`signal_bot/envelope_shape.py`). This is a caption-less PNG posted in the real
group, reproduced exactly as the logger described it:

```
{account: str, envelope: {
  dataMessage: {
    attachments: [{caption: null, contentType: 'image/png', filename: null,
                   height: int, id: str, size: int, uploadTimestamp: int,
                   width: int} x1],
    expiresInSeconds: int,
    groupInfo: {groupId: str, groupName: str, revision: int, type: 'DELIVER'},
    isExpirationUpdate: bool,
    message: null,
    timestamp: int,
    viewOnce: bool},
  serverDeliveredTimestamp: int, serverReceivedTimestamp: int,
  source: str, sourceDevice: int, sourceName: str,
  sourceNumber: str, sourceUuid: str, timestamp: int}}
```

Three things this settles, none of which were guessable:

- `attachments` is a list of objects and the type lives in `contentType`. That
  is what `models._attachments` reads and what `counting.media_kind` maps.
- **A caption-less photo sends `message: null`**, not `""` and not an absent
  key. Before 0.1.0 `should_count` ended in `bool(message.text)`, so every one
  of these was silently worth nothing.
- Read them off the *resolved* payload from `_payload()`, never off
  `envelope["dataMessage"]` -- see "The trap this caused" below.

Fields nothing reads yet, recorded so the next person does not have to capture
them again: `expiresInSeconds`, `isExpirationUpdate`, `viewOnce`,
`groupInfo.groupName`, `groupInfo.revision`, and the attachment's `caption`,
`filename`, `width`, `height`, `size` and `uploadTimestamp`.

**Open question, deliberately not assumed.** `caption` is a field on the
attachment, and it was `null` here because this photo had none. Whether a
photo *with* a caption puts the text in `message` or in `attachments[].caption`
has not been observed yet. `char_len` currently measures `message` only, so if
it turns out to be the latter, captioned photos are recording a length of 0.
Leave `LOG_LEVEL=DEBUG` on and watch for `caption: str` to settle it.

## A reply carries `quote` -- with its own attachments

Also captured live, on 2026-08-30. This is a *text* reply to somebody else's
photo:

```
dataMessage: {
  expiresInSeconds: int, isExpirationUpdate: bool, viewOnce: bool,
  groupInfo: {groupId: str, groupName: str, revision: int, type: 'DELIVER'},
  message: str,
  quote: {
    attachments: [{contentType: 'image/jpeg', filename: str,
                   thumbnail: {caption: null, contentType: 'image/jpeg',
                               filename: str, height: int, id: str, size: int,
                               uploadTimestamp: int, width: int}} x1],
    author: str, authorNumber: str, authorUuid: str, id: int, text: str},
  timestamp: int}
```

**`quote` has its own `attachments` array**, holding the *quoted* message's
media. There is no top-level `attachments` here at all, because the replier
sent only text.

So anything looking for attachments must read them off the top level of the
resolved payload and nowhere else. Searching the payload for an `attachments`
key would credit the replier with a photo somebody else posted -- and in a
group where people reply to photos constantly, that inflates one number
without ever looking wrong. It is the same wrong-nesting-level mistake that
once made the bot ignore its own stickers.

`quote.text` is the quoted message's body, and is not read for the same
reason: it is somebody else's message, already counted when they sent it.
`tests/test_models.py::test_a_quoted_photo_is_not_the_replier_s_photo` pins
this against the exact frame above.

## Somebody changed the membership: `groupInfo.type` is `UPDATE`

The only frame that names *who* added the bot to a group, which is what
`signal_bot/trust.py` needs. It carries no `message` at all, so it counts
toward nothing and answers nothing; `source`/`sourceNumber` is the person
who made the change. Captured live on 2026-08-29:

```json
{
  "envelope": {
    "source": "+48123456789",
    "sourceNumber": "+48123456789",
    "sourceUuid": "b1c2d3e4-…",
    "sourceName": "kuhy",
    "sourceDevice": 1,
    "timestamp": 1788006851503,
    "dataMessage": {
      "timestamp": 1788006851503,
      "message": null,
      "groupInfo": { "groupId": "Y29uZmlnLWdy…", "groupName": "testbot", "type": "UPDATE" }
    }
  },
  "account": "+420111222333"
}
```

Note `source` here is a **phone number**, not the display name this document
used to show for `dataMessage`. Both spellings have been observed, which is
why `models.py` reads the sender's number from `sourceNumber` and nothing
trusts `source`.

## From the bot's own account: `syncMessage.sentMessage`

When the account is deployed as a *linked device*, its own outgoing messages
come back as sync messages. Same fields, one level deeper.

> **This deployment never receives them.** The bot registers its own number as
> its own primary device and has no linked devices, so Signal sends it no copy
> of its own traffic. The consequence to know before you try to test anything:
> the bot **cannot self-trigger a command**. Posting `!cat` from the bot's
> number into a group does nothing whatsoever — a human has to type it, and
> `journalctl --user -u signal-bot.service` showing `running command …` is how
> you confirm it landed. The parsing below stays because the linked-device
> deployment is still supported, not because it fires here.

```json
{
  "envelope": {
    "sourceUuid": "SOURCE_ID",
    "sourceName": "USER_DEFINED_NAME",
    "timestamp": 1719177728639,
    "syncMessage": {
      "sentMessage": {
        "destination": "DEST_NAME",
        "destinationNumber": "DEST_PHONE_NUMBER",
        "timestamp": 1719177728639,
        "message": "MESSAGE_CONTENT",
        "sticker": { "packId": "166dd1b5…", "stickerId": 6 },
        "groupInfo": { "groupId": "ID_OF_GROUP", "type": "DELIVER" }
      }
    }
  },
  "account": "BOT_ACCOUNT_PHONE_NUMBER"
}
```

## The trap this caused

The original bot read `envelope.dataMessage.sticker` even when the frame was a
`syncMessage`. Its own stickers therefore never matched the sticker filter and
were counted as messages. Four consecutive commits (`f1931b8`, `b325126`,
`62352e5`, `d35aa59`) fought the symptom.

`models.py` resolves the payload *first* — `dataMessage` or
`syncMessage.sentMessage` — and reads `sticker`, `reaction`, `message` and
`groupInfo` off whichever it found. `tests/test_models.py` asserts both shapes.

## No `groupInfo` means a direct message

A frame without `groupInfo` arrived in a one-to-one conversation. A linked
device would receive every one of those on the account, so `counting.watched_group`
rejects them explicitly rather than relying on a falsy comparison. See the
`scoping` scenario in `fake_signal/scenarios/`.

## Frames the bot ignores

Receipts, typing indicators and anything else with no `dataMessage` and no
`syncMessage.sentMessage` parse to `None` and are dropped.